@linker-design-plus/timeline-track 1.0.8 → 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,9 +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

@@ -13,15 +13,26 @@ export declare class Timeline {
     private onZoomChange;
     private onScrollChange;
     private animationFrameId;
-    private isZooming;
     private scrollbarHeight;
     private scrollbarY;
     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;
@@ -64,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/constants.d.ts

@@ -19,3 +19,4 @@ export declare const TIME_SCALE: {
     MAX_HEIGHT: number;
 };
 export declare const TIMELINE_LEFT_PADDING = 15;
+export declare const MIN_CLIP_LINE_WIDTH = 6;

package/dist/core/timelineManager.d.ts

@@ -1,4 +1,4 @@
-import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener, VideoPreviewConfig, TimelineExportData, ThumbnailProvider } from './types';
+import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener as TimelineEventListener, VideoPreviewConfig, TimelineExportData, ThumbnailProvider } from './types';
 export declare class TimelineManager {
     private timeline;
     private tracks;
@@ -20,6 +20,12 @@ export declare class TimelineManager {
     private lastTrackDuration;
     private thumbnailProvider;
     private canPlay;
+    private isBuffering;
+    private sourceLoadingCount;
+    private lastSelectedClipId;
+    private playStateBeforeBuffering;
+    private isPausingForBuffering;
+    private videoBufferingListeners;
     constructor(config?: Partial<TimelineConfig>);
     init(container: HTMLElement): void;
     play(): void;
@@ -29,6 +35,21 @@ export declare class TimelineManager {
     setCurrentTime(time: TimeMs): void;
     getCurrentTime(): TimeMs;
     setZoom(zoom: number): void;
+    /**
+     * 以游标（playhead）为中心设置缩放，用于外置 slider 等非幕布上的缩放操作
+     * 调整 scrollLeft 使游标在屏幕上的位置保持不变
+     */
+    setZoomCenteredOnPlayhead(zoom: number): void;
+    /**
+     * 外部缩放入口：
+     * - 鼠标在时间轴内：以鼠标位置为中心缩放
+     * - 鼠标不在时间轴内：回退为以游标（playhead）为中心缩放
+     */
+    setZoomByInteraction(zoom: number): void;
+    /**
+     * 以时间轴上的指定像素点为中心缩放，保持该像素对应时间不变
+     */
+    setZoomCenteredOnTimelinePointer(zoom: number, pointerX: number): void;
     getZoom(): number;
     /**
      * 设置播放倍速
@@ -45,6 +66,17 @@ export declare class TimelineManager {
      * @returns 是否可以播放
      */
     getCanPlay(): boolean;
+    /**
+     * 当前是否存在视频源加载任务（例如 addClip 期间读取视频时长）
+     */
+    isSourceLoading(): boolean;
+    /**
+     * 获取视频源加载状态
+     */
+    getSourceLoadingState(): {
+        isLoading: boolean;
+        pending: number;
+    };
     /**
      * 设置缩略图提供器
      * @param provider 缩略图提供器
@@ -68,6 +100,11 @@ export declare class TimelineManager {
      */
     refreshAllClipThumbnails(): Promise<boolean[]>;
     addClip(clipConfig: ClipConfig): Promise<string>;
+    /**
+     * 批量添加片段。批量模式下仅维护一段连续的视频源加载状态。
+     */
+    addClips(clipConfigs: ClipConfig[]): Promise<string[]>;
+    private addClipInternal;
     removeClip(clipId: string): void;
     updateClip(clipId: string, updates: Partial<Clip>): void;
     splitClip(clipId: string, time: TimeMs): void;
@@ -92,6 +129,7 @@ export declare class TimelineManager {
     private handleTimeChange;
     private handleZoomChange;
     private handleScrollChange;
+    private handleTrackAutoScrollRequest;
     private handleClipUpdate;
     private handleClipAdd;
     private handleClipRemove;
@@ -109,9 +147,12 @@ export declare class TimelineManager {
     private handleClipSelect;
     private handleActionUndo;
     private handleActionRedo;
-    on(event: TimelineEvent, listener: EventListener): void;
-    off(event: TimelineEvent, listener: EventListener): void;
+    on(event: TimelineEvent, listener: TimelineEventListener): void;
+    off(event: TimelineEvent, listener: TimelineEventListener): void;
     private emitEvent;
+    private emitSelectedClipChangeIfNeeded;
+    private beginSourceLoading;
+    private endSourceLoading;
     getPlayState(): PlayState;
     setDuration(duration: TimeMs): void;
     getDuration(): TimeMs;
@@ -168,10 +209,16 @@ export declare class TimelineManager {
     /** 清除历史堆栈 */
     clearHistory(): void;
     private handleVideoTimeUpdate;
+    private getLastClipByEndTime;
     private handlePlayStateChange;
     private handleClipChange;
     private findClipAtTime;
     private loadClipToVideo;
+    private attachVideoBufferingListeners;
+    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';
+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,12 +136,23 @@ export interface ZoomChangeData {
 export interface ClipEventData {
     clip: Clip;
 }
+export interface SelectedClipChangeData {
+    clip: Clip | null;
+    hasSelectedClip: boolean;
+}
 export interface ClipRemovedEventData {
     clipId: string;
 }
 export interface CanPlayChangeData {
     canPlay: boolean;
 }
+export interface BufferingStateChangeData {
+    isBuffering: boolean;
+}
+export interface SourceLoadingChangeData {
+    isLoading: boolean;
+    pending: number;
+}
 export interface EventListener {
     (event: TimelineEvent, data?: any): void;
 }