120 lines
4.9 KiB
Markdown
120 lines
4.9 KiB
Markdown
|
# 波形分析组件项目架构
|
|||
|
|
|
|||
|
|
## 项目概览
|
|||
|
|
|
|||
|
|
这是一个基于 Vue 3、TypeScript 和 D3.js 的响应式波形可视化组件库，面向大规模数据集提供高性能的 SVG 波形渲染、缩放和悬浮取点能力。
|
|||
|
|
|
|||
|
|
- **技术栈**: Vue 3、TypeScript、D3.js、Vite
|
|||
|
|
- **包管理器**: pnpm
|
|||
|
|
- **测试**: Vitest、Vue Test Utils
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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 应用
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 分层架构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
外部 WaveformData
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
normalizeWaveformData / normalizeWaveformSeries
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
不可变数据缓存 / 坐标域元数据
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
WaveformChart
|
|||
|
|
├─ chartSeries / trackLayouts
|
|||
|
|
├─ D3 scales、坐标轴和可见域降采样路径
|
|||
|
|
├─ 独立或共享模式的 zoom behavior
|
|||
|
|
├─ hover 最近点与 WaveformTooltip
|
|||
|
|
└─ 受控采样点标注与自动布局
|
|||
|
|
│
|
|||
|
|
▼
|
|||
|
|
WaveformTrack（每个 series 一条 SVG 轨道）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 核心组件
|
|||
|
|
|
|||
|
|
### WaveformChart
|
|||
|
|
|
|||
|
|
`WaveformChart` 负责数据归一化后的布局、坐标轴、路径、缩放和跨轨道 hover 协调。
|
|||
|
|
|
|||
|
|
支持三种显示模式：
|
|||
|
|
|
|||
|
|
- `independent`: 每个波形独立坐标和缩放
|
|||
|
|
- `separated`: 波形垂直堆叠，共享 X 轴
|
|||
|
|
- `compact`: 多个波形在紧凑布局中展示
|
|||
|
|
|
|||
|
|
公开输入包括 `data`、显示模式、尺寸、标签、颜色、tooltip、缩放、时间单位、帧号和
|
|||
|
|
受控标注状态；公开事件包括 `point-hover`、`zoom-change` 以及标注 CRUD 生命周期事件。
|
|||
|
|
|
|||
|
|
标注只保存 `seriesId` 与 `x/y` 数据坐标，渲染时根据当前轨道比例尺重新投影。新增支持
|
|||
|
|
工具模式和绘图区任意位置右键快捷创建；创建后的标注通过连接线绑定到对应的数据坐标，已有标注通过右键菜单编辑或删除。
|
|||
|
|
|
|||
|
|
### WaveformTrack
|
|||
|
|
|
|||
|
|
轨道组件渲染网格、坐标轴、端点标签、波形路径、帧号和 hover 十字线。独立模式下，
|
|||
|
|
轨道创建自己的透明交互层；共享模式下由图表创建覆盖整个绘图区的交互层。
|
|||
|
|
|
|||
|
|
### WaveformTooltip
|
|||
|
|
|
|||
|
|
根据当前轨道或共享 X 坐标显示最近数据点、系列名称、单位和格式化时间。tooltip 不
|
|||
|
|
持有数据状态，由 `WaveformChart` 通过 props 控制显示位置和内容。
|
|||
|
|
|
|||
|
|
### WaveformAnnotationLayer
|
|||
|
|
|
|||
|
|
标注层使用 SVG 圆点、箭头、矩形和多行文本渲染标注，不依赖图表库私有 DOM。布局按实际
|
|||
|
|
轨道尺寸计算，并使用确定性的候选偏移避让相邻文字框；无效标注会被忽略但不会从受控
|
|||
|
|
数组中删除。
|
|||
|
|
|
|||
|
|
Y 轴只在轴域最大绝对值小于 `0.01` 或大于等于 `100` 时使用共享科学计数指数；tooltip 和标注编辑器使用各自的普通十进制格式。所有格式化仅作用于展示层，受控数据与比例尺仍使用原始数值。
|
|||
|
|
标注框候选位置按上、下、右、左及四个对角方向排序，优先垂直布局并按轨道独立执行碰撞避让。
|
|||
|
|
|
|||
|
|
## 数据流
|
|||
|
|
|
|||
|
|
1. `normalizeWaveformData` 将 samples 或 points 输入转换为有序有限点。
|
|||
|
|
2. `normalizeWaveformSeries` 为多通道数据提供稳定 ID，并过滤空通道。
|
|||
|
|
3. 数据引用变化时缓存每个通道的有序点和 X/Y 域。
|
|||
|
|
4. `WaveformChart` 截取可见域，并按像素桶保留首点、末点和 Y 极值后生成 SVG path。
|
|||
|
|
5. D3 zoom 更新比例尺变换并发出 `zoom-change`，pointer move 仍基于原始点更新 hover。
|
|||
|
|
|
|||
|
|
内部时间坐标始终使用秒；`timeUnit` 只影响轴、端点和 tooltip 的显示格式。
|
|||
|
|
|
|||
|
|
## 设计约束
|
|||
|
|
|
|||
|
|
- 使用 `shallowRef` 保存 D3 行为和 ResizeObserver，避免深层响应式开销。
|
|||
|
|
- 缩放行为只由 `zoomable`、显示模式、绘图区尺寸和通道数决定。
|
|||
|
|
- 父组件通过 props 提供不可变数据；只有替换 `data` 引用才会刷新内部缓存。
|
|||
|
|
- 空数据和非法数据必须渲染明确的空状态，而不是创建无效 SVG path。
|
|||
|
|
|
|||
|
|
## 测试与验证
|
|||
|
|
|
|||
|
|
`WaveformChart.test.ts` 覆盖数据规范化、空数据、多通道布局、坐标轴、显示模式、hover、
|
|||
|
|
tooltip、缩放和响应式尺寸变化。完成改动后运行：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pnpm test
|
|||
|
|
pnpm typecheck
|
|||
|
|
pnpm lint
|
|||
|
|
pnpm build
|
|||
|
|
```
|