@linker-design-plus/timeline-track 1.0.1

package/README.md

@@ -0,0 +1,387 @@
+# @linker-design-plus/timeline-track
+
+基于 TypeScript 和 Konva.js 的高性能视频编辑时间线库，支持拖拽、缩放、分割等核心功能，集成了完整的操作历史记录和日志系统。
+
+## 核心功能
+
+- ✅ 交互式时间线，支持水平缩放（鼠标滚轮/触摸手势）
+- ✅ 视频轨道系统，支持多个片段的拖拽、调整大小、分割功能
+- ✅ 播放头指针，用于精确时间指示
+- ✅ 操作历史记录，支持撤销/重做功能
+- ✅ Canvas-based 渲染，确保高性能
+- ✅ 外部 API，用于片段管理、时间同步和播放控制
+- ✅ 片段碰撞检测，防止重叠
+- ✅ 片段边界限制，确保在轨道范围内
+- ✅ 原视频长度边界限制，确保剪辑不超出原视频范围
+- ✅ 日志系统，支持调试模式开关
+- ✅ 间隙移除功能，自动删除片段之间的间隙
+- ✅ 批量片段更新，提高性能
+- ✅ 历史记录变更通知事件，用于外部应用调整撤销/重做按钮状态
+- ✅ 播放倍速控制，支持 0.1x 到 10x 的播放速度
+- ✅ 轨道总时长计算，包含片段间隙
+
+## 安装
+
+```bash
+npm install @linker-design-plus/timeline-track
+```
+
+## 快速开始
+
+### 基本用法
+
+```typescript
+import { TimelineManager } from '@linker-design-plus/timeline-track';
+
+// 获取容器元素
+const timelineContainer = document.getElementById('timeline-container');
+const videoElement = document.getElementById('video-element') as HTMLVideoElement;
+
+// 创建 TimelineManager 实例
+const timelineManager = new TimelineManager({
+  container: timelineContainer,
+  debug: true, // 开启调试模式
+});
+
+// 连接到视频元素（可选）
+timelineManager.connectTo(videoElement);
+
+// 添加片段
+const clipId = await timelineManager.addClip({
+  src: 'sample-video.mp4',
+  name: 'Clip 1',
+  startTimeAtSource: 0, // 源视频中的开始时间（毫秒）
+  duration: 5000 // 片段持续时间（毫秒）
+});
+
+// 开始播放
+timelineManager.play();
+
+// 设置播放倍速
+timelineManager.setSpeed(2); // 2 倍速
+
+// 适合缩放（自动调整缩放比例以适应所有片段）
+timelineManager.fitZoom();
+
+// 分割当前时间点的片段
+timelineManager.splitCurrentClip();
+
+// 移除片段之间的间隙
+timelineManager.removeClipGaps();
+
+// 监听历史记录变更事件
+timelineManager.on('history_change', (event, data) => {
+  console.log('History changed:', data);
+  // 更新撤销/重做按钮状态
+  updateUndoRedoButtons(data.canUndo, data.canRedo);
+});
+
+// 销毁时间轴管理器
+// timelineManager.destroy();
+```
+
+### Vue 3 集成
+
+```vue
+<template>
+  <div class="app">
+    <div class="video-container">
+      <video ref="videoElement" class="video" controls playsinline></video>
+    </div>
+    
+    <div class="controls">
+      <button @click="togglePlay">{{ isPlaying ? 'Pause' : 'Play' }}</button>
+      <button @click="fitZoom">适合缩放</button>
+      <button @click="removeClipGaps">移除间隙</button>
+      <button @click="undo" :disabled="!canUndo">Undo</button>
+      <button @click="redo" :disabled="!canRedo">Redo</button>
+      <button @click="addClip">Add Clip</button>
+      <button @click="splitClip">Split Clip</button>
+    </div>
+
+    <div class="timeline-container" ref="timelineContainer"></div>
+
+    <div class="info-panel">
+      <div>Current Time: {{ formattedTime }}</div>
+      <div>Zoom: {{ zoom }} px/s</div>
+      <div>Clips: {{ clipCount }}</div>
+      <div>Status: {{ isPlaying ? 'Playing' : 'Paused' }}</div>
+      <div>Speed: {{ speed }}x</div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted, computed } from 'vue';
+import { TimelineManager } from '@linker-design-plus/timeline-track';
+
+// 容器引用
+const timelineContainer = ref<HTMLDivElement | null>(null);
+const videoElement = ref<HTMLVideoElement | null>(null);
+
+// 状态
+const isPlaying = ref(false);
+const currentTime = ref(0);
+const zoom = ref(100);
+const clipCount = ref(0);
+const canUndo = ref(false);
+const canRedo = ref(false);
+const speed = ref(1.0);
+
+// TimelineManager 实例
+let timelineManager: TimelineManager | null = null;
+
+// 格式化时间显示
+const formattedTime = computed(() => {
+  const totalSeconds = Math.floor(currentTime.value / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
+});
+
+// 初始化
+onMounted(async () => {
+  if (!timelineContainer.value) return;
+
+  // 创建 TimelineManager 实例
+  timelineManager = new TimelineManager({
+    container: timelineContainer.value,
+    debug: true,
+  });
+
+  // 连接到视频元素
+  if (videoElement.value) {
+    timelineManager.connectTo(videoElement.value);
+  }
+
+  // 添加事件监听器
+  timelineManager.on('time_change', (event, data) => {
+    currentTime.value = data.time;
+  });
+
+  timelineManager.on('play_state_change', (event, data) => {
+    isPlaying.value = data.playState === 'playing';
+  });
+
+  timelineManager.on('zoom_change', (event, data) => {
+    zoom.value = data.zoom;
+  });
+
+  timelineManager.on('history_change', (event, data) => {
+    canUndo.value = data.canUndo;
+    canRedo.value = data.canRedo;
+  });
+
+  timelineManager.on('speed_change', (event, data) => {
+    speed.value = data.speed;
+  });
+
+  // 添加示例片段
+  await addSampleClips();
+  updateClipCount();
+
+  // 初始设置
+  zoom.value = timelineManager.getZoom();
+  speed.value = timelineManager.getSpeed();
+});
+
+// 清理
+onUnmounted(() => {
+  timelineManager?.destroy();
+});
+
+// 控制方法
+const togglePlay = () => timelineManager?.togglePlay();
+const undo = () => timelineManager?.undo();
+const redo = () => timelineManager?.redo();
+const fitZoom = () => timelineManager?.fitZoom();
+const removeClipGaps = () => timelineManager?.removeClipGaps();
+
+// 添加片段
+const addClip = async () => {
+  if (!timelineManager) return;
+  
+  const clipId = await timelineManager.addClip({
+    src: 'sample-video.mp4',
+    name: `Clip ${Date.now()}`,
+    duration: 5000,
+    startTimeAtSource: 0
+  });
+  updateClipCount();
+};
+
+// 分割片段
+const splitClip = () => timelineManager?.splitCurrentClip();
+
+// 更新片段计数
+const updateClipCount = () => {
+  if (timelineManager) {
+    clipCount.value = timelineManager.getClips().length;
+  }
+};
+
+// 添加示例片段
+const addSampleClips = async () => {
+  if (!timelineManager) return;
+  
+  const clips = [
+    {
+      src: 'sample1.mp4',
+      name: 'Clip 1',
+      startTimeAtSource: 0,
+      duration: 5000
+    },
+    {
+      src: 'sample2.mp4',
+      name: 'Clip 2',
+      startTimeAtSource: 0,
+      duration: 8000
+    }
+  ];
+
+  for (const clip of clips) {
+    await timelineManager.addClip(clip);
+  }
+  
+  timelineManager.clearHistory();
+};
+</script>
+
+<style scoped>
+/* 样式省略 */
+</style>
+```
+
+## API 文档
+
+### TimelineManager
+
+#### 构造函数
+
+```typescript
+new TimelineManager(config?: Partial<TimelineConfig>)
+```
+
+**参数：**
+- `config`：配置选项
+  - `container`：容器元素
+  - `debug`：是否开启调试模式，默认 false
+  - `duration`：总时长（毫秒），默认 3600000
+  - `zoom`：缩放比例（像素/秒），默认 100
+  - `currentTime`：初始当前时间（毫秒），默认 0
+  - `playState`：初始播放状态，默认 'paused'
+  - `speed`：初始播放倍速，默认 1.0
+
+#### 核心方法
+
+| 方法名 | 描述 | 参数 | 返回值 |
+|--------|------|------|--------|
+| `play()` | 开始播放 | 无 | 无 |
+| `pause()` | 暂停播放 | 无 | 无 |
+| `togglePlay()` | 切换播放状态 | 无 | 无 |
+| `setCurrentTime(time)` | 设置当前时间 | `time`：时间（毫秒） | 无 |
+| `getCurrentTime()` | 获取当前时间 | 无 | `number` |
+| `setZoom(zoom)` | 设置缩放比例 | `zoom`：缩放比例（像素/秒） | 无 |
+| `getZoom()` | 获取缩放比例 | 无 | `number` |
+| `setSpeed(speed)` | 设置播放倍速 | `speed`：播放倍速 | 无 |
+| `getSpeed()` | 获取播放倍速 | 无 | `number` |
+| `addClip(clipConfig)` | 添加片段 | `clipConfig`：片段配置 | `Promise<string>`（片段 ID） |
+| `removeClip(clipId)` | 移除片段 | `clipId`：片段 ID | 无 |
+| `removeSelectedClip()` | 移除当前选中的片段 | 无 | `boolean`（是否成功） |
+| `splitCurrentClip()` | 分割当前时间点的片段 | 无 | 无 |
+| `removeClipGaps()` | 移除片段之间的间隙 | 无 | 无 |
+| `fitZoom()` | 自动调整缩放比例以适应所有片段 | 无 | 无 |
+| `getClips()` | 获取所有片段 | 无 | `Clip[]` |
+| `getCurrentClip()` | 获取当前时间点所在的片段 | 无 | `Clip` 或 `null` |
+| `getSelectedClip()` | 获取当前选中的片段 | 无 | `Clip` 或 `null` |
+| `getTrackTotalDuration()` | 获取轨道总时长（包含间隙） | 无 | `number` |
+| `exportTimeline()` | 导出时间轴数据 | 无 | `TimelineExportData` |
+| `undo()` | 撤销操作 | 无 | `boolean`（是否成功） |
+| `redo()` | 重做操作 | 无 | `boolean`（是否成功） |
+| `clearHistory()` | 清空历史记录 | 无 | 无 |
+| `connectTo(video)` | 连接到视频元素 | `video`：视频元素 | 无 |
+| `on(event, listener)` | 添加事件监听器 | `event`：事件类型，`listener`：事件监听器 | 无 |
+| `off(event, listener)` | 移除事件监听器 | `event`：事件类型，`listener`：事件监听器 | 无 |
+| `destroy()` | 销毁时间轴管理器 | 无 | 无 |
+
+#### 事件
+
+| 事件名 | 描述 | 数据 |
+|--------|------|------|
+| `time_change` | 当前时间变化 | `{ time: number }` |
+| `play_state_change` | 播放状态变化 | `{ playState: 'playing' \| 'paused' }` |
+| `speed_change` | 播放倍速变化 | `{ speed: number }` |
+| `clip_added` | 添加片段 | `{ clip: Clip }` |
+| `clip_removed` | 移除片段 | `{ clipId: string }` |
+| `clip_updated` | 更新片段 | `{ clip: Clip }` |
+| `clip_selected` | 选择片段 | `{ clip: Clip }` |
+| `zoom_change` | 缩放比例变化 | `{ zoom: number }` |
+| `history_change` | 历史记录变更 | `{ canUndo: boolean, canRedo: boolean }` |
+| `track_duration_change` | 轨道总时长变化 | `{ duration: number }` |
+
+### ClipConfig 接口
+
+```typescript
+interface ClipConfig {
+  src: string; // 视频源 URL
+  name?: string; // 片段名称
+  duration: number; // 片段持续时间（毫秒）
+  startTimeAtSource?: number; // 源视频中的开始时间（毫秒）
+  startTime?: number; // 片段在轨道上的起始时间（可选，自动计算）
+  thumbnail?: string; // 缩略图 URL
+}
+```
+
+## 开发指南
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 预览构建结果
+
+```bash
+npm run preview
+```
+
+## 浏览器兼容性
+
+- Chrome (推荐)
+- Firefox
+- Safari
+- Edge
+
+## 许可证
+
+MIT
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 更新日志
+
+### v1.0.0-beta.1
+- 首次发布
+- 基于 TypeScript 和 Konva.js 构建
+- 实现核心视频编辑时间线功能
+- 支持片段拖拽、调整大小、分割
+- 集成操作历史记录系统
+- 支持播放倍速控制
+- 提供完整的外部 API
+- 包含 TypeScript 类型声明

package/dist/components/Clip.d.ts

@@ -0,0 +1,57 @@
+import { default as Konva } from 'konva';
+import { Clip as ClipType, Position } from '../core/types';
+
+export declare class Clip {
+    private clip;
+    private onUpdate;
+    private onSplit;
+    private isMoving;
+    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;
+    /**
+     * 创建Konva片段组
+     */
+    createKonvaGroup(zoom: number, scrollLeft: number, _trackY: number, trackHeight: number): Konva.Group;
+    /**
+     * 渲染调整手柄
+     */
+    private renderResizeHandles;
+    /**
+     * 更新Konva片段组
+     */
+    updateKonvaGroup(group: Konva.Group, zoom: number, scrollLeft: number, trackHeight: number): void;
+}

package/dist/components/Playhead.d.ts

@@ -0,0 +1,28 @@
+import { default as Konva } from 'konva';
+import { TimeMs, Theme } from '../core/types';
+
+export declare class Playhead {
+    private layer;
+    private playheadGroup;
+    private playheadLine;
+    private playheadTriangle;
+    private theme;
+    private currentTime;
+    private zoom;
+    private scrollLeft;
+    private onTimeChange;
+    private isDragging;
+    constructor(layer: Konva.Layer, initialTime: TimeMs, zoom: number, height: number, theme: Theme, onTimeChange: (time: TimeMs) => void);
+    private initEventListeners;
+    private handleMouseMove;
+    setTime(time: TimeMs): void;
+    setZoom(zoom: number): void;
+    setScrollLeft(scrollLeft: number): void;
+    setHeight(height: number): void;
+    render(): void;
+    getTime(): TimeMs;
+    /**
+     * 获取播放头组
+     */
+    getPlayheadGroup(): Konva.Group;
+}

package/dist/components/Timeline.d.ts

@@ -0,0 +1,48 @@
+import { default as Konva } from 'konva';
+import { TimelineConfig, TimeMs } from '../core/types';
+
+export declare class Timeline {
+    private stage;
+    private gridLayer;
+    private config;
+    private theme;
+    private isDragging;
+    private startDragX;
+    private scrollLeft;
+    private timeScaleHeight;
+    private onTimeChange;
+    private onZoomChange;
+    private onScrollChange;
+    private animationFrameId;
+    private isZooming;
+    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 easeOutCubic;
+    private handleClick;
+    private pixelToTime;
+    private timeToPixel;
+    setCurrentTime(time: TimeMs): void;
+    setZoom(zoom: number): void;
+    setDuration(duration: TimeMs): void;
+    setPlayState(playState: 'playing' | 'paused'): void;
+    update(): void;
+    private render;
+    private renderTimeTicks;
+    getConfig(): TimelineConfig;
+    getScrollLeft(): number;
+    setScrollLeft(scrollLeft: number): void;
+    /**
+     * 获取舞台实例
+     */
+    getStage(): Konva.Stage;
+    /**
+     * 获取网格图层
+     */
+    getGridLayer(): Konva.Layer;
+    /**
+     * 调整大小
+     */
+    resize(_width: number, _height: number): void;
+}

package/dist/components/VideoTrack.d.ts

@@ -0,0 +1,117 @@
+import { default as 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;
+    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);
+    private initClips;
+    private initEventListeners;
+    /**
+     * 创建片段组
+     */
+    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 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;
+    splitSelectedClip(time: TimeMs): void;
+    /**
+     * 删除轨道内片段之间的空隙
+     */
+    removeClipGaps(): void;
+    /**
+     * 获取轨道组
+     */
+    getTrackGroup(): Konva.Group;
+    /**
+     * 获取轨道ID
+     */
+    getId(): string;
+}

package/dist/core/clipManager.d.ts

@@ -0,0 +1,54 @@
+import { Clip, ClipConfig } from './types';
+
+export declare class ClipManager {
+    private clips;
+    private onClipChange;
+    constructor(onClipChange: (clips: Clip[]) => void);
+    /**
+     * 添加片段
+     */
+    addClip(config: ClipConfig): string;
+    /**
+     * 获取片段
+     */
+    getClip(id: string): Clip | undefined;
+    /**
+     * 获取所有片段
+     */
+    getAllClips(): Clip[];
+    /**
+     * 更新片段
+     */
+    updateClip(id: string, updates: Partial<ClipConfig>): boolean;
+    /**
+     * 移除片段
+     */
+    removeClip(id: string): boolean;
+    /**
+     * 移除所有片段
+     */
+    removeAllClips(): void;
+    /**
+     * 分割片段
+     */
+    splitClip(id: string, splitTime: number): {
+        clip1: Clip;
+        clip2: Clip;
+    } | null;
+    /**
+     * 检查片段是否存在
+     */
+    exists(id: string): boolean;
+    /**
+     * 根据时间范围获取片段
+     */
+    getClipsInTimeRange(startTime: number, endTime: number): Clip[];
+    /**
+     * 获取片段数量
+     */
+    getClipCount(): number;
+    /**
+     * 批量添加片段
+     */
+    addClips(configs: ClipConfig[]): string[];
+}