@linker-design-plus/timeline-track 1.0.9 → 1.0.10

package/README.md

@@ -348,6 +348,12 @@ new TimelineManager(config?: Partial<TimelineConfig>)
 | `off(event, listener)` | 移除事件监听器 | `event`：事件类型，`listener`：事件监听器 | 无 |
 | `destroy()` | 销毁时间轴管理器 | 无 | 无 |
 
+### 交互事件分层规范
+
+- 鼠标交互（时间轴拖拽、底部滑块拖拽、片段拖拽）采用统一分层策略，详见：
+  - `docs/interaction-model.md`
+- 该文档用于约束后续重构，避免出现“移出画布中断拖拽”或“回到画布瞬移”等回归问题。
+
 #### 事件
 
 | 事件名 | 描述 | 数据 |
@@ -359,10 +365,13 @@ new TimelineManager(config?: Partial<TimelineConfig>)
 | `clip_removed` | 移除片段 | `{ clipId: string }` |
 | `clip_updated` | 更新片段 | `{ clip: Clip }` |
 | `clip_selected` | 选择片段 | `{ clip: Clip }` |
+| `selected_clip_change` | 选中片段变化（订阅后会立即回调当前状态） | `{ clip: Clip \| null, hasSelectedClip: boolean }` |
 | `zoom_change` | 缩放比例变化 | `{ zoom: number }` |
 | `history_change` | 历史记录变更 | `{ canUndo: boolean, canRedo: boolean }` |
 | `track_duration_change` | 轨道总时长变化 | `{ duration: number }` |
 | `buffering_state_change` | 视频缓冲状态变化 | `{ isBuffering: boolean }` |
+| `can_play_change` | 是否可播放状态变化 | `{ canPlay: boolean }` |
+| `source_loading_change` | 视频源加载状态变化 | `{ isLoading: boolean, pending: number }` |
 
 ### ClipConfig 接口
 

package/dist/components/Timeline.d.ts

@@ -18,9 +18,21 @@ export declare class Timeline {
     private isScrollbarDragging;
     private scrollbarDragStartX;
     private scrollbarDragStartScrollLeft;
+    private hasBoundGlobalPointerListenersForDrag;
+    private isPointerInsideTimeline;
+    private lastPointerXInTimeline;
+    private handleGlobalPointerMove;
+    private handleGlobalPointerEnd;
+    private handleVisibilityChange;
     private leftPadding;
     constructor(stage: Konva.Stage, gridLayer: Konva.Layer, config: Partial<TimelineConfig>, onTimeChange: (time: TimeMs) => void, onZoomChange: (zoom: number) => void, onScrollChange: (scrollLeft: number) => void);
     private initEventListeners;
+    private updatePointerPosition;
+    private bindGlobalPointerListenersForDrag;
+    private unbindGlobalPointerListenersForDrag;
+    private isPointerSessionActive;
+    private finalizePointerInteraction;
+    private handlePointerMove;
     private handleZoom;
     private animateZoom;
     private animateHorizontalScroll;
@@ -63,6 +75,14 @@ export declare class Timeline {
      * 获取网格图层
      */
     getGridLayer(): Konva.Layer;
+    /**
+     * 鼠标当前是否位于时间轴区域内
+     */
+    hasPointerInTimeline(): boolean;
+    /**
+     * 获取时间轴内最近一次鼠标 X 坐标（相对 stage）
+     */
+    getPointerXInTimeline(): number | null;
     /**
      * 调整大小
      */

package/dist/components/VideoTrack.d.ts

@@ -21,13 +21,21 @@ export declare class VideoTrack {
     private onClipSplit;
     private onClipSelect;
     private onTimeJump;
+    private onAutoScrollDuringDrag?;
+    private dragAutoScrollOffsetPx;
+    private hasBoundGlobalPointerListenersForDrag;
+    private handleGlobalPointerMove;
+    private handleGlobalPointerEnd;
     constructor(layer: Konva.Layer, config: TrackConfig, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: ClipType, originalClip?: ClipType, clipUpdates?: Array<{
         clipId: string;
         newState: any;
         previousState: any;
-    }>) => void, onClipAdd: (clip: ClipType) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: ClipType, clip2: ClipType) => void, onClipSelect: (clip: ClipType) => void, onTimeJump: (time: TimeMs) => void);
+    }>) => void, onClipAdd: (clip: ClipType) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: ClipType, clip2: ClipType) => void, onClipSelect: (clip: ClipType) => void, onTimeJump: (time: TimeMs) => void, onAutoScrollDuringDrag?: (targetScrollLeft: number) => void);
     private initClips;
     private initEventListeners;
+    private bindGlobalPointerListenersForDrag;
+    private unbindGlobalPointerListenersForDrag;
+    private handleVisibilityChange;
     /**
      * 处理轨道背景点击事件
      */
@@ -77,6 +85,9 @@ export declare class VideoTrack {
      * 处理舞台鼠标移动事件
      */
     private handleStageMouseMove;
+    private isDragSessionActive;
+    private handleDragMove;
+    private maybeAutoScrollDuringDrag;
     /**
      * 处理片段鼠标离开事件
      */

package/dist/core/timelineManager.d.ts

@@ -22,6 +22,7 @@ export declare class TimelineManager {
     private canPlay;
     private isBuffering;
     private sourceLoadingCount;
+    private lastSelectedClipId;
     private playStateBeforeBuffering;
     private isPausingForBuffering;
     private videoBufferingListeners;
@@ -39,6 +40,16 @@ export declare class TimelineManager {
      * 调整 scrollLeft 使游标在屏幕上的位置保持不变
      */
     setZoomCenteredOnPlayhead(zoom: number): void;
+    /**
+     * 外部缩放入口：
+     * - 鼠标在时间轴内：以鼠标位置为中心缩放
+     * - 鼠标不在时间轴内：回退为以游标（playhead）为中心缩放
+     */
+    setZoomByInteraction(zoom: number): void;
+    /**
+     * 以时间轴上的指定像素点为中心缩放，保持该像素对应时间不变
+     */
+    setZoomCenteredOnTimelinePointer(zoom: number, pointerX: number): void;
     getZoom(): number;
     /**
      * 设置播放倍速
@@ -118,6 +129,7 @@ export declare class TimelineManager {
     private handleTimeChange;
     private handleZoomChange;
     private handleScrollChange;
+    private handleTrackAutoScrollRequest;
     private handleClipUpdate;
     private handleClipAdd;
     private handleClipRemove;
@@ -138,6 +150,7 @@ export declare class TimelineManager {
     on(event: TimelineEvent, listener: TimelineEventListener): void;
     off(event: TimelineEvent, listener: TimelineEventListener): void;
     private emitEvent;
+    private emitSelectedClipChangeIfNeeded;
     private beginSourceLoading;
     private endSourceLoading;
     getPlayState(): PlayState;
@@ -205,6 +218,7 @@ export declare class TimelineManager {
     private detachVideoBufferingListeners;
     private enterBuffering;
     private exitBuffering;
+    private clearBufferingStateForNoSource;
     /**
      * 检查轨道总时长是否变化，如果变化则触发事件并更新时间轴时长
      */

package/dist/core/types.d.ts

@@ -123,7 +123,7 @@ export interface HistoryState {
     past: Action[];
     future: Action[];
 }
-export type TimelineEvent = 'time_change' | 'play_state_change' | 'clip_added' | 'clip_removed' | 'clip_updated' | 'zoom_change' | 'history_change' | 'track_duration_change' | 'clip_selected' | 'speed_change' | 'can_play_change' | 'buffering_state_change' | 'source_loading_change';
+export type TimelineEvent = 'time_change' | 'play_state_change' | 'clip_added' | 'clip_removed' | 'clip_updated' | 'zoom_change' | 'history_change' | 'track_duration_change' | 'clip_selected' | 'selected_clip_change' | 'speed_change' | 'can_play_change' | 'buffering_state_change' | 'source_loading_change';
 export interface TimeChangeData {
     time: TimeMs;
 }
@@ -136,6 +136,10 @@ export interface ZoomChangeData {
 export interface ClipEventData {
     clip: Clip;
 }
+export interface SelectedClipChangeData {
+    clip: Clip | null;
+    hasSelectedClip: boolean;
+}
 export interface ClipRemovedEventData {
     clipId: string;
 }