波形分析组件项目架构

项目概览

这是一个基于 Vue 3、TypeScript 和 D3.js 的响应式波形可视化组件库，面向大规模数据集提供高性能的 SVG 波形渲染、缩放和悬浮取点能力。

技术栈: Vue 3、TypeScript、D3.js、Vite
包管理器: pnpm
测试: Vitest、Vue Test Utils

目录结构

src/
├── components/
│   ├── WaveformChart.vue       # 主波形图组件
│   ├── waveform.ts             # 数据规范化兼容入口
│   ├── data/types.ts           # 组件内部数据类型入口
│   ├── interaction/
│   │   └── WaveformTooltip.vue # 悬浮提示
│   ├── rendering/
│   │   └── WaveformTrack.vue   # 单轨道 SVG 渲染
│   ├── core/                   # 常量和组件核心类型
│   └── WaveformChart.test.ts   # 组件与数据测试
├── core/                       # 数据规范化、可见域裁剪和保峰降采样
├── types/                      # 公开数据和图表类型
├── utils/                      # 域、格式化和几何工具
├── data/                       # 示例波形数据
└── App.vue                     # Demo 应用

分层架构

外部 WaveformData
        │
        ▼
normalizeWaveformData / normalizeWaveformSeries
        │
        ▼
不可变数据缓存 / 坐标域元数据
        │
        ▼
WaveformChart
  ├─ chartSeries / trackLayouts
  ├─ D3 scales、坐标轴和可见域降采样路径
  ├─ 独立或共享模式的 zoom behavior
  ├─ hover 最近点与 WaveformTooltip
  └─ 受控采样点标注与自动布局
        │
        ▼
WaveformTrack（每个 series 一条 SVG 轨道）

核心组件

WaveformChart

WaveformChart 负责数据归一化后的布局、坐标轴、路径、缩放和跨轨道 hover 协调。

支持三种显示模式：

independent: 每个波形独立坐标和缩放
separated: 波形垂直堆叠，共享 X 轴
compact: 多个波形在紧凑布局中展示

叠加曲线由独立的 overlayMode 控制 Y 轴：single-axis 共享一个值轴， multi-axis 最多使用四个值轴，超出的曲线复用第 4 轴。

公开输入包括 data、显示模式、尺寸、标签、颜色、tooltip、缩放、时间单位、帧号和受控标注状态；公开事件包括 point-hover、zoom-change 以及标注 CRUD 生命周期事件。

标注只保存 seriesId 与 x/y 数据坐标，渲染时根据当前轨道比例尺重新投影。新增支持工具模式和绘图区任意位置右键快捷创建；创建后的标注通过连接线绑定到对应的数据坐标，已有标注通过右键菜单编辑或删除。

WaveformTrack

轨道组件渲染网格、坐标轴、端点标签、波形路径、帧号和 hover 十字线。独立模式下，轨道创建自己的透明交互层；共享模式下由图表创建覆盖整个绘图区的交互层。

WaveformTooltip

根据当前轨道或共享 X 坐标显示最近数据点、系列名称、单位和格式化时间。tooltip 不持有数据状态，由 WaveformChart 通过 props 控制显示位置和内容。

WaveformAnnotationLayer

标注层使用 SVG 圆点、箭头、矩形和多行文本渲染标注，不依赖图表库私有 DOM。布局按实际轨道尺寸计算，并使用确定性的候选偏移避让相邻文字框；无效标注会被忽略但不会从受控数组中删除。

X、Y 轴在显示域最大绝对值小于 0.01 或大于等于 100 时使用共享科学计数指数；刻度固定保留两位缩放值，倍率以 E±NN 独立显示在轴末端。X 轴按当前时间单位换算后判断，多 Y 轴分别计算。tooltip 和标注编辑器使用各自的普通十进制格式。所有格式化仅作用于展示层，受控数据与比例尺仍使用原始数值。标注框候选位置按上、下、右、左及四个对角方向排序，优先垂直布局并按轨道独立执行碰撞避让。

数据流

normalizeWaveformData 将 samples 或 points 输入转换为有序有限点。
normalizeWaveformSeries 为多通道数据提供稳定 ID，并过滤空通道。
数据引用变化时缓存每个通道的有序点和 X/Y 域。
WaveformChart 截取可见域，并按像素桶保留首点、末点和 Y 极值后生成 SVG path。
D3 zoom 更新比例尺变换并发出 zoom-change，pointer move 仍基于原始点更新 hover。

内部时间坐标始终使用秒；timeUnit 只影响轴、端点和 tooltip 的显示格式。

设计约束

使用 shallowRef 保存 D3 行为和 ResizeObserver，避免深层响应式开销。
缩放行为只由 zoomable、显示模式、绘图区尺寸和通道数决定。
父组件通过 props 提供不可变数据；只有替换 data 引用才会刷新内部缓存。
空数据和非法数据必须渲染明确的空状态，而不是创建无效 SVG path。

测试与验证

WaveformChart.test.ts 覆盖数据规范化、空数据、多通道布局、坐标轴、显示模式、hover、 tooltip、缩放和响应式尺寸变化。完成改动后运行：

pnpm test
pnpm typecheck
pnpm lint
pnpm build

5.2 KiB Raw Blame History Unescape Escape