waveform-analysis 0.1.66 → 0.1.67

package/README.md

@@ -91,12 +91,15 @@ const data = ref<WaveformData>({
 | `data`                     | `WaveformData`                              | 必填                                                                                  | 波形数据                                      |
 | `displayMode`              | `'independent' \| 'separated' \| 'compact'` | `'independent'`                                                                       | 图框布局                                      |
 | `overlayMode`              | `'single-axis' \| 'multi-axis'`             | `'single-axis'`                                                                       | 叠加曲线的 Y 轴模式                           |
+| `layoutPreset`             | `'default' \| 'edge-compact'`               | `'default'`                                                                           | 标题贴边、时间标签与响应式分页布局            |
+| `unitDisplayMode`          | `'axis' \| 'legend-single-series'`          | `'axis'`                                                                              | 可选的图表级单位展示规则                      |
 | `timeUnit`                 | `'s' \| 'ms'`                               | `'ms'`                                                                                | 坐标轴和 tooltip 展示单位                     |
 | `xLabel` / `yLabel`        | `string`                                    | `时间（timeUnit）` / `'幅值'`                                                         | 坐标轴名称                                    |
 | `lineColor`                | `string`                                    | `'#0960bd'`                                                                           | 单波形默认颜色                                |
 | `width` / `height`         | `number`                                    | 自适应                                                                                | 组件总尺寸，单位为 CSS 像素                   |
 | `zoomable` / `showTooltip` | `boolean`                                   | `true` / `true`                                                                       | 缩放和数值 tooltip 开关                       |
 | `pannable`                 | `boolean`                                   | `false`                                                                               | 空格拖拽平移开关                              |
+| `panXDomain`               | `[number, number]`                          | 未设置                                                                                | 远端横向平移边界，使用秒坐标                  |
 | `minZoomSpan`              | `number`                                    | 未设置                                                                                | 最小缩放跨度，使用原始 X 数据单位             |
 | `integerZoom`              | `boolean`                                   | `false`                                                                               | 缩放范围按 X 轴显示单位对齐整数               |
 | `minVisiblePoints`         | `number`                                    | `0`                                                                                   | 缩放后至少保留的不同 X 坐标数                 |
@@ -267,6 +270,16 @@ Y 轴会独立计算：
 <WaveformChart :data="chartData" :axes="{ y: { nice: false } }" />
 ```
 
+自动 Y 轴范围可通过 `axes.y.upperPaddingRatio` 设置上限留白比例，默认 `0`。
+例如 `0.1` 使用 `[min, max + (max - min) * 0.1]`，下限不变。
+单值轴按图框合并范围计算，多值轴按各轴对应曲线范围计算；固定范围及手动缩放的 Y
+视口不增加留白。常量数据先沿用非零范围回退，再计算留白。设置 `nice: false`
+可避免刻度算法进一步扩展范围。
+
+```vue
+<WaveformChart :data="chartData" :axes="{ y: { nice: false, upperPaddingRatio: 0.1 } }" />
+```
+
 ### 缩放后按可视区间加载数据
 
 组件支持 Plotly 风格的矩形框选缩放：在 zoom 模式下按住鼠标左键拖拽，松开后同时缩放
@@ -295,7 +308,32 @@ X/Y 轴；设置 `pannable` 后，指针位于图表内时按住空格键拖拽
 
 `zoom-end.gesture` 用于区分 `wheel` 和 `box`。单轨道 payload 使用 `yStart/yEnd`；共享
 X 轴且包含多个轨道时使用按稳定 track ID 索引的 `yRanges`。平移不会触发 `zoom-end`，
-因此不会自动发起新的区间加载请求。
+平移结束且 X 范围变化时触发 `pan-end`，可在此请求新的时间段。
+
+远端时间段平移可配置 `panXDomain` 为整条记录的起止时间。启用后，空格 + 拖动只改变 X
+范围，保持当前窗口宽度和 Y 轴；到达记录边界时停止。未配置或范围无效（非有限值、起点不小于
+终点）时保留原来的数据内 X/Y 平移行为。
+
+```vue
+<WaveformChart
+  :data="waveformData"
+  :pan-x-domain="[recordStartSeconds, recordEndSeconds]"
+  pannable
+  @pan-end="loadTimeWindow"
+/>
+```
+
+`pan-end` 的公开类型为 `WaveformPanEndPayload`，包含以秒表示的 `start/end`；独立模式还包含
+`trackIndex/seriesIds`，业务页面据此只更新对应图框的数据，保留其他序列及稳定 ID。松开鼠标后
+按端点请求，用新的 `data` 引用回填；组件会保持当前 X 视口，包括返回点稀疏、缓存范围更大或
+当前视口与旧数据窗口等宽的情况。不要为每次请求修改 `initialXDomain`，它仍表示重置范围。
+加载期间超出已加载数据的区域显示空白，加载状态和错误提示由业务页面提供。
+
+配置远端边界时，滚轮、框选和 `setViewportDomain` 在记录范围内约束，最小缩放跨度及倍率
+仍基于初始数据域；未加载区间没有真实点数，因此不会用 `minVisiblePoints` 将目标窗口拉回
+已加载数据。回填时保留 X 范围，不重新应用点数约束。取消拖动或范围没有变化不会触发 `pan-end`。
+平移过程中用 `zoom-change` 使旧请求失效，完成后用 `pan-end` 发起请求；对缩放仍使用
+`zoom-intent`。业务页面应使用请求序号或取消机制，避免旧响应覆盖更新的目标窗口。
 
 调用方应处理加载失败的情况（网络错误、超时等），并保持旧数据或显示加载状态。生产环境建议使用
 `AbortController` 取消过时的请求。
@@ -367,7 +405,81 @@ chartRef.value?.setViewportDomain(trackDomain, trackIndex)
 `timeUnit` 只控制坐标轴和 tooltip 的显示单位。
 
 Tooltip 每个系列按 `炮号：通道  (x:值 y:值)` 格式显示。`WaveformSeries.shotNo` 为空或未提供时，
-炮号显示为“未配置炮号”；Tooltip 不显示单位和误差附加文本。
+炮号显示为“未配置炮号”；配置 `series.unit` 时在通道名后显示 `(单位)`，不显示误差附加文本。
+
+### 标题与时间标签贴边布局（可选）
+
+```vue
+<WaveformChart
+  :data="waveformData"
+  layout-preset="edge-compact"
+  :title="{ text: 'shot: #1001', textStyle: { fontSize: 18, fontWeight: 700 } }"
+  x-label="Time(ms)"
+  :plot-margin="{ top: 0, bottom: 44 }"
+/>
+```
+
+公共类型 `WaveformLayoutPreset = 'default' | 'edge-compact'`，对应
+`WaveformChartProps.layoutPreset`。默认 `'default'` 保持既有标题、时间标签、宽窄分页
+布局；可与 `unitDisplayMode='legend-single-series'` 一起使用。
+
+`'edge-compact'` 下，标题区域使用实际测量的文字显示高度加 8px，顶部约 4px 留白，
+不再强制最少 44px。设置 `plotMargin.top=0` 时，标题底部距内部绘图上边框约 4px。
+无标题、空标题或 `title.visible=false` 时不预留标题区。
+标题字体仍由 `title.textStyle` 控制，保留长标题换行及旋转缩放（旋转标题区域上限
+仍为 160px）。测量完成前使用文字尺寸估计，不重复放大已经测量的多行高度。
+
+时间标签（`xLabel`，默认仍为 `时间（ms）` 或 `时间（s）`）单独使用 18px、字重 700，
+水平居中于绘图区，紧凑模式基线为 `drawingHeight - 9px`，比原位置下移 3px，
+增加与上方刻度区域的间隔；默认布局仍为 `drawingHeight - 12px`，不设置额外的
+`dominant-baseline`。通过 `xLabel='Time(ms)'` 传入严格的业务文字，组件不自动改写。
+分页按钮可见时，宽度大于 520px 且右侧空间足够时仅预留 16px；结合已有的 44px 底部总预算，
+图框底边距卡片内容下沿共 60px，末尾 X 刻度与右下分页顶部约留 5px 安全间距。
+相较预留 40px，桌面图框向下延伸 24px；Time 仍居中使用 18px/700，其基线距内容
+下沿 25px，与右侧分页处于同一底部水平区域。窄图表（宽度小于等于 520px）保留
+40px 独立分页区，避免 Time 与按钮水平冲突。预留条件与按钮显隐一致：
+`grid.showPagination && pageCount > 1 && !cleanView`。
+组件按最多 9 个页码/省略号及前后按钮、32px 按钮、8px 间距保守估算分页宽度，
+同时按绘图区中心和 18px 字体估算 Time 标签占位；中等宽度、多页或长标签导致右侧
+空间不足时自动预留 40px，无需新公共配置。
+没有分页或净图模式不预留按钮区。`cleanView` 仍隐藏时间标签及标题文字，保留既有标题区域策略。
+
+紧凑模式的 `plotMargin.bottom` 最小为 44px（传入 35px 会按 44px 布局），该总预算
+已包含最后一行的 30px X 轴刻度带，不再额外叠加；最下面的网格图框底边距绘制 SVG
+下沿为 44px（更大的有效边距仍保留）。中间行刻度带不变，尾部空行无 X 轴时不补偿。
+净图模式不应用刻度带补偿，保留现有刻度与网格布局。
+最高 Y 刻度（含科学指数和单位）在紧凑模式向图框内贴边，`top=0` 时有无标题均不会
+向 SVG 顶部越界；默认模式的刻度锚点不变。
+紧凑模式的图框边框路径向内缩半个实际 `frameStyle.borderWidth`，四边使用同一描边
+线宽，完整描边保持在原图框范围内；`top=0` 且没有标题时也无需额外顶部留白。
+外层卡片继续裁切溢出内容，默认布局的边框几何保持不变。
+刻度字号保持原值。`plotMargin` 不改变标签距底部的位置。该布局只影响展示尺寸，
+既有平移事件与范围、单位模式、tooltip 和 Y 轴上限留白 API 保持不变。
+
+### 客户图例单位规则（可选）
+
+```vue
+<WaveformChart :data="waveformData" unit-display-mode="legend-single-series" />
+```
+
+公共类型 `WaveformUnitDisplayMode = 'axis' | 'legend-single-series'`，也可通过
+`WaveformChartProps.unitDisplayMode` 配置。默认 `'axis'` 保持现有行为（单位在 Y 轴最高
+刻度中，单曲线图框不显示图例）。客户模式会为每个非空图框显示图例：
+
+- 整个图表的所有非空 track 都只有一条曲线时，图例显示 `名称 (单位)`，例如
+  `CH1(1001) (V)`；单位去除两端空白，缺失、空白或占位值 `--` 不追加括号。
+- 任一 track 包含多条曲线时，整个图表的图例只显示原始名称，所有 Y 轴也隐藏单位。
+  判定依据是曲线数量，而非 Y 轴分组数量，同单位共用一根轴的多曲线图框同样适用。
+- 判定使用分页前完整的 track 曲线列表，跨页一致；`grid.trackOrder` 的空图框和补齐
+  槽位不参与判定；隐藏曲线仍计数，包括全部曲线隐藏的图框，切换可见性不会改变规则。
+  替换 `data` 后重新判定。只有从数据中移除曲线才改变曲线数量。
+- 客户模式始终隐藏轴单位，科学计数法 `E+04` 等仍保留在最高刻度（左侧 Y 轴顶端
+  左侧；多 Y 轴各自保留倍率），刻度缩放和数值不变。多曲线规则不隐藏倍率。
+
+继续将真实单位写入 `series.unit`，名称写入 `series.name`（可已包含炮号）。组件只在
+展示层组合图例文字，不修改名称或单位；tooltip 仍使用原始名称和单位字段，例如
+`CH1(1001)(V)`，标注元数据也保持原值。图例位置、排列、交互仍由 `legend` 控制，
+`cleanView` 仍隐藏图例。`pan-end`、`panXDomain`、`axes.y.upperPaddingRatio` 不受影响。
 
 ### 纵轴单位
 
@@ -397,7 +509,15 @@ const chartData = {
 `(V) 3`。单位为空、全为空白或未配置时，不显示 `(单位)`，例如仍显示为 `E+03 3` 或 `3`。
 多 Y 轴模式下，每根轴使用该轴首个 series 的单位。
 
-左侧通道名称使用 14px、字重 600 的加粗文字，按字符宽度估算旋转名称的垂直范围，仅对可能与名称相交的刻度文字（含文字高度和安全间距）自动计算间距；不相交的顶部单位刻度不会推远名称。同一列中相同轴位使用逐道计算的最大间距，保证多道名称垂直对齐；左侧留白随刻度宽度调整，避免名称与刻度重叠。
+左侧通道名称使用 14px、字重 600 的加粗文字。默认布局按字符宽度估算旋转名称的垂直范围，
+仅对可能与名称相交的刻度文字（含文字高度和安全间距）自动计算间距；不相交的顶部单位
+刻度不会推远名称。同一列中相同轴位使用逐道计算的最大间距，保证多道名称垂直对齐。
+
+`edge-compact` 统一按实际显示的 Y 刻度文字宽度、7px 刻度间距和 20px 名称带计算
+轴槽位、名称位置及左边距；隐藏的单位不参与宽度估算，科学计数法倍率仍计入。
+最外侧名称带左边保留 24px 外部留白，与单轴图框右侧的 24px 对齐，不再使用
+默认布局的固定 48px 最小左边距。多轴使用各轴位的最大刻度宽度，多列同时预留相邻
+图框的轴和名称带，避免名称、长刻度及相邻图框重叠。默认布局的留白策略保持兼容。
 
 ### 线型、点型与误差棒
 
@@ -854,6 +974,7 @@ X 轴刻度和左右端点先按 `timeUnit` 转换为秒或毫秒，再显示为
 | `point-hover`                                                   | 当前最近点变化时触发，离开图表时传入 `null`                    |
 | `zoom-intent`                                                   | 真实滚轮或框选确定目标范围时同步触发，参数含端点和 `gesture`   |
 | `zoom-change`                                                   | 缩放过程中触发，参数为 `[start, end]`                          |
+| `pan-end`                                                       | 平移结束且范围变化时返回时间端点，独立模式附带轨道信息         |
 | `zoom-end`                                                      | 滚轮或框选结束后触发；`gesture` 区分二者，独立模式附带轨道信息 |
 | `zoom-reset`                                                    | 双击重置视口时触发；独立模式 payload 标识目标图框              |
 | `page-change`                                                   | 分页变化，参数为当前页和总页数                                 |