npm package: @linker-design-plus/timeline-track
Description: A TypeScript-based video editing library with timeline and track functionality
Author: yygf94half@163.com
Latest version: 2.0.11

# @linker-design-plus/timeline-track

基于 TypeScript、Konva 和 Vue demo 的时间线编辑组件库，对外以 `TimelineManager` 为统一入口，提供多轨片段编辑、拖拽/拉伸/分割、撤销重做、选中态同步、封面渲染和预览挂载能力。

## 当前状态

- 主线重构已经完成，仓库已从“双轨实现 + 大量兼容层”收敛到单一轨道组件 `Track`
- `TimelineManager` 仍然是 façade，但内部已经拆分为 `stores`、`commands`、`controllers`、`tracks`、`presentation`
- 当前发布包实际内置的预览实现是 `DomPreviewBackend`
- `previewBackend` 配置仍然保留，但当前实现会统一解析到 `dom`，不要把 `canvas` / `auto` 视为已交付能力
- 仓库内保留了较完整的回归测试，适合继续做功能收敛和架构瘦身

## 审计结论

本轮已完成一次针对仓库现状的维护梳理，并同步修正了以下残留：

- 修复了 3 处测试残留，使 `pnpm test` 与 `pnpm exec tsc -p tsconfig.json --noEmit` 恢复通过
- 清理了 `pixi` 预览类型和 demo 入口中的过期选项
- 把 README 与重构路线文档改为“当前真实状态”，不再把未交付的 canvas 预览写成已完成能力
- 把 `build` 脚本改为直接调用本地 `tsc`，避免 `npm run build:types` 带来的环境告警

更细的维护记录见 [docs/maintenance-audit.md](./docs/maintenance-audit.md)。

## 安装

```bash
pnpm add @linker-design-plus/timeline-track konva
```

## 快速开始

```ts
import { TimelineManager } from '@linker-design-plus/timeline-track';

const container = document.getElementById('timeline-container') as HTMLDivElement;
const preview = document.getElementById('preview-container') as HTMLDivElement;

const timeline = new TimelineManager({
  container,
  zoom: 100,
  currentTime: 0,
  previewBackend: 'dom'
});

timeline.attachPreview(preview);

await timeline.addClip({
  src: 'sample-video.mp4',
  name: 'Clip 1',
  startTimeAtSource: 0,
  duration: 5000,
  visualTransform: {
    x: 0.5,
    y: 0.5,
    scale: 1
  }
});

timeline.on('history_change', (_event, data) => {
  console.log(data.canUndo, data.canRedo);
});
```

## 核心能力

- 多轨时间线编辑，支持视频轨和音频轨
- 片段拖拽、拉伸、分割、跨轨移动和重叠避让
- 单一选中态与批量拖拽
- 播放头、缩放、滚动和时间同步
- 撤销 / 重做 / 历史变更通知
- 缩略图提供器与异步封面加载
- 预览容器挂载、预览比例同步和当前激活片段解析
- 草稿导入导出、音视频分离/恢复等编辑工作流

## 主要 API

常用方法：

- `play()` / `pause()` / `togglePlay()`
- `setCurrentTime(time)` / `getCurrentTime()`
- `setZoom(zoom)` / `fitZoom()`
- `setSpeed(speed)` / `getSpeed()`
- `addClip(config)` / `addClips(configs)`
- `updateClip(clipId, updates)` / `removeClip(clipId)`
- `selectClip(clipId)` / `clearSelection()` / `getSelectedClip()`
- `splitCurrentClip()` / `removeClipGaps()`
- `undo()` / `redo()` / `clearHistory()`
- `attachPreview(containerOrConfig)` / `detachPreview()`
- `exportTimeline()` / `loadDraft(data)`

常用事件：

- `time_change`
- `play_state_change`
- `zoom_change`
- `clip_added`
- `clip_removed`
- `clip_updated`
- `clip_selected`
- `selected_clip_change`
- `history_change`
- `track_duration_change`
- `buffering_state_change`
- `source_loading_change`

## 关键类型

```ts
interface ClipConfig {
  id?: string;
  type?: 'video' | 'audio';
  externalId?: string;
  src: string;
  name: string;
  isMuted?: boolean;
  startTime?: number;
  duration: number;
  startTimeAtSource?: number;
  endTimeAtSource?: number;
  sourceDuration?: number;
  thumbnails?: string[];
  style?: Record<string, any>;
  visualTransform?: {
    x: number;
    y: number;
    scale: number;
  };
  trackId?: string;
  volume?: number;
}
```

## 预览实现说明

- 当前代码路径实际只会创建 `DomPreviewBackend`
- `previewBackend` 字段被保留，目的是不给后续预览实现扩展制造额外 breaking change
- 如果你在业务接入层看到 `canvas` / `auto` 配置，请把它当作保留参数，而不是当前版本的有效能力

## 架构概览

```mermaid
flowchart TB
  API["Public API\nsrc/index.ts"] --> FACADE["TimelineManager\nsrc/core/facade/timelineManager.ts"]
  FACADE --> STORES["Stores\nTimeline / Selection / Playback / Viewport"]
  FACADE --> COMMANDS["Commands\nTimelineCommands"]
  FACADE --> CONTROLLERS["Controllers\nworkflow / selection / duration / playback / events"]
  FACADE --> TRACKS["Tracks\nTrackManager / Bridge / Collection"]
  FACADE --> PRESENTATION["Presentation\nTimelinePresentationAdapter"]
  FACADE --> PREVIEW["Preview\nDomPreviewBackend"]
  FACADE --> COMPONENTS["Konva Views\nTimeline / Track / Clip / Playhead / Panels"]
```

当前最值得关注的热点：

- `src/core/facade/timelineManager.ts` 仍然超过 4k 行，是后续最重要的瘦身目标
- `src/components/track/Track.tsx` 内部还保留一层 `legacy` 交互镜像，用于兼容旧拖拽状态
- `src/utils/rendering/KonvaUtils.ts` 仍偏大，适合继续拆分为更小的渲染工具模块
- `demo/App.vue` 既承担演示又承担诊断面板职责，维护成本偏高

## 目录结构

```text
src/
  components/   Konva 组件与交互 helper
  core/         stores / commands / controllers / facade / models
  utils/        渲染、时间和日志工具
  styles/       样式入口
  index.ts      对外导出
docs/
  interaction-model.md
  maintenance-audit.md
  refactor-roadmap.md
demo/
  App.vue
  main.ts
```

## 开发

```bash
pnpm install
pnpm dev
pnpm build
pnpm test
pnpm exec tsc -p tsconfig.json --noEmit
```

## 相关文档

- [docs/interaction-model.md](./docs/interaction-model.md): 指针交互分层和拖拽约束
- [docs/refactor-roadmap.md](./docs/refactor-roadmap.md): 主线重构归档与后续收敛方向
- [docs/maintenance-audit.md](./docs/maintenance-audit.md): 本轮仓库审计、验证结果和依赖建议
- [docs/review-remediation-plan.md](./docs/review-remediation-plan.md): 基于审查结论的修复计划与阶段性落地建议