waveform-analysis 0.1.65 → 0.1.67

package/README.md

@@ -91,13 +91,17 @@ 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 坐标数                 |
 | `maxZoomScale`             | `number \| null`                            | 未设置                                                                                | 最大缩放倍数；`null` 表示不限制               |
 | `initialXDomain`           | `[number, number]`                          | 未设置                                                                                | 所有图框的初始 X 范围（可超出数据，空白显示） |
@@ -266,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 模式下按住鼠标左键拖拽，松开后同时缩放
@@ -294,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` 取消过时的请求。
@@ -303,6 +342,15 @@ X 轴且包含多个轨道时使用按稳定 track ID 索引的 `yRanges`。平
 `initialXDomains` 按 track ID 或 series ID 分别配置。`minZoomSpan` 使用原始 X 数据单位，
 可防止每次区间数据回填后重新累计放大。未配置任何缩放约束时保留既有的 40 倍兜底；设置
 `minVisiblePoints: 2` 可缩放到两个真实采样点，`maxZoomScale: null` 可显式关闭倍率上限。
+
+设置 `:integer-zoom="true"` 可开启整数缩放，默认关闭。开启后滚轮、框选和
+`setViewportDomain` 的开始时间向下取整、结束时间向上取整；`timeUnit='ms'` 时对齐整毫秒，
+`timeUnit='s'` 时对齐整秒，最小跨度为一个显示单位。初始范围和重置范围也向外对齐，
+不会裁掉边缘数据，最小跨度、最大倍率和最少可见点数限制仍然生效。
+默认 X 轴标签和主刻度也使用整数显示单位，平移时保持整数端点及当前跨度。
+动态切换此开关或在开启时切换时间单位会重置视口。
+原始采样坐标不会被修改，缩放事件仍以秒返回实际对齐后的范围；自定义 formatter 不影响对齐粒度。
+关闭时 `timeUnit` 仍只影响展示，不改变缩放范围。
 显式设置多种限制时采用最严格的一项。双击图框会
 重置组件内部缩放并触发 `zoom-reset`；调用方应在事件中取消区间请求并恢复首次完整数据。
 外部重置按钮也可以通过模板引用调用组件公开的 `resetViewport()` 方法，然后执行相同的数据恢复逻辑。
@@ -357,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` 不受影响。
 
 ### 纵轴单位
 
@@ -387,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 最小左边距。多轴使用各轴位的最大刻度宽度，多列同时预留相邻
+图框的轴和名称带，避免名称、长刻度及相邻图框重叠。默认布局的留白策略保持兼容。
 
 ### 线型、点型与误差棒
 
@@ -564,8 +694,10 @@ const hiddenSeriesIds = ref<string[]>([])
 ### 零值参考线与净图
 
 `zeroLine` 用于绘制 `y = 0` 的水平参考线，默认显示红色（`#ff0000`）、1px 宽的虚线
-（`dash: '6 4'`）。参考线只在对应 Y 轴的当前 domain
-包含 0 时渲染，不会为了显示参考线而扩展数据范围。多值轴模式下，每根可见 Y 轴分别按自身
+（`dash: '6 4'`），透明度默认为 `0.5`。参考线只在对应 Y 轴的当前 domain
+严格跨过 0，且距两端均不小于一个主刻度间距的 2% 时渲染；零线位于边界时隐藏。
+不会为了显示参考线而扩展数据范围。零线绘制在曲线、点标记及误差棒上方。
+多值轴模式下，每根可见 Y 轴分别按自身
 scale 定位零线：
 
 ```vue
@@ -576,6 +708,8 @@ scale 定位零线：
     color: '#ff0000',
     width: 1,
     dash: '6 4',
+    opacity: 0.5,
+    boundaryThreshold: 0.02,
   }"
 />
 ```
@@ -586,6 +720,12 @@ scale 定位零线：
 只传入颜色或线型时仍默认显示，例如 `:zero-line="{ color: '#0960bd', dash: '' }"`
 显示蓝色实线。使用 `:zero-line="{ visible: false }"` 可关闭零线。颜色和线型配置可动态修改。
 
+`boundaryThreshold` 可动态调整边界隐藏比例，例如 `0.05` 表示一个主刻度间距的 5%，
+`0` 表示仅在恰好位于边界时隐藏；负数或非有限值回退到 `0.02`。
+`opacity` 支持 `0` 到 `1`，越界或非有限值回退到 `0.5`。颜色本身的 Alpha 与该透明度相乘；
+若使用 `rgba()` 或八位十六进制颜色的透明度，可设置 `opacity: 1`。
+主演示页的“零值参考线”区域可直接调整透明度，修改后立即应用于波形图。
+
 设置 `cleanView` 后，组件保留波形、图框边框、X/Y 轴刻度及刻度值，并隐藏标题内容、图例、
 网格、轴标签、图框背景、帧水印、零值参考线、标注和分页器。原图的标题区域、边距和波形
 尺寸保持不变；缩放、悬浮、十字线和 tooltip 仍然可用，切换回普通模式后原有配置和标注
@@ -834,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`                                                   | 分页变化，参数为当前页和总页数                                 |