@linker-design-plus/timeline-track

v2.1.0

Published

a day ago

A TypeScript-based video editing library with timeline and track functionality

Downloads

2,056

0High
0Medium
0Low

video editor timeline track typescript

@linker-design-plus/timeline-track

基于 TypeScript、Konva 和 Vue demo 的时间线编辑组件库，对外以 TimelineManager 为统一入口，提供多轨片段编辑、拖拽/拉伸/分割、撤销重做、选中态同步、封面渲染和预览挂载能力。时间轴主体仍由 Konva 驱动，播放指针使用独立的 SVG/DOM 覆盖层渲染。

当前状态

主线重构已经完成，仓库已从“双轨实现 + 大量兼容层”收敛到单一轨道组件 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。

安装

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

快速开始

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',
  keyboardShortcuts: {
    bindings: {
      togglePlay: 'Mod+Alt+P'
    }
  }
});

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);
});

预览资源缓存

预览资源缓存默认关闭。开启后，可被前端 fetch 读取且不超过 100MB 的 http: / https: 音视频文件会被缓存到浏览器存储中，用于后续预览播放。默认策略为 30 天 TTL、10GB 应用级容量上限、优先 OPFS，并在 OPFS 不可用时降级到 IndexedDB Blob。缓存失败会自动回退原始媒体 URL。

const timeline = new TimelineManager({
  container,
  previewBackend: 'dom',
  resourceCache: {
    enabled: true,
    resolveMode: 'prefer-fast-start'
  }
});

第一版不会缓存 HLS manifest / 分片，也不会缓存超过 100MB 的媒体文件。

核心能力

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

主要 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()
getRenderedHeight()
undo() / redo() / clearHistory()
attachPreview(containerOrConfig) / detachPreview()
exportTimeline() / loadDraft(data)

快捷键配置：

keyboardShortcuts: false 可彻底关闭快捷键
keyboardShortcuts.bindings 可按动作覆盖默认键位
时间轴挂载后默认在当前页面生效

默认快捷键：

播放 / 暂停：Space
删除片段：Delete / Backspace
复制片段：Mod+C
剪切片段：Mod+X
粘贴片段：Mod+V
分离 / 还原音频：Mod+Alt+A
分割片段：Mod+B
撤销：Mod+Z
还原：Mod+Shift+Z，Windows 另支持 Ctrl+Y

常用事件：

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

关键类型

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 配置，请把它当作保留参数，而不是当前版本的有效能力
挂载预览且当前时间命中视频片段时，播放时间由预览视频的真实媒体时钟驱动；媒体 buffering 或 stalled 导致画面没有前进时，播放指针也不会继续超前
多视频叠加播放时，任意一路 active 视频仍在加载或卡顿，预览层会暂停整个 active 播放组，等当前时刻所有视频都 ready 后统一恢复
空白段、纯音频、文本或未挂载预览时，播放仍回退到 TimelineManager 的 wall-clock 推进

架构概览

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["Presentation Views\nTimeline / Track / Clip / Panels / ManagedPlayhead"]

当前最值得关注的热点：

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

目录结构

src/
  components/   时间轴视图、SVG/DOM 覆盖层与交互 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

开发

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@linker-design-plus/timeline-track

当前状态

审计结论

安装

快速开始

预览资源缓存

核心能力

主要 API

关键类型

预览实现说明

架构概览

目录结构

开发

相关文档