本文详解如何在 Wavesurfer.js 中实现字幕时间轴多区域（regions）的防重叠逻辑，通过监听 region-updated 事件动态校准相邻区域边界，确保拖拽/缩放后各区域严格互不交叠。
本文详解如何在 wavesurfer.js 中实现字幕时间轴多区域（regions）的防重叠逻辑，通过监听 `region-updated` 事件动态校准相邻区域边界，确保拖拽/缩放后各区域严格互不交叠。
在基于 Wavesurfer.js 构建视频字幕编辑器时，常需为每行字幕创建可拖拽、可缩放的时间区域（Region）。但默认行为下，区域之间可自由重叠，破坏时间轴语义（例如：字幕不应在同一时刻显示两行）。虽然 Wavesurfer.js 未内置防重叠机制，但可通过事件监听 + 边界校准实现鲁棒的约束逻辑。
核心思路是：在区域更新完成时（region-updated），立即检测其与前后相邻区域的时间冲突，并将越界端点强制对齐至邻区边界。注意，必须使用 region-updated（而非 region-drag 或 region-resize）——因为该事件在用户操作结束、波形图重绘完成后触发，此时区域时间值已稳定，且所有区域状态同步可用。
以下为完整实现方案：
✅ 步骤一：定义邻区查找工具函数
const findAdjacentRegions = (targetRegion, allRegions) => {
const sorted = [...allRegions].sort((a, b) => a.start - b.start);
const idx = sorted.findIndex(r => r.id === targetRegion.id);
return {
previous: idx > 0 ? sorted[idx - 1] : null,
next: idx <h3>✅ 步骤二：实现边界校准处理函数</h3><pre class="brush:php;toolbar:false;">const handleRegionUpdateEnd = (region) => {
const regions = wsRegions.current.getRegions();
const currentRegion = region;
const { previous, next } = findAdjacentRegions(currentRegion, regions);
// 若当前区域终点越过后一区域起点 → 截断至后区起点
if (next && currentRegion.end > next.start) {
currentRegion.end = next.start;
}
// 若当前区域起点早于前一区域终点 → 推进至前区终点
if (previous && currentRegion.start <h3>✅ 步骤三：注册事件监听（推荐配合 useEffect）</h3><pre class="brush:php;toolbar:false;">useEffect(() => {
if (!wsRegions.current) return;
wsRegions.current.on('region-updated', handleRegionUpdateEnd);
return () => {
wsRegions.current.un('region-updated', handleRegionUpdateEnd);
};
}, [segments]); // 依赖 segments 确保业务状态最新
⚠️ 关键注意事项：
- 不要在 region-drag 中校准：拖拽中区域时间持续变化，频繁修改会导致 UI 卡顿和逻辑混乱；region-updated 是唯一可靠时机。
- 必须重新排序再查找邻区：regions 集合无序，每次需按 start 排序后定位前后关系。
- 边界校准后需手动触发业务更新：如调用 updateSegmentTimeStamp() 刷新字幕列表或保存到状态管理。
- 容忍微小重叠（可选优化）：为避免浮点精度导致的“抖动”，可加入容差（如 Math.abs(current.end - next.start)
- 禁用重叠创建（进阶）：在 addRegion 前预检是否与现有区域冲突，直接拒绝非法区域。
该方案虽非像素级实时拦截（即拖拽过程中仍可见短暂重叠），但在用户体验上已足够自然：用户松手后区域立即“弹回”合法位置，符合专业音视频编辑器的操作直觉。如需更严格的实时拦截，需深入 Wavesurfer 源码 Hook 拖拽逻辑，但代价显著增加维护复杂度——对于字幕编辑场景，本方案是简洁性与健壮性的最佳平衡。
