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

package/dist/utils/logging/Logger.d.ts

@@ -0,0 +1,30 @@
+import type { LogConfig } from '../../core/models/types';
+export declare class Logger {
+    private static config;
+    private static dedupeWindowMs;
+    private static readonly dedupeState;
+    /**
+     * 配置日志系统
+     * @param config 日志配置
+     */
+    static setConfig(config?: LogConfig): void;
+    /**
+     * 输出调试级别日志
+     * @param module 模块名称
+     * @param message 日志消息
+     * @param data 附加数据
+     */
+    static debug(module: string, message: string, data?: any): void;
+    static debugLazy(module: string, messageFactory: () => string, dataFactory?: () => any): void;
+    static info(module: string, message: string, data?: any): void;
+    static infoLazy(module: string, messageFactory: () => string, dataFactory?: () => any): void;
+    static warn(module: string, message: string, data?: any): void;
+    static warnLazy(module: string, messageFactory: () => string, dataFactory?: () => any): void;
+    static error(module: string, message: string, data?: any): void;
+    /**
+     * 设置去重窗口，减少高频日志刷屏
+     */
+    static setDedupeWindowMs(windowMs: number): void;
+    private static emit;
+    private static resolveConsoleMethod;
+}

package/dist/utils/logging/index.d.ts

@@ -0,0 +1 @@
+export { Logger } from './Logger';

package/dist/utils/{KonvaUtils.d.ts → rendering/KonvaUtils.d.ts}

@@ -1,15 +1,10 @@
 import Konva from 'konva';
-import type { Theme } from '../core/types';
+import type { Theme, TrackType } from '../../core/models';
 /**
  * Konva工具类，封装常用的Konva操作
  */
 export declare class KonvaUtils {
     static readonly RESIZE_AREA_WIDTH = 3;
-    /** 单张封面图的最小展示宽度（px），zoom 过小时通过减少显示段数保证每段不低于此宽度，且仍填满整条 */
-    static readonly MIN_IMAGE_DISPLAY_WIDTH = 24;
-    private static keyframeDimensionsCache;
-    private static imageCache;
-    private static readonly MAX_CACHE_SIZE;
     /**
      * 创建舞台
      */
@@ -49,32 +44,6 @@ export declare class KonvaUtils {
      * 绘制网格线
      */
     static drawGrid(layer: Konva.Layer, x: number, y: number, width: number, height: number, gridSize: number): void;
-    /**
-     * 格式化时间（毫秒 -> mm:ss.ms）
-     */
-    static formatTime(ms: number): string;
-    /**
-     * 格式化时长（毫秒 -> ss.ms）
-     */
-    static formatDuration(ms: number): string;
-    /**
-     * 获取关键帧的尺寸信息（按 keyframeUrl 缓存，保证每张缩略图使用自身真实比例）
-     * @param videoSrc 视频源的URL（用于兼容旧调用）
-     * @param keyframeUrl 关键帧图片的URL
-     * @returns Promise<{ width: number; height: number }> 关键帧的宽度和高度
-     */
-    private static getKeyframeDimensions;
-    /**
-     * 获取缓存的图片对象
-     * @param imageUrl 图片的URL
-     * @returns HTMLImageElement 图片对象
-     */
-    private static getCachedImage;
-    /**
-     * 检查并清理缓存，防止内存占用过大
-     * 优先驱逐未加载完成的图片，已加载的图片尽量保留，避免滚动时重复请求
-     */
-    private static checkAndTrimCache;
     /**
      * 清空图片缓存
      */
@@ -82,11 +51,11 @@ export declare class KonvaUtils {
     /**
      * 创建片段组
      */
-    static createClipGroup(x: number, y: number, width: number, height: number, clipName: string, duration: number, theme: Theme, isSelected?: boolean, thumbnails?: string[], videoSrc?: string): Konva.Group;
+    static createClipGroup(x: number, y: number, width: number, height: number, clipName: string, duration: number, theme: Theme, isSelected?: boolean, thumbnails?: string[], videoSrc?: string, clipType?: TrackType, hasSeparatedAudio?: boolean, deferCoverRender?: boolean): Konva.Group;
     /**
      * 更新片段组
      */
-    static updateClipGroup(group: Konva.Group, width: number, height: number, clipName: string, duration: number, theme?: Theme, isSelected?: boolean, thumbnails?: string[], videoSrc?: string): void;
+    static updateClipGroup(group: Konva.Group, width: number, height: number, clipName: string, duration: number, theme?: Theme, isSelected?: boolean, thumbnails?: string[], videoSrc?: string, clipType?: TrackType, hasSeparatedAudio?: boolean, deferCoverRender?: boolean): void;
     /**
      * 创建选中效果
      */
@@ -95,15 +64,6 @@ export declare class KonvaUtils {
      * 时间到像素的转换
      */
     static timeToPixels(time: number, zoom: number): number;
-    private static readonly COVER_RENDER_VERSION_KEY;
-    /**
-     * 渲染关键帧封面（统一放大/缩小逻辑，始终填满无空轴）
-     * - 将 coverWidth 等分为若干段，每段对应一张缩略图（时间对应）。
-     * - 放大：段数 = N，段宽可能很大 → 用同一张图重复平铺填满该段。
-     * - 缩小：段数减少以保证每段宽度 ≥ MIN_IMAGE_DISPLAY_WIDTH，从 N 张中均匀抽样；每段仍用一张图缩放或重复填满。
-     * - 使用版本号避免 zoom 快速变化时，旧渲染覆盖新渲染导致空轴。
-     */
-    static renderClipCovers(coversGroup: Konva.Group, coverSource: string[], coverWidth: number, coverHeight: number, videoSrc?: string): Promise<void>;
     /**
      * 像素到时间的转换
      */

package/dist/utils/rendering/clipCoverRenderer.d.ts

@@ -0,0 +1,23 @@
+import Konva from 'konva';
+export declare class ClipCoverRenderer {
+    static readonly MIN_IMAGE_DISPLAY_WIDTH = 24;
+    private static readonly COVER_RENDER_VERSION_KEY;
+    private static readonly MAX_CACHE_SIZE;
+    private static readonly DEFAULT_DIMENSIONS;
+    private static keyframeDimensionsCache;
+    private static keyframeDimensionsPromiseCache;
+    private static imageCache;
+    static clearImageCache(): void;
+    static renderClipCovers(coversGroup: Konva.Group, coverSource: string[], coverWidth: number, coverHeight: number, videoSrc?: string, deferInitialRender?: boolean): void;
+    private static startRenderJob;
+    private static buildSegmentsData;
+    private static buildSegmentsDataSync;
+    private static requestRender;
+    private static isRenderJobCurrent;
+    private static renderSegments;
+    private static getSafeKeyframeDimensions;
+    private static getKeyframeDimensions;
+    private static getCachedKeyframeDimensions;
+    private static getCachedImage;
+    private static checkAndTrimCache;
+}

package/dist/utils/rendering/clipVisualRenderer.d.ts

@@ -0,0 +1,5 @@
+import Konva from 'konva';
+import { type Theme, type TrackType } from '../../core/models';
+export declare function createClipGroup(x: number, y: number, width: number, height: number, clipName: string, duration: number, theme: Theme, isSelected?: boolean, thumbnails?: string[], videoSrc?: string, clipType?: TrackType, hasSeparatedAudio?: boolean, deferCoverRender?: boolean): Konva.Group;
+export declare function updateClipGroup(group: Konva.Group, width: number, height: number, clipName: string, duration: number, theme?: Theme, isSelected?: boolean, thumbnails?: string[], videoSrc?: string, clipType?: TrackType, hasSeparatedAudio?: boolean, deferCoverRender?: boolean): void;
+export declare function createSelectionEffect(x: number, y: number, width: number, height: number): Konva.Rect;

package/dist/utils/rendering/index.d.ts

@@ -0,0 +1,4 @@
+export { KonvaUtils } from './KonvaUtils';
+export { ClipCoverRenderer } from './clipCoverRenderer';
+export { createClipGroup, createSelectionEffect, updateClipGroup } from './clipVisualRenderer';
+export { drawGrid, drawTimeTick } from './timelineGridDrawing';

package/dist/utils/rendering/timelineGridDrawing.d.ts

@@ -0,0 +1,8 @@
+import Konva from 'konva';
+interface TimeTickTheme {
+    timeTick: string;
+    timeText: string;
+}
+export declare function drawTimeTick(layer: Konva.Layer, x: number, y: number, height: number, time: number, theme: TimeTickTheme, tickType: 'major' | 'minor', timeScaleHeight?: number): void;
+export declare function drawGrid(layer: Konva.Layer, x: number, y: number, width: number, height: number, gridSize: number): void;
+export {};

package/dist/utils/time/index.d.ts

@@ -0,0 +1 @@
+export { TimeUtils } from './timeUtils';

package/dist/utils/{timeUtils.d.ts → time/timeUtils.d.ts}

@@ -23,6 +23,10 @@ export declare class TimeUtils {
      * 格式化时间显示
      */
     static formatTime(ms: number): string;
+    /**
+     * 格式化时长（毫秒 -> ss.ms）
+     */
+    static formatDuration(ms: number): string;
     /**
      * 计算两个时间点之间的差值
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linker-design-plus/timeline-track",
-  "version": "1.0.10",
+  "version": "2.0.0",
   "description": "A TypeScript-based video editing library with timeline and track functionality",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
@@ -16,13 +16,15 @@
     "build": "vite build && npm run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "preview": "vite preview",
-    "test:e2e": "vitest run src/components/__tests__/*.test.ts src/core/__tests__/*.test.ts"
+    "test": "vitest run src/components/__tests__/*.test.ts src/core/__tests__/*.test.ts"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^5.0.0",
+    "jsdom": "^29.0.1",
     "typescript": "^5.3.0",
     "vite": "^5.0.0",
     "vite-plugin-dts": "^3.6.0",
+    "vitest": "^4.0.18",
     "vue": "^3.4.0"
   },
   "keywords": [

package/dist/components/Clip.d.ts

@@ -1,44 +0,0 @@
-import { Clip as ClipType, Position } from '../core/types';
-export declare class Clip {
-    private clip;
-    private onUpdate;
-    private onSplit;
-    private isMoving;
-    private isMovingVisualApplied;
-    private dragStartPos;
-    private originalStart;
-    private originalDuration;
-    private originalStartTimeAtSource;
-    private originalEndTimeAtSource;
-    private originalOpacity;
-    constructor(clip: ClipType, onUpdate: (clip: ClipType) => void, onSplit: (clip: ClipType, time: number) => void);
-    /**
-     * 检查与其他片段是否重叠
-     */
-    checkCollision(newStartTime: number, newDuration: number, otherClips: ClipType[]): ClipType | undefined;
-    /**
-     * 检查是否超出边界
-     */
-    checkBoundary(newStartTimeAtSource: number, newEndTimeAtSource: number, newDuration: number, newStartTime: number): boolean;
-    /**
-     * 获取片段的中心点
-     */
-    getCenterTime(): number;
-    getClip(): ClipType;
-    setSelected(selected: boolean): void;
-    isPointInClip(x: number, y: number, zoom: number, trackY: number, trackHeight: number, scrollLeft: number): boolean;
-    isPointInResizeHandle(x: number, y: number, zoom: number, trackY: number, trackHeight: number, scrollLeft: number): boolean;
-    startDrag(pos: Position): void;
-    startResize(pos: Position): void;
-    /**
-     * 拖动片段或调整片段大小
-     * @param pos 当前鼠标位置
-     * @param zoom 缩放比例
-     * @param otherClips 其他片段列表（用于碰撞检测）
-     * @param enableBoundaryCheck 是否启用边界检查
-     * @returns 是否成功更新（即是否在边界内）
-     */
-    drag(pos: Position, zoom: number, otherClips?: ClipType[], enableBoundaryCheck?: boolean): boolean;
-    endDrag(): void;
-    split(time: number): void;
-}

package/dist/components/VideoTrack.d.ts

@@ -1,137 +0,0 @@
-import Konva from 'konva';
-import { Clip as ClipType, TrackConfig, TimeMs, Theme } from '../core/types';
-export declare class VideoTrack {
-    private layer;
-    private trackGroup;
-    private config;
-    private theme;
-    private clips;
-    private clipGroups;
-    private zoom;
-    private scrollLeft;
-    private trackY;
-    private trackHeight;
-    private selectedClip;
-    private originalClipsState;
-    private nonDraggedClips;
-    private isVisualUpdate;
-    private onClipUpdate;
-    private onClipAdd;
-    private onClipRemove;
-    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, onAutoScrollDuringDrag?: (targetScrollLeft: number) => void);
-    private initClips;
-    private initEventListeners;
-    private bindGlobalPointerListenersForDrag;
-    private unbindGlobalPointerListenersForDrag;
-    private handleVisibilityChange;
-    /**
-     * 处理轨道背景点击事件
-     */
-    private handleTrackBackgroundClick;
-    /**
-     * 创建片段组
-     */
-    private createClipGroup;
-    /**
-     * 处理片段点击事件
-     */
-    private handleClipClick;
-    /**
-     * 处理片段鼠标按下事件
-     */
-    private handleClipMouseDown;
-    /**
-     * 处理片段鼠标移动事件
-     */
-    private handleClipMouseMove;
-    /**
-     * 处理片段鼠标释放事件
-     */
-    private handleClipMouseUp;
-    /**
-     * 处理片段移动结束后的重叠检测和重新排序
-     */
-    private handleClipMoveEnd;
-    /**
-     * 调整片段以解决重叠问题
-     * @param clips 需要调整的片段数组
-     * @param startIndex 开始调整的索引
-     */
-    private adjustClipsForOverlap;
-    /**
-     * 批量更新所有片段状态
-     * @param processedClips 处理后的片段数组
-     */
-    private updateAllClips;
-    /**
-     * 构建并发送更新数据
-     * @param draggedClip 拖动的片段
-     * @param processedClips 处理后的片段数组
-     */
-    private buildAndSendUpdates;
-    /**
-     * 处理舞台鼠标移动事件
-     */
-    private handleStageMouseMove;
-    private isDragSessionActive;
-    private handleDragMove;
-    private maybeAutoScrollDuringDrag;
-    /**
-     * 处理片段鼠标离开事件
-     */
-    private handleClipMouseLeave;
-    /**
-     * 更新片段的视觉状态
-     */
-    private updateClipVisualState;
-    /**
-     * 更新片段组
-     */
-    private updateClipGroup;
-    private handleClipUpdate;
-    private handleClipSplit;
-    addClip(clip: ClipType): void;
-    removeClip(clipId: string): void;
-    updateClip(clipId: string, updates: Partial<ClipType>): void;
-    setZoom(zoom: number): void;
-    setCurrentTime(_time: TimeMs): void;
-    setScrollLeft(scrollLeft: number): void;
-    /**
-     * 更新片段的可见性
-     */
-    private updateClipVisibility;
-    setTrackY(trackY: number): void;
-    render(): void;
-    getClips(): ClipType[];
-    getSelectedClip(): ClipType | null;
-    /**
-     * 选择指定的片段
-     * @param clipId 目标片段的 ID
-     */
-    selectClip(clipId: string): void;
-    splitSelectedClip(time: TimeMs): void;
-    /**
-     * 删除轨道内片段之间的空隙
-     */
-    removeClipGaps(): void;
-    /**
-     * 获取轨道组
-     */
-    getTrackGroup(): Konva.Group;
-    /**
-     * 获取轨道ID
-     */
-    getId(): string;
-}

package/dist/core/timelineManager.d.ts

@@ -1,226 +0,0 @@
-import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener as TimelineEventListener, VideoPreviewConfig, TimelineExportData, ThumbnailProvider } from './types';
-export declare class TimelineManager {
-    private timeline;
-    private tracks;
-    private playhead;
-    private history;
-    private config;
-    private eventListeners;
-    private animationFrameId;
-    private lastUpdateTime;
-    private isInitialized;
-    private stage;
-    private gridLayer;
-    private trackLayer;
-    private playheadLayer;
-    private selectionLayer;
-    private resizeObserver;
-    private videoPreview;
-    private isExecutingHistoryAction;
-    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;
-    pause(): void;
-    togglePlay(): void;
-    private animate;
-    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;
-    /**
-     * 设置播放倍速
-     * @param speed 播放倍速，默认为 1.0
-     */
-    setSpeed(speed: number): void;
-    /**
-     * 获取当前播放倍速
-     * @returns 当前播放倍速
-     */
-    getSpeed(): number;
-    /**
-     * 获取当前是否可以播放
-     * @returns 是否可以播放
-     */
-    getCanPlay(): boolean;
-    /**
-     * 当前是否存在视频源加载任务（例如 addClip 期间读取视频时长）
-     */
-    isSourceLoading(): boolean;
-    /**
-     * 获取视频源加载状态
-     */
-    getSourceLoadingState(): {
-        isLoading: boolean;
-        pending: number;
-    };
-    /**
-     * 设置缩略图提供器
-     * @param provider 缩略图提供器
-     */
-    setThumbnailProvider(provider: ThumbnailProvider): void;
-    /**
-     * 加载片段的封面
-     * @param clip 片段对象
-     * @returns Promise<boolean> 加载是否成功
-     */
-    private loadClipThumbnails;
-    /**
-     * 刷新指定片段的封面
-     * @param clipId 片段 ID
-     * @returns Promise<boolean> 刷新是否成功
-     */
-    refreshClipThumbnails(clipId: string): Promise<boolean>;
-    /**
-     * 刷新所有片段的封面
-     * @returns Promise<boolean[]> 每个片段的刷新结果
-     */
-    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;
-    splitCurrentClip(): void;
-    getClips(): Clip[];
-    exportTimeline(): TimelineExportData;
-    getClipsData(): Clip[];
-    /**
-   * 获取插件版本号
-   */
-    getVersion(): string;
-    undo(): boolean;
-    redo(): boolean;
-    getHistoryState(): {
-        past: Action[];
-        future: Action[];
-    };
-    /** 调整缩放比例以适应当前所有片段 */
-    fitZoom(): void;
-    /** 删除轨道内clip 间的空隙 */
-    removeClipGaps(): void;
-    private handleTimeChange;
-    private handleZoomChange;
-    private handleScrollChange;
-    private handleTrackAutoScrollRequest;
-    private handleClipUpdate;
-    private handleClipAdd;
-    private handleClipRemove;
-    /**
-     * 检查并重新加载关键帧（如果需要）
-     * @param clip 更新后的片段
-     * @param originalClip 原始片段
-     */
-    private reloadClipThumbnailsIfNeeded;
-    /**
-     * 更新 canPlay 状态
-     */
-    private updateCanPlayState;
-    private handleClipSplit;
-    private handleClipSelect;
-    private handleActionUndo;
-    private handleActionRedo;
-    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;
-    /**
-     * 调整时间轴大小以适配容器
-     * @param width 新的宽度
-     * @param height 新的高度
-     */
-    resize(width: number, height: number): void;
-    /**
-     * 滚动到指定时间
-     * @param time 目标时间（毫秒）
-     * @param setCurrentTime 是否同时将当前时间设置为该时间点，默认为 false
-     */
-    scrollToTime(time: TimeMs, setCurrentTime?: boolean): void;
-    /**
-     * 选择指定的片段
-     * @param clipId 目标片段的 ID
-     */
-    selectClip(clipId: string): void;
-    /**
-     * 滚动到指定片段
-     * @param clipId 目标片段的 ID
-     * @param options 配置选项
-     */
-    scrollToClip(clipId: string, options?: {
-        selectClip?: boolean;
-        setCurrentTime?: boolean;
-    }): void;
-    /**
-     * 获取当前时间点所在的clip
-     * @returns 当前时间点所在的clip，如果没有则返回null
-     */
-    /**
-     * 获取当前选中的 clip
-     * @returns 当前选中的 clip，如果没有则返回 null
-     */
-    getSelectedClip(): Clip | null;
-    getCurrentClip(): Clip | null;
-    /**
-     * 删除当前选中的 clip
-     * @returns 是否成功删除了选中的 clip
-     */
-    removeSelectedClip(): boolean;
-    /**
-     * 获取轨道内的总时长（包含空隙）
-     * @returns 从0到最后一个clip结束时间的总时长（毫秒）
-     */
-    getTrackTotalDuration(): TimeMs;
-    destroy(): void;
-    connectTo(videoElement: HTMLVideoElement): void;
-    connectTo(config: VideoPreviewConfig): void;
-    disconnectVideo(): void;
-    /** 清除历史堆栈 */
-    clearHistory(): void;
-    private handleVideoTimeUpdate;
-    private getLastClipByEndTime;
-    private handlePlayStateChange;
-    private handleClipChange;
-    private findClipAtTime;
-    private loadClipToVideo;
-    private attachVideoBufferingListeners;
-    private detachVideoBufferingListeners;
-    private enterBuffering;
-    private exitBuffering;
-    private clearBufferingStateForNoSource;
-    /**
-     * 检查轨道总时长是否变化，如果变化则触发事件并更新时间轴时长
-     */
-    private checkTrackDurationChange;
-}