Clips 元素详解

Clip 是时间线上的基本元素，代表在特定时间段显示的内容。

基础属性

所有 Clip 共享的基础属性：

interface BaseClip {
  id?: string;           // 元素唯一标识
  type: ClipType;        // 元素类型
  start: number;         // 开始时间（秒）
  duration: number;      // 持续时长（秒）
  transform?: Transform; // 变换属性
  style?: Style;         // 样式属性
  animations?: Animation[]; // 动画列表
  keyframes?: Keyframe[];   // 关键帧动画
  transition?: Transition; // 转场效果
  zIndex?: number;        // 层级顺序
}

属性	类型	必填	默认值	描述
id	string	否	-	元素唯一标识符，用于调试
type	ClipType	是	-	元素类型
start	number	是	-	在时间线上的开始时间（秒）
duration	number	是	-	元素显示时长（秒）
transform	Transform	否	-	变换属性（位置/缩放/旋转）
style	Style	否	-	样式属性（颜色/字体等）
animations	Animation[]	否	[]	动画列表
keyframes	Keyframe[]	否	[]	关键帧动画
transition	Transition	否	-	转场效果
zIndex	number	否	0	层级顺序（数值越大越在上层）

支持的元素类型

类型	描述	特有属性
video	视频片段	src, source, volume, muted
image	图片	src
text	文本	text
rect	矩形	width, height
circle	圆形	size, startAngle, endAngle
audio	音频	src, volume, loop, fadeIn, fadeOut
layout	布局容器	direction, gap, padding, children
subtitle	字幕	words, config

Video Clip

视频元素，用于显示视频文件。

interface VideoClip extends BaseClip {
  type: 'video';
  src: string | { $ref: string };  // 视频 URL 或资源引用
  source?: {
    start: number;  // 源视频开始点（秒）
    end: number;    // 源视频结束点（秒）
  };
  volume?: number;   // 音量 0-1
  muted?: boolean;   // 是否静音
}

示例

{
  "type": "video",
  "src": "https://example.com/video.mp4",
  "start": 0,
  "duration": 10,
  "source": {
    "start": 5,
    "end": 15
  },
  "volume": 0.8,
  "muted": false,
  "transform": {
    "x": "50%",
    "y": "50%",
    "width": "100%",
    "height": "100%",
    "anchor": "center"
  },
  "zIndex": 5
}

Image Clip

图片元素，用于显示静态图片。

interface ImageClip extends BaseClip {
  type: 'image';
  src: string | { $ref: string };  // 图片 URL 或资源引用
}

示例

{
  "type": "image",
  "src": "https://example.com/image.png",
  "start": 2,
  "duration": 5,
  "transform": {
    "x": "50%",
    "y": "50%",
    "width": 800,
    "height": 600,
    "anchor": "center"
  },
  "style": {
    "opacity": 1,
    "borderRadius": 10
  },
  "animations": [
    { "type": "fadeIn", "duration": 0.5 },
    { "type": "zoomIn", "duration": 0.5 }
  ],
  "zIndex": 10
}

Text Clip

文本元素，用于显示文字内容。

interface TextClip extends BaseClip {
  type: 'text';
  text: string;  // 文本内容
}

示例

{
  "type": "text",
  "text": "Hello World",
  "start": 1,
  "duration": 5,
  "transform": {
    "x": "50%",
    "y": "50%",
    "anchor": "center"
  },
  "style": {
    "fontSize": 72,
    "fontFamily": "Roboto",
    "fontWeight": 700,
    "fill": "#ffffff",
    "shadowColor": "#000000",
    "shadowBlur": 20
  },
  "animations": [
    { "type": "fadeIn", "duration": 1 },
    { "type": "slideIn", "direction": "up", "duration": 1 }
  ],
  "zIndex": 10
}

Rect Clip

矩形元素，用于创建矩形/方形区域。

interface RectClip extends BaseClip {
  type: 'rect';
}

示例

{
  "type": "rect",
  "start": 0,
  "duration": 20,
  "transform": {
    "x": 0,
    "y": 0,
    "width": 1920,
    "height": 1080
  },
  "style": {
    "fill": {
      "type": "linear",
      "angle": 135,
      "stops": [
        { "offset": 0, "color": "#1a1a2e" },
        { "offset": 1, "color": "#0f3460" }
      ]
    }
  },
  "zIndex": 0
}

Circle Clip

圆形元素，用于创建圆形/椭圆。

interface CircleClip extends BaseClip {
  type: 'circle';
  size: number;        // 直径
  startAngle?: number; // 起始角度（扇形）
  endAngle?: number;   // 结束角度（扇形）
}

示例

{
  "type": "circle",
  "size": 100,
  "start": 0,
  "duration": 10,
  "transform": {
    "x": 100,
    "y": 100
  },
  "style": {
    "fill": "#ff5733",
    "opacity": 0.6
  },
  "animations": [
    { "type": "scale", "from": 0.5, "to": 1.2, "duration": 3, "loop": true }
  ],
  "zIndex": 1
}

Audio Clip

音频元素，用于播放音效或配音。

interface AudioClip extends BaseClip {
  type: 'audio';
  src: string | { $ref: string };  // 音频 URL 或资源引用
  volume?: number;   // 音量 0-1
  loop?: boolean;    // 是否循环
  fadeIn?: number;   // 淡入时长（秒）
  fadeOut?: number;  // 淡出时长（秒）
}

示例

{
  "type": "audio",
  "src": "https://example.com/sound.mp3",
  "start": 5,
  "duration": 3,
  "volume": 0.8,
  "fadeIn": 0.5,
  "fadeOut": 0.5
}

时间计算

开始时间：clip.start 决定元素何时出现
结束时间：clip.start + clip.duration
活跃判断：start <= currentTime < start + duration

最佳实践

ID 命名：使用有意义的 ID，如 title-text, bg-video
时间安排：确保 clip 之间没有时间冲突（除非有意为之）
zIndex 规划：按层次分配 zIndex，便于管理
资源引用：复用资源时使用 { $ref: "id" } 格式
动画协调：多个动画可以同时执行，注意时间配合

Clips 元素详解

On this page