@linker-design-plus/timeline-track 1.0.1 → 1.0.3

package/README.md

@@ -19,6 +19,8 @@
 - ✅ 历史记录变更通知事件，用于外部应用调整撤销/重做按钮状态
 - ✅ 播放倍速控制，支持 0.1x 到 10x 的播放速度
 - ✅ 轨道总时长计算，包含片段间隙
+- ✅ 封面系统，支持自定义缩略图提供器
+- ✅ 异步封面加载，支持 Promise 形式的封面获取
 
 ## 安装
 
@@ -51,7 +53,8 @@ const clipId = await timelineManager.addClip({
   src: 'sample-video.mp4',
   name: 'Clip 1',
   startTimeAtSource: 0, // 源视频中的开始时间（毫秒）
-  duration: 5000 // 片段持续时间（毫秒）
+  duration: 5000, // 片段持续时间（毫秒）
+  thumbnail: 'https://example.com/thumbnail1.jpg' // 可选：直接提供封面图片
 });
 
 // 开始播放
@@ -80,6 +83,44 @@ timelineManager.on('history_change', (event, data) => {
 // timelineManager.destroy();
 ```
 
+### 封面系统用法
+
+```typescript
+import { TimelineManager, ThumbnailProvider } from '@linker-design-plus/timeline-track';
+
+// 创建缩略图提供器
+const thumbnailProvider: ThumbnailProvider = {
+  getThumbnail(clip) {
+    // 同步获取封面
+    return `https://example.com/thumbnails/${clip.id}.jpg`;
+    
+    // 或异步获取封面
+    // return new Promise((resolve) => {
+    //   // 模拟异步获取封面
+    //   setTimeout(() => {
+    //     resolve(`https://example.com/thumbnails/${clip.id}.jpg`);
+    //   }, 100);
+    // });
+  }
+};
+
+// 创建 TimelineManager 实例时设置缩略图提供器
+const timelineManager = new TimelineManager({
+  container: timelineContainer,
+  thumbnailProvider: thumbnailProvider
+});
+
+// 或动态设置缩略图提供器
+timelineManager.setThumbnailProvider(thumbnailProvider);
+
+// 添加片段时，会自动通过提供器获取封面
+const clipId = await timelineManager.addClip({
+  src: 'sample-video.mp4',
+  name: 'Clip 1',
+  duration: 5000
+});
+```
+
 ### Vue 3 集成
 
 ```vue
@@ -272,6 +313,7 @@ new TimelineManager(config?: Partial<TimelineConfig>)
   - `currentTime`：初始当前时间（毫秒），默认 0
   - `playState`：初始播放状态，默认 'paused'
   - `speed`：初始播放倍速，默认 1.0
+  - `thumbnailProvider`：缩略图提供器，用于获取片段封面
 
 #### 核心方法
 
@@ -285,7 +327,8 @@ new TimelineManager(config?: Partial<TimelineConfig>)
 | `setZoom(zoom)` | 设置缩放比例 | `zoom`：缩放比例（像素/秒） | 无 |
 | `getZoom()` | 获取缩放比例 | 无 | `number` |
 | `setSpeed(speed)` | 设置播放倍速 | `speed`：播放倍速 | 无 |
-| `getSpeed()` | 获取播放倍速 | 无 | `number` |
+| `getSpeed()` | 获取当前播放倍速 | 无 | `number` |
+| `setThumbnailProvider(provider)` | 设置缩略图提供器 | `provider`：缩略图提供器 | 无 |
 | `addClip(clipConfig)` | 添加片段 | `clipConfig`：片段配置 | `Promise<string>`（片段 ID） |
 | `removeClip(clipId)` | 移除片段 | `clipId`：片段 ID | 无 |
 | `removeSelectedClip()` | 移除当前选中的片段 | 无 | `boolean`（是否成功） |

package/dist/components/Timeline.d.ts

@@ -15,10 +15,12 @@ export declare class Timeline {
     private onScrollChange;
     private animationFrameId;
     private isZooming;
+    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 handleZoom;
     private animateZoom;
+    private animateHorizontalScroll;
     private easeOutCubic;
     private handleClick;
     private pixelToTime;
@@ -33,6 +35,19 @@ export declare class Timeline {
     getConfig(): TimelineConfig;
     getScrollLeft(): number;
     setScrollLeft(scrollLeft: number): void;
+    /**
+     * 滚动到指定时间
+     * @param time 目标时间（毫秒）
+     */
+    scrollToTime(time: TimeMs): void;
+    /**
+     * 滚动到指定片段
+     * @param clip 目标片段
+     */
+    scrollToClip(clip: {
+        startTime: TimeMs;
+        duration: TimeMs;
+    }): void;
     /**
      * 获取舞台实例
      */

package/dist/components/VideoTrack.d.ts

@@ -101,6 +101,11 @@ export declare class VideoTrack {
     render(): void;
     getClips(): ClipType[];
     getSelectedClip(): ClipType | null;
+    /**
+     * 选择指定的片段
+     * @param clipId 目标片段的 ID
+     */
+    selectClip(clipId: string): void;
     splitSelectedClip(time: TimeMs): void;
     /**
      * 删除轨道内片段之间的空隙

package/dist/core/constants.d.ts

@@ -18,3 +18,4 @@ export declare const TIME_SCALE: {
     MIN_HEIGHT: number;
     MAX_HEIGHT: number;
 };
+export declare const TIMELINE_LEFT_PADDING = 15;

package/dist/core/timelineManager.d.ts

@@ -1,4 +1,4 @@
-import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener, VideoPreviewConfig, TimelineExportData } from './types';
+import { TimelineConfig, Clip, ClipConfig, TimeMs, PlayState, Action, TimelineEvent, EventListener, VideoPreviewConfig, TimelineExportData, ThumbnailProvider } from './types';
 
 export declare class TimelineManager {
     private timeline;
@@ -15,9 +15,11 @@ export declare class TimelineManager {
     private trackLayer;
     private playheadLayer;
     private selectionLayer;
+    private resizeObserver;
     private videoPreview;
     private isExecutingHistoryAction;
     private lastTrackDuration;
+    private thumbnailProvider;
     constructor(config?: Partial<TimelineConfig>);
     init(container: HTMLElement): void;
     play(): void;
@@ -38,9 +40,14 @@ export declare class TimelineManager {
      * @returns 当前播放倍速
      */
     getSpeed(): number;
+    /**
+     * 设置缩略图提供器
+     * @param provider 缩略图提供器
+     */
+    setThumbnailProvider(provider: ThumbnailProvider): void;
     addClip(clipConfig: ClipConfig): Promise<string>;
     removeClip(clipId: string): void;
-    updateClip(clipId: string, updates: Partial<ClipConfig>): void;
+    updateClip(clipId: string, updates: Partial<Clip>): void;
     splitClip(clipId: string, time: TimeMs): void;
     splitCurrentClip(): void;
     getClips(): Clip[];
@@ -72,6 +79,32 @@ export declare class TimelineManager {
     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

package/dist/core/types.d.ts

@@ -6,8 +6,17 @@ export interface LogConfig {
     level?: LogLevel;
     moduleLevels?: Record<string, LogLevel>;
 }
+export interface ThumbnailProvider {
+    /**
+     * 获取片段的封面图片
+     * @param clip 片段对象
+     * @returns 封面图片URL、Promise<URL>或封面图片URL数组、Promise<URL数组>
+     */
+    getThumbnails(clip: Clip): string[] | Promise<string[]>;
+}
 export interface ClipConfig {
     id?: string;
+    externalId?: string;
     src: string;
     name: string;
     startTime?: TimeMs;
@@ -15,11 +24,12 @@ export interface ClipConfig {
     startTimeAtSource?: TimeMs;
     endTimeAtSource?: TimeMs;
     sourceDuration?: TimeMs;
-    thumbnail?: string;
+    thumbnails?: string[];
     style?: Record<string, any>;
 }
 export interface Clip {
     id: string;
+    externalId?: string;
     src: string;
     name: string;
     startTime: TimeMs;
@@ -35,7 +45,7 @@ export interface Clip {
     isSelected: boolean;
     zIndex: number;
     opacity: number;
-    thumbnail?: string;
+    thumbnails?: string[];
     style?: Record<string, any>;
 }
 export interface TrackConfig {
@@ -57,11 +67,13 @@ export interface Theme {
     clipName: string;
     clipDuration: string;
     clipHandle: string;
+    clipCoverBackground: string;
     clipSelectedBackground: string;
     clipSelectedBorder: string;
     clipSelectedName: string;
     clipSelectedDuration: string;
     clipSelectedHandle: string;
+    clipSelectedCoverBackground: string;
     playhead: string;
     grid: string;
 }
@@ -76,6 +88,7 @@ export interface TimelineConfig {
     timeScaleHeight?: number;
     debug?: boolean;
     speed?: number;
+    thumbnailProvider?: ThumbnailProvider;
 }
 export interface VideoPreviewConfig {
     videoElement: HTMLVideoElement;
@@ -129,6 +142,7 @@ export interface TimelineManagerConfig {
     initialDuration?: TimeMs;
     initialZoom?: number;
     logConfig?: LogConfig;
+    thumbnailProvider?: ThumbnailProvider;
 }
 export interface TimelineExportData {
     version: string;
@@ -141,6 +155,7 @@ export interface TrackExportData {
 }
 export interface ClipExportData {
     id: string;
+    externalId?: string;
     src: string;
     name: string;
     startTime: TimeMs;
@@ -149,5 +164,5 @@ export interface ClipExportData {
     startTimeAtSource: TimeMs;
     endTimeAtSource: TimeMs;
     sourceDuration: TimeMs;
-    thumbnail?: string;
+    thumbnails?: string[];
 }