李启源
119
ARCHITECTURE.md
Normal file
119
ARCHITECTURE.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# 波形分析组件项目架构
|
||||
|
||||
## 项目概览
|
||||
|
||||
这是一个基于 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
|
||||
```
|
||||
Reference in New Issue
Block a user