@basic-genomics/hivtrace-viz 1.1.3 → 1.1.5

package/README.md

@@ -24,19 +24,33 @@ yarn add @basic-genomics/hivtrace-viz
 
 ```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 (
     <HivtraceViz
       data={analysisData}
       options={{
-        enableClusterTracking: true,
         threshold: 0.015,
         expand: ['cluster_1']
       }}
-      onTrackCluster={(clusterInfo, networkInfo) => {
-        console.log('跟踪簇:', clusterInfo);
-      }}
+      customContextMenuItems={customMenuItems}
+      onCustomMenuItemClick={handleMenuClick}
       onReady={() => console.log('可视化已就绪')}
       error={fetchError?.message}
     />
@@ -103,19 +117,42 @@ yarn build:vite   # Vite 插件
 yarn build:embed  # 嵌入资源
 ```
 
-### 测试
+### 本地调试（与宿主应用联调）
 
-在宿主应用中测试：
+使用 `npm link` 进行本地开发调试：
 
 ```bash
-# 1. 在 hivtrace-viz 目录构建
-yarn build
+# 1. 在 hivtrace-viz 目录执行
+npm link
 
-# 2. 在宿主应用目录
-yarn add file:../hivtrace-viz-github
+# 2. 在宿主应用目录执行
+npm link @basic-genomics/hivtrace-viz
+```
 
-# 3. 启动宿主应用
-yarn dev
+**开发流程：**
+
+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
 ```
 
 ## 项目结构
@@ -146,8 +183,10 @@ hivtrace-viz/
 | `options` | `HivtraceVizOptions` | 配置选项 |
 | `error` | `string` | 错误信息（API 错误时传入） |
 | `loadingState` | `ReactNode \| null` | 自定义加载态，`null` 禁用 |
-| `onTrackCluster` | `(info, data) => void` | 簇追踪回调 |
+| `customContextMenuItems` | `CustomContextMenuItem[]` | 自定义上下文菜单项 |
+| `onCustomMenuItemClick` | `(itemId, clusterInfo) => void` | 自定义菜单项点击回调 |
 | `onReady` | `() => void` | 渲染完成回调 |
+| `onRetry` | `() => void` | 重试回调 |
 
 ## 国际化