@basic-genomics/hivtrace-viz

HIV-TRACE 分子传播网络可视化组件，支持 React 集成和 Vite 开发服务器。

功能特性

• 🔬 HIV 分子传播网络可视化
• ⚛️ React 组件封装
• 🔌 Vite 插件支持
• 🌐 国际化支持（中文/英文）
• 📦 支持 iframe 嵌入模式

安装

npm install @basic-genomics/hivtrace-viz
# 或
yarn add @basic-genomics/hivtrace-viz

使用方式

React 组件

import { HivtraceViz } from '@basic-genomics/hivtrace-viz/react';
import type { CustomContextMenuItem, ClusterInfo } from '@basic-genomics/hivtrace-viz/react';

function App() {
  // 自定义上下文菜单项
  const customMenuItems: CustomContextMenuItem[] = [
    {
      id: 'track-cluster',
      label: '追踪此簇',
      icon: 'fa-crosshairs',
    },
  ];

  const handleMenuClick = (itemId: string, clusterInfo: ClusterInfo) => {
    if (itemId === 'track-cluster') {
      console.log('追踪簇:', clusterInfo);
    }
  };

  return (
    <HivtraceViz
      data={analysisData}
      options={{
        threshold: 0.015,
        expand: ['cluster_1']
      }}
      customContextMenuItems={customMenuItems}
      onCustomMenuItemClick={handleMenuClick}
      onReady={() => console.log('可视化已就绪')}
      error={fetchError?.message}
    />
  );
}

Vite 插件

// vite.config.ts
import { hivtraceVizPlugin } from '@basic-genomics/hivtrace-viz/vite';

export default defineConfig({
  plugins: [
    hivtraceVizPlugin({
      base: '/hivtrace-viz' // 可选，默认 '/hivtrace-viz'
    })
  ]
});

iframe 嵌入

<iframe 
  src="/hivtrace-viz/index.html" 
  style="width: 100%; height: 600px; border: none;">
</iframe>

开发指南

环境要求

• Node.js >= 18
• Yarn 1.22+

开发模式

# 安装依赖
yarn install

# 启动开发服务器（热更新 + 预览页面）
yarn dev

开发服务器启动后：

• 自动打开 http://localhost:8080/preview.html
• 支持核心库热更新
• 支持 embed 模板热更新

生产构建

# 完整构建（推荐）
yarn build

# 分步构建
yarn build:core   # 核心可视化库
yarn build:react  # React 组件
yarn build:vite   # Vite 插件
yarn build:embed  # 嵌入资源

本地调试（与宿主应用联调）

使用 npm link 进行本地开发调试：

# 1. 在 hivtrace-viz 目录执行
npm link

# 2. 在宿主应用目录执行
npm link @basic-genomics/hivtrace-viz

开发流程：

1. 修改 hivtrace-viz 代码后，运行相应的构建命令：

   • 修改 src/react/*.tsx → npm run build:react
   • 修改 template/embed.html → npm run build:embed
   • 修改 src/*.js → npm run build:core

2. 清除宿主应用的 Vite 缓存并重启：

   rm -rf node_modules/.vite
   yarn dev

3. 刷新浏览器

重要提示：

• npm link 创建的是 symlink，但 Vite 会缓存模块
• 每次修改 hivtrace-viz 代码后需要重新构建对应部分
• 需要删除 Vite 缓存或重启 dev server才能看到更新

验证 npm link 状态：

ls -la node_modules/@basic-genomics/hivtrace-viz
# 应显示：xxx -> ../../../hivtrace-viz

项目结构

hivtrace-viz/
├── src/
│   ├── *.js              # 核心可视化逻辑
│   ├── locales/          # 国际化文件
│   ├── react/            # React 组件
│   └── vite-plugin/      # Vite 插件
├── template/
│   └── embed.html        # 嵌入模板
├── dist/                 # 构建产物
│   ├── hivtrace.js       # 核心库
│   ├── hivtrace.zh.js    # 中文版本
│   ├── react/            # React 组件
│   ├── vite-plugin/      # Vite 插件
│   └── embed/            # 嵌入资源
└── preview.html          # 开发预览

Props API

| 属性 | 类型 | 说明 | |------|------|------| | data | HivtraceVizData | 分析数据 | | options | HivtraceVizOptions | 配置选项 | | error | string | 错误信息（API 错误时传入） | | loadingState | ReactNode \| null | 自定义加载态，null 禁用 | | customContextMenuItems | CustomContextMenuItem[] | 自定义上下文菜单项 | | onCustomMenuItemClick | (itemId, clusterInfo) => void | 自定义菜单项点击回调 | | onReady | () => void | 渲染完成回调 | | onRetry | () => void | 重试回调 |

国际化

语言在构建时确定。默认生成中文版本。

• zh-CN - 简体中文（默认）
• en-US - English

License

MIT