@basic-genomics/hivtrace-viz

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

功能特性

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

安装

``bash
npm install @basic-genomics/hivtrace-viz


或


yarn add @basic-genomics/hivtrace-viz
`

使用方式

$3

`tsx
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 (
data={analysisData}
options={{
threshold: 0.015,
expand: ["cluster_1"],
}}
customContextMenuItems={customMenuItems}
onCustomMenuItemClick={handleMenuClick}
onReady={() => console.log("可视化已就绪")}
error={fetchError?.message}
/>
);
}
`

$3

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

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

$3

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

`

开发指南

$3

- Node.js >= 18
- Yarn 1.22+

$3

`bash


安装依赖

yarn install

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

yarn dev
`

开发服务器启动后：

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

$3

`bash


完整构建（推荐）

yarn build

分步构建

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

$3

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

`bash


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 缓存并重启：

`bash
rm -rf node_modules/.vite
yarn dev
`

3. 刷新浏览器

重要提示：

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

验证 npm link 状态：

`bash
ls -la node_modules/@basic-genomics/hivtrace-viz


应显示：xxx -> ../../../hivtrace-viz


`

自动发布 (CI/CD)

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

$3

#### 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 组织的发布权限。首次发布需手动执行：

`bash
npm login
yarn build
npm publish --access public
`

$3

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

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

$3

| 格式 | 版本变更 | 示例 |
| ------------------ | --------------------- | ------------------------- |
| 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 |

$3

在 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