@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

自动发布 (CI/CD)

项目已配置 GitHub Actions 实现全自动版本管理和 npm 发布。

配置步骤

1. 获取 npm 访问令牌

1. 登录 npmjs.com
2. 右上角头像 → Access Tokens → Generate New Token
3. 选择 Automation 类型
4. 复制 Token（只显示一次）

2. 配置 GitHub Secrets

1. 进入仓库 Settings → Secrets and variables → Actions
2. 点击 New repository secret
3. 添加：
   • Name: NPM_TOKEN
   • Value: 上一步获取的 token

3. 确认 npm 组织权限

确保你的 npm 账号拥有 @basic-genomics 组织的发布权限。首次发布需手动执行：

npm login
yarn build
npm publish --access public

发布流程

配置完成后，发布流程全自动：

提交代码到 main 分支（遵循 Conventional Commits）
        ↓
release-please 自动创建 Release PR
        ↓
合并 PR → 自动创建 GitHub Release
        ↓
自动发布到 npm

Commit 规范

| 格式 | 版本变更 | 示例 | | ------------------ | --------------------- | ------------------------- | | feat: xxx | Minor (1.2.0 → 1.3.0) | feat: 添加簇追踪功能 | | fix: xxx | Patch (1.2.0 → 1.2.1) | fix: 修复上下文菜单定位 | | feat!: xxx | Major (1.2.0 → 2.0.0) | feat!: 重构 API 接口 | | chore/docs/style | 不触发发布 | docs: 更新 README |

手动测试发布

在 GitHub Actions 中可手动触发 dry-run 测试：

1. 仓库 → Actions → Publish to npm
2. 点击 Run workflow
3. 勾选 是否仅测试发布流程

项目结构

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 | 重试回调 | | treeData | TreeData | 进化树数据，传入时显示进化树 Tab | | treeDefaultClusterId | string \| number | 进化树默认高亮的簇 ID | | showTreeTab | boolean | 是否显示进化树 Tab（即使没有 treeData） | | treeLoading | boolean | 进化树正在加载中，显示加载状态 |

国际化

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

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

License

MIT