editor-gui

编辑器工具包

通过组合 GUI 组件来构建视频编辑界面。每个组件都是一个独立的自定义元素。每个组件通过 target 属性连接到你的合成。使用 composition 技能构建合成本身。这些组件为它添加控件和视图。

快速开始

<ef-timegroup id="my-video">
  <ef-video src="/video.mp4"></ef-video>
</ef-timegroup>

<ef-controls target="my-video">
  <ef-toggle-play></ef-toggle-play>
  <ef-scrubber></ef-scrubber>
  <ef-time-display></ef-time-display>
</ef-controls>

这里的 ef-timegroup 未设置 mode，因此默认值为 contain。它的时长取自 video.mp4 本身的长度，而不是硬编码的数字。有关完整的时长模型，请参阅 composition 技能中的“时间组与排序”部分。

核心概念：Target 与 Bridge

每个播放控件（ef-play、ef-pause、ef-toggle-play、ef-toggle-loop、ef-volume、ef-mute、ef-scrubber、ef-time-display）都会按以下顺序解析它所控制的合成：

1. 如果设置了自身的 target="id-or-selector" 属性，则使用该属性直接解析。
2. 否则，它会向上遍历祖先 ef-controls、ef-preview 和 ef-configuration 元素。带有自身 target 的祖先会在一步内解析到目标。没有设置 target 的 ef-configuration 祖先会解析为自身。控件会越过未设置 target 的 ef-controls 或 ef-preview 祖先，继续向上查找。
3. 最后，它会解析到最近的外层时间根节点。

ef-controls 是一个纯代理，本身不渲染任何内容。它为一组后代控件设置共享的 target，这样每个控件就不必单独设置：

<ef-timegroup id="my-video" mode="contain">…</ef-timegroup>


<ef-controls target="my-video">
  <ef-toggle-play></ef-toggle-play>
  <ef-scrubber></ef-scrubber>
</ef-controls>

ef-canvas、ef-hierarchy 和 ef-timeline 通过另一套独立机制共享选择状态：一个以解析后的合成根节点为键的共享 SelectionBridge。这与上面的播放桥接机制无关。在 ef-hierarchy 中选择一行会在 ef-canvas 中高亮该行，反之亦然。两个元素都不需要直接引用对方。

预览与画布

ef-preview 是一个轻量的透传容器。它会追踪指针悬停在哪个元素上，并触发 focus-changed。ef-canvas 内部使用它来高亮悬停的元素。

ef-canvas 与 ef-preview 一样，会将你的组合内容作为轻 DOM 子元素包裹起来。它会直接在你的组合内容上添加点击选择、拖动移动、角点调整大小和旋转功能。它通过 SelectionBridge 与 ef-hierarchy 和 ef-timeline 共享选中状态。如果你没有显式设置 target，它会自动将第一个已分配的时间子元素的 id 设为 target。设置 readonly 可使叠加层保持可见但不可交互。

<ef-canvas class="relative">
  <ef-timegroup id="scene" mode="contain" class="w-[1920px] h-[1080px]">
    <ef-video id="bg" src="/bg.mp4" class="absolute inset-0 size-full object-cover"></ef-video>
    <ef-text id="title" duration="5s" class="absolute top-12 left-12 text-6xl text-white">Title</ef-text>
  </ef-timegroup>
</ef-canvas>

• 点击可选择的元素（任何带有 id 的 TemporalElement）即可选中它。此操作会替换当前选中项。
• 点击画布空白背景可取消选择。
• 从空白背景处拖动即可绘制套索框。此操作会选中套索框触及的所有元素。释放鼠标时按住 Shift 或 Cmd/Ctrl，可将选中项添加到现有选择中，而不是替换它。
• 拖动选框主体可移动它。
• 拖动角点或边缘控点可调整大小。按住 Shift 可锁定宽高比。按住 Cmd/Ctrl 可从中心调整大小。
• 拖动旋转控点可旋转。按住 Shift 可按 15° 的增量吸附。
• 拖动、调整大小或旋转手势结束后，ef-canvas 会触发一次 canvas-transform 事件（{ elementId }）。拖动过程中不会持续触发该事件。
• ef-canvas 不内置键盘支持：不支持方向键微移、删除等操作。它也不支持通过 Shift-单击或 Cmd-单击单个元素进行多选。只有套索拖动支持添加式多选。

ef-pan-zoom 会将内容包裹在可平移、缩放的视口中。拖动即可平移。使用滚轮或捏合手势即可缩放。它提供 screenToCanvas()、canvasToScreen()、reset() 和 fitToContent() 方法，以及 transform-changed 事件。它没有 shadow root。其内容包装器是一个普通的轻 DOM 子元素，可通过 [part="content"] 访问。

ef-fit-scale 是一个轻 DOM 容器。它会缩放第一个子元素以适应可用空间，同时保持宽高比。每次 ResizeObserver 或 MutationObserver 发生变化时，它都会重新计算缩放比例。通常可用它将固定分辨率的组合内容包裹在 ef-pan-zoom 中。

播放与显示控制

播放或暂停时，ef-play 和 ef-pause 会分别隐藏自身。将你自己的按钮作为默认插槽内容放入其中。点击 ef-toggle-play 会切换其 slot="play"/slot="pause" 内容。点击 ef-toggle-loop 会切换循环模式。以上三个元素都会通过前述 target/bridge 模式解析目标。

ef-volume 是一个原生范围滑块，范围为 0 到 1，并绑定到解析出的组合内容的音量。点击 ef-mute 会切换其 slot="muted"/slot="unmuted" 内容。ef-fullscreen 和 ef-pip 会在其 target 上切换全屏和画中画 API。点击时，两者都会切换其 slot="enter"/slot="exit" 内容。ef-pip 的目标可以是 <video>、<canvas>（通过 captureStream()），或用于在其中搜索的容器。ef-resolution 是一个下拉菜单，附带自定义宽度和高度输入框。它会设置 target 元素的内联 CSS 尺寸，并触发 resolution-change。

时间线

ef-timeline 将固定的层级列、每个元素的轨道行和时间标尺组合到一个可滚动区域中。它会自动为每一行中的每个可修剪视频或音频元素添加修剪手柄、缩略图条和波形条。无需任何启用标志。

<ef-timegroup id="comp" mode="sequence" class="w-[1920px] h-[1080px]">
  <ef-video src="/clip.mp4" duration="5s"></ef-video>
  <ef-text duration="5s">Title</ef-text>
</ef-timegroup>

<div class="h-64">
  <ef-timeline target="comp" pixels-per-second="80"></ef-timeline>
</div>

ef-timeline 通过 SelectionBridge 与 ef-canvas/ef-hierarchy 共享选择状态，并为每一行触发 timeline-select。它没有筛选属性（hide/show）、缩放限制属性或面板可见性属性。实际支持的少量属性请参阅下方的元素参考。

独立时间线组件（也可在 ef-timeline 外使用，且均在下方的元素参考中完整介绍）：

• ef-scrubber — 播放头拖动控件。orientation="horizontal"（默认值）会渲染带拖动手柄的进度条，宽度与轨道自身相同。orientation="vertical" 会渲染一条细播放头线，通过 pixels-per-second 定位，可用于滚动时间线轨道内。其时间单位为毫秒（current-time-ms、duration-ms）。
• ef-time-display — 根据解析后的 PlaybackBridge，将以秒为单位的 currentTime / duration 格式化为 M:SS / M:SS。它只接受 target。它不接受独立的 current-time-ms/duration-ms 覆盖属性。
• ef-timeline-ruler — 使用 Canvas 渲染刻度线和秒数标签。它读取 duration、pixels-per-second 和 fps，或读取 Motion-Designer 风格时间线所用的 duration-ms 和 zoom-scale。
• ef-trim-handles — 可拖动的入点和出点。mode="standalone" 会在两个手柄之间显示一个可拖动的完整区域。mode="track" 会将手柄固定在容器边缘。ef-timeline 的行使用此模式。其时间单位为秒（intrinsic-duration、pixels-per-second），与 ef-scrubber 的单位约定不同。value（{start, end}）是 JS 属性，不是 HTML 属性。它会持续触发 trim-change，并触发一次 trim-change-end。
• ef-thumbnail-strip 和 ef-waveform-strip — 直接镜像源 <ef-video>/<ef-audio> 的属性：src、variants、sourcein/sourceout、trimstart/trimend。两者都不接受 target ID 引用。独立使用时，请将这些属性与源元素并列设置，或从源元素复制这些属性。在 ef-timeline 内，这些关联会按行自动完成。

变换与操作

ef-transform-handles 是受控叠加层。它不会自行跟踪目标元素。通过其 bounds JS 属性显式设置位置：{x, y, width, height, rotation?}，单位为宿主的本地像素。然后将 bounds-change/rotation-change 事件的结果应用回自己的目标元素，并更新 bounds。

<div style="position: relative;">
  <ef-video id="clip" src="/clip.mp4" style="position: absolute; left: 0; top: 0; width: 320px; height: 180px; transform-origin: center;"></ef-video>
  <ef-transform-handles id="handles" enable-rotation></ef-transform-handles>
</div>
<script>
  const clip = document.getElementById("clip");
  const handles = document.getElementById("handles");
  handles.bounds = { x: 0, y: 0, width: 320, height: 180 };
  handles.addEventListener("bounds-change", (e) => {
    const { x, y, width, height } = e.detail.bounds;
    Object.assign(clip.style, { left: `${x}px`, top: `${y}px`, width: `${width}px`, height: `${height}px` });
    handles.bounds = e.detail.bounds;
  });
  handles.addEventListener("rotation-change", (e) => {
    const { rotation } = e.detail;
    clip.style.transform = `rotate(${rotation}deg)`;
    handles.bounds = { ...handles.bounds, rotation };
  });
</script>

调整大小时，按住 Shift 可通过类似 lock-aspect-ratio 的约束锁定宽高比；还可以使用 rotation-step 对角度进行吸附。corners-only 会隐藏边缘手柄。enable-drag、enable-resize 和 enable-rotation 分别独立切换对应的交互。此元素是 ef-canvas 内置选择框所基于的通用构件。需要将变换手柄与画布选择状态分离时，可直接使用它。

ef-dial 是一种圆形拖动控件。它会生成一个 0 到 360 度的 value，并循环变化。value 仅为 JS 属性，没有受监控的 HTML 属性。<ef-dial value="45"> 不会将拨盘初始化为 45°。请在创建元素后设置 .value。拖动时按住 Shift，可按 15° 的增量吸附。它会触发 change。

覆盖层系统

ef-overlay-layer 和 ef-overlay-item 实现了一种不同于 target/bridge 的模式。它们通过共享的 RAF 调度器，在每一帧被动跟随目标元素的屏幕位置，而不是控制播放。ef-overlay-layer 必须与 ef-pan-zoom 同级，或嵌套在其中，才能在用户平移和缩放时保持对齐。

<ef-pan-zoom>
  <ef-fit-scale>
    <ef-timegroup id="comp" mode="contain" class="w-[1920px] h-[1080px]">
      <ef-video id="clip" src="/clip.mp4"></ef-video>
    </ef-timegroup>
  </ef-fit-scale>
</ef-pan-zoom>
<ef-overlay-layer>
  <ef-overlay-item id="clip-overlay">
    <div class="border-2 border-blue-500"></div>
  </ef-overlay-item>
</ef-overlay-layer>
<script>
  document.getElementById("clip-overlay").target = "clip";
</script>

通过 target JS 属性设置目标。传入 CSS 选择器字符串（纯 id 会回退到 getElementById）或直接传入元素引用。element-id HTML 属性提供了另一种查找方式：它会匹配目标的 data-element-id/data-timegroup-id 属性。默认情况下，组合中不会设置这两个数据属性，请自行添加。当跟踪的目标移动超过 0.01px 时，此元素会触发 position-changed，并提供 {x, y, width, height, rotation}。

编辑器外壳

ef-workbench 将层级面板、带选择功能的画布、时间轴和传输控件组合成一个完整的三面板编辑器布局。传输控件（播放、暂停、循环、时间）与工具栏分开。ef-workbench 接受一个默认插槽，即你的组合；如果组合尚未包装在 <ef-configuration>/<ef-canvas> 中，它会自动进行包装。它没有 slot="canvas"、slot="hierarchy" 或 slot="timeline" 插槽。

<ef-workbench class="w-full h-screen" resolution="1920x1080">
  <ef-timegroup mode="sequence" class="w-[1920px] h-[1080px]">
    <ef-timegroup mode="fixed" duration="3s">
      <ef-text duration="3s">Opening</ef-text>
    </ef-timegroup>
    <ef-video src="/clip.mp4"></ef-video>
  </ef-timegroup>
</ef-workbench>

resolution（"WIDTHxHEIGHT"）用于设置组合实际渲染的尺寸。这是一个固定尺寸的舞台，ef-pan-zoom/fitToContent() 会将其缩放以适应视图。调用 .exportVideo(options?) 可通过离屏渲染克隆将组合渲染为 MP4。实时预览不会受到影响。此方法会派发冒泡的 export-start、export-progress、export-complete 和 export-error 事件。工具栏中的“导出”按钮使用同一方法。.previewMode JS 属性（"dom" | "canvas"，不是属性）可在实时 DOM 组合和画布光栅化预览之间切换。原生渲染宿主会将 rendering 设为启用状态，使工作台折叠为仅显示裸舞台。正常使用时，不要将 rendering 当作“隐藏工具栏”的便捷标志。

ef-hierarchy 是一个独立的图层面板树。可单独使用，不依赖 ef-workbench。它与 ef-canvas 共享相同的 target/选择共享模式。将这两个元素都指向同一个组合根 id，而不是 ef-canvas 自身的 id，这样它们的 SelectionBridge 才能解析到同一个根并保持同步：

<ef-hierarchy target="comp" show-header header="Layers" class="w-64"></ef-hierarchy>
<ef-canvas>
  <ef-timegroup id="comp" mode="contain" class="w-[1920px] h-[1080px]">…</ef-timegroup>
</ef-canvas>

它通过 SelectionBridge 与 ef-canvas/ef-timeline 共享选择状态，而不是通过 @lit/context。此版本的 Editframe 完全移除了 @lit/context。.select(id) 和 .getSelectedElementId() 用于控制选择状态。.setHighlighted(el) 和 .getHighlightedElement() 用于控制悬停高亮，并会触发 hierarchy-highlight。拖动行会触发 hierarchy-reorder，并提供 { sourceId, targetId, position }。hideSelectors 和 showSelectors（字符串数组形式的 JS 属性，不是属性）可通过 CSS 选择器筛选显示的元素。

发送反馈

向 Editframe 反馈问题和改进建议：

• 如果 Editframe 或此技能导致问题，请找到变通方法并继续任务。然后报告问题和变通方法。
• 如果你发现也能帮助其他任务（而不仅是当前任务）的改进，请发送建议。例如，建议更清晰的说明、缺失的示例、更好的默认设置或新功能。

每个不同的问题或建议分别提交一份报告。如果报告提交失败，请继续任务。

curl -sS https://editframe.com/api/v1/feedback \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EDITFRAME_API_KEY" \
  --data-binary @- <<'JSON'
{
  "category": "bug",
  "skill": "editor-gui",
  "summary": "One line that names the problem or the suggestion",
  "details": "For a problem: steps, expected result, actual result, and errors. For a suggestion: the change and how it helps.",
  "workaround": "The workaround that you used. Omit this field for a suggestion."
}
JSON

将 category 设为 bug、documentation、feature_request、performance 或 other。API 密钥为可选项。不提供密钥的报告将以匿名方式提交。请勿在报告中填写机密信息、API 密钥或个人数据。所有字段、限制和响应详见 editframe-api 技能。

元素参考

ef-agent-pane

CSS 自定义属性

自定义属性	默认值	描述
--ef-font-family	system-ui	TODO: 文档尚未说明此自定义属性。

ef-ai-editor

共享的创作工作区，包含按修订版本划分的对话和手动编辑。

属性

属性	React 属性	类型	默认值	描述
presentation	presentationMode	"simple" \	"advanced"	—

CSS 自定义属性

自定义属性	默认值	描述
--ef-ai-agent-width	${AGENT_WIDTH_DEFAULT}px	TODO: 文档尚未说明此自定义属性。
--ef-font-family	system-ui, sans-serif	TODO: 文档尚未说明此自定义属性。

插槽

• （默认插槽）— TODO: 文档尚未说明此插槽。

触发事件

• browser-cancel (any) — TODO: 文档尚未说明此事件。
• browser-request (any) — TODO: 文档尚未说明此事件。
• composition-edit (unknown) — TODO: 文档尚未说明此事件。
• connection-error (unknown) — TODO: 文档尚未说明此事件。
• editor-context ({ snapshotId: string; timeMs: number; selectedIds: string[] }) — TODO: 文档尚未说明此事件。
• editor-error (string) — TODO: 文档尚未说明此事件。
• export-complete ({ snapshotId: string; filename: string; byteSize: number; durationMs: number; durationSeconds: number; width: number; height: number; fps: number; mimeType: string; url: string }) — TODO: 文档尚未说明此事件。
• export-end ({ snapshotId: string }) — TODO: 文档尚未说明此事件。
• export-error ({ snapshotId: string; error: string }) — TODO: 文档尚未说明此事件。
• export-job (any) — TODO: 文档尚未说明此事件。
• export-progress ({ snapshotId: string; frame: number; totalFrames: number; time: number; duration: number; elapsedMs: number; estimatedRemainingMs: number; speedMultiplier: number; framePreviewCanvas?: HTMLCanvasElement \| undefined }) — TODO: 文档尚未说明此事件。
• export-start ({ snapshotId: string }) — TODO: 文档尚未说明此事件。
• media-import ({ files: File[]; commit: (result: Promise<void>) => void }) — TODO: 文档尚未说明此事件。
• playback-state (Readonly<{ timeMs: number; durationMs: number; paused: boolean; }>) — TODO: 文档尚未说明此事件。
• snapshot-change ({ snapshotId: string; compositionId: string \| undefined; sequence: number; html: string }) — TODO: 文档尚未说明此事件。
• snapshot-export ({ snapshotId: string; filename: string; byteSize: number; durationMs: number; durationSeconds: number; width: number; height: number; fps: number; mimeType: string; url: string }) — TODO: 文档尚未说明此事件。
• task-change ({ taskId: any; runId: any; status: any }) — TODO: 文档尚未说明此事件。
• workspace-activity (any) — TODO: 文档尚未说明此事件。

ef-asset-rail

用于共享创作的会话媒体标签和导入控件。

ef-canvas

为创作内容的 DOM 子树添加选中和悬停叠加层，支持点击选中、拖动和角点调整大小。

属性

属性	React 属性	类型	默认值	描述
readonly	readonly	boolean	false	禁用选中、拖动、调整大小和旋转交互；叠加层仍会显示，但不可交互。
target	target	string	""	此组件控制或读取的目标元素 ID。

插槽

• （默认插槽）— 向画布注册、用于选中、拖动和调整大小操作的创作元素。

触发事件

• canvas-transform ({ elementId: string }) — 选框上的拖动、调整大小或旋转手势结束时触发。

ef-canvas-selection-box

此元素绘制一个选中框或悬停框。

ef-composition-thumbnail-strip

此元素是嵌套合成的胶片条。

属性

属性	React prop	类型	默认值	说明
duration	duration	number	—	修剪后片段的时长（秒），用于排列缩略图槽位。
height	height	number	—	胶片条的高度（像素），默认为元素渲染后的高度，或 32。
pixels-per-second	pixelsPerSecond	number	100	缩放级别 — 每秒合成时间渲染的像素数。
scroll-left	scrollLeftInClip	number	—	时间轴视口左边缘相对于片段的滚动偏移量。
thumbnail-spacing-px	thumbnailSpacingPx	number	—	缩略图之间的最小间距（像素），默认为 thumbnailWidth。
thumbnail-width	thumbnailWidth	number	—	每个缩略图的宽度（像素），默认为根据 height 计算出的值。
viewport-width	viewportWidth	number	—	可见视口的宽度（像素），用于对缩略图生成进行虚拟化。

CSS 部件

• canvas — 用于渲染胶片条的画布。

ef-controls

<ef-controls target="#preview"> 元素用作代理容器。

属性

属性	React prop	类型	默认值	说明
target	target	string	""	目标元素后代控件默认通过其解析播放的目标元素 ID。

ef-dial

这是一个圆形拨盘，用户可拖动它，将 value 设为 0 到 360 度之间的值。

CSS 自定义属性

自定义属性	默认值	说明
--dial-stroke	var(--ef-color-border, rgba(255,255,255,0.16))	拨盘外环和刻度线基础描边的颜色。
--dial-tick	var(--ef-color-border-subtle, rgba(255,255,255,0.08))	四个主方向刻度线的颜色。

CSS 部件

• container — 拨盘的圆形背景。
• handle — 可拖动的旋钮，用于显示当前值。
• value — 拨盘中央的数值读数。

触发事件

• change（{ value: number }）— 每当用户拖动拨盘将值更改为新值时触发。

ef-fit-scale

此元素是一个轻量 DOM 容器。

属性

属性	React prop	类型	默认值	说明
paused	paused	boolean	false	暂停自动重新计算缩放比例。

ef-fullscreen

此元素可切换目标元素的浏览器 Fullscreen API 状态。

属性

属性	React prop	类型	默认值	说明
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• button — 点击目标，包含插槽中的 enter 和 exit 内容。

插槽

• slot="enter" — 目标元素未处于全屏模式时显示。点击目标即可进入全屏。
• slot="exit" — 目标元素处于全屏模式时显示。点击目标即可退出全屏。

ef-hierarchy

此树能够感知 DOM 组合结构。

属性

属性	React 属性	类型	默认值	描述
header	header	string	""	显示在树上方的标题文本（当设置了 show-header 时）。
show-header	showHeader	boolean	false	是否显示标题行。
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 自定义属性

自定义属性	默认值	描述
--hierarchy-bg	var(--ef-color-bg)	树容器的背景色。
--hierarchy-border	var(--ef-color-border)	边框颜色（标题分隔线）。
--hierarchy-drop-indicator	var(--ef-color-primary)	拖放排序指示线的颜色。
--hierarchy-hover-bg	var(--ef-color-border-subtle)	悬停时行的背景色。
--hierarchy-selected-bg	var(--ef-color-primary-subtle, rgba(110,168,254,0.18))	选中时行的背景色。
--hierarchy-text	var(--ef-color-text)	文本颜色。

CSS 部件

• header — 树项目上方的可选标题。设置 show-header 属性后会显示此部件。
• list — 包含层级树的外层容器。

触发的事件

• hierarchy-highlight（{ element: Element \| null }）— 高亮元素发生变化时触发，例如用户在 ef-canvas 中将鼠标悬停在该元素上时。此事件通过 EFHierarchyElement.setHighlighted 触发。
• hierarchy-reorder（{ sourceId: string; targetId: string; position: "before" \| "after" \| "inside" }）— 用户将某一行拖动到新位置时触发。
• hierarchy-select（{ elementId: string \| null }）— 用户点击元素行，或脚本直接调用 EFHierarchyElement.select 时触发。

方法

• select(elementId: string | null): void — 根据元素 ID 选中元素。传入 null 可清除选中状态。
• getSelectedElementId(): string | null — 返回第一个选中元素的 ID。如果没有选中任何内容，则返回 null。
• getHighlightedElement(): Element | null — 返回当前通过 setHighlighted 高亮的元素。如果没有高亮元素，则返回 null。
• setHighlighted(el: Element | null): void — 设置从此元素外部高亮的元素。例如，用户在 ef-canvas 中将鼠标悬停在某个元素上时，代码可以调用此方法。此方法也会派发 hierarchy-highlight 事件。

ef-hierarchy-item

此元素为 EFHierarchyElement 渲染一行。

CSS 自定义属性

自定义属性	默认值	描述
--hierarchy-drop-indicator	#3b82f6	拖放排序指示线的颜色。
--hierarchy-indent	0.75rem	每个嵌套层级的缩进宽度。
--hierarchy-item-font-size	0.75rem	行标签的字体大小。
--hierarchy-item-height	1.5rem	行高。
--hierarchy-item-padding-left	0.5rem	行的左内边距。

CSS 部件

• badge — 显示元素类型的徽标 span。
• children — 嵌套子项目的包装器。
• label — 显示元素名称的 span。
• row — 此项目行的容器。此部件会接收 data-focused 和 data-selected 属性。

ef-mute

点击此元素可切换静音状态。

属性

属性	React 属性	类型	默认值	描述
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• button — 可点击的目标区域，包含插槽中的 muted 和 unmuted 内容。

插槽

• slot="muted" — 目标静音时显示。点击目标可取消静音。
• slot="unmuted" — 目标未静音时显示。点击目标可将其静音。

ef-overlay-item

此元素是一个被动叠加项。

属性

Attribute	React prop	Type	Default	Description
element-id	elementId	string	—	该叠加项跟踪的目标元素 ID（与 data-element-id/data-timegroup-id 匹配）。

插槽

• （默认插槽）— 此插槽用于放置显示在目标元素上方的内容。

触发事件

• position-changed ({ x: number; y: number; width: number; height: number; rotation: number; }) — 当目标元素的位置、大小或旋转角度变化超过 0.01px 时触发此事件。

ef-overlay-layer

此元素是一个叠加容器。

插槽

• （默认插槽）— 此插槽可接受一个或多个 ef-overlay-item 或 ef-transform-handles 元素。

ef-pause

目标暂停时，此元素会隐藏自身。

属性

Attribute	React prop	Type	Default	Description
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• button — 包含插槽图标或标签内容的点击目标。

插槽

• （默认插槽）— 在此放置自定义按钮或图标元素。点击它可暂停播放。

ef-pip

此元素是画中画切换控件。

属性

Attribute	React prop	Type	Default	Description
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• button — 包含插槽中的 enter 和 exit 内容的点击目标。

插槽

• slot="enter" — 目标未处于画中画模式时显示。点击目标可进入画中画模式。
• slot="exit" — 目标处于画中画模式时显示。点击目标可退出画中画模式。

ef-play

目标播放时，此元素会隐藏自身。

属性

Attribute	React prop	Type	Default	Description
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• button — 包含插槽图标或标签内容的点击目标。

插槽

• （默认插槽）— 在此放置自定义按钮或图标元素。点击它可开始播放。

ef-preview

这是一个轻量级透传容器。

属性

Attribute	React prop	Type	Default	Description
loop	loop	boolean	false	设置后会转发到嵌套的合成根节点，使文档中的 <Preview loop> 能包装播放，而无需将 loop 添加到 timegroup 上。

触发事件

• focus-changed ({ element: HTMLElement \| null }) — 悬停的元素发生变化时触发。detail.element 字段包含新的元素；如果当前没有聚焦元素，则为 null。

ef-recorder

将屏幕和摄像头录制为实时 H.264/AAC MP4。

触发事件

• recording-state ({ which: "screen" \| "camera"; live: boolean }) — TODO：记录此事件的文档。
• workspace-error (string) — TODO：记录此事件的文档。

ef-resolution

此元素是一个分辨率选择器，用于设置 target 元素的内联 CSS width 和 height 样式。

属性

属性	React 属性	类型	默认值	说明
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 自定义属性

自定义属性	默认值	说明
--ef-color-surface	rgba(0, 0, 0, 0.6)	--ef-resolution-bg 的备用背景色来源（目前不属于共享主题令牌集）。
--ef-resolution-bg	var(--ef-color-surface, rgba(0, 0, 0, 0.6))	下拉列表／输入框的背景色。
--ef-resolution-border-color	var(--ef-color-border, rgba(255, 255, 255, 0.2))	下拉列表／输入框的边框颜色。
--ef-resolution-color	var(--ef-color-text, #fff)	文本颜色。
--ef-resolution-font-size	12px	下拉列表／输入框的字体大小。

CSS 部件

• height-input — 自定义高度数字输入框。此部件仅在自定义模式下显示。
• select — 预设分辨率的下拉列表。
• separator — 宽度和高度输入框之间的“×”符号。
• width-input — 自定义宽度数字输入框。此部件仅在自定义模式下显示。

触发事件

• resolution-change（{ width: number; height: number }）— 分辨率变化时触发，事件详情为 { width, height }。变化可能来自选择预设，也可能来自自定义宽度和高度输入。

ef-scrubber

此元素是一个播放头拖动条。

属性

属性	React 属性	类型	默认值	说明
container-width	containerWidth	number	—	以像素为单位的显式容器宽度，用于垂直方向。
current-time-ms	currentTimeMs	number	—	当前播放时间，单位为毫秒。
duration-ms	durationMs	number	—	总时长，单位为毫秒。
fps	fps	number	—	用于按帧量化计算的帧率。
orientation	orientation	"horizontal" \	"vertical"	—
pixels-per-second	pixelsPerSecond	number	—	缩放级别 — 每秒合成时间渲染的像素数。
raw-scrub-time-ms	rawScrubTimeMs	number | null	—	未量化的拖动位置，单位为毫秒；拖动过程中实时更新。
target	target	string	""	此组件控制或读取的目标元素 ID。
zoom-scale	zoomScale	number	—	应用于垂直（时间线）拖动条尺寸的缩放倍数。

CSS 自定义属性

自定义属性	默认值	说明
--ef-scrubber-background	var(--ef-color-border, rgba(255, 255, 255, 0.2))	未填充轨道的颜色。
--ef-scrubber-handle-size	12px	可拖动控件的直径。
--ef-scrubber-height	4px	轨道厚度。
--ef-scrubber-progress-color	var(--ef-color-primary, #fff)	已填充（进度）轨道的颜色。

CSS 部件

• handle — 可拖动的圆形旋钮。
• playhead — 当前时间位置处的垂直线。
• progress — 已填充部分，用于显示当前位置。
• scrubber — 外层轨道容器。

触发事件

• seek（number）— 用户将拖动条拖到新位置时触发。

ef-thumbnail-strip

此元素是一个视频胶片条，缩放和滚动行为与旧版 EFThumbnailStrip 相同。

属性

属性	React prop	类型	默认值	描述
duration	duration	number	—	剪辑修剪后的时长（秒），用于排列缩略图槽位。
height	height	number	—	胶片条的高度（像素）（默认为元素渲染后的高度，或 32）。
pixels-per-second	pixelsPerSecond	number	100	缩放级别 — 每秒合成时间渲染的像素数。
scroll-left	scrollLeftInClip	number	—	时间线视口左边缘相对于剪辑的滚动偏移量。
sourcein	sourcein	string	—	源视频中的起始时间（CSS 时间，例如 "1.5s"），与源 <ef-video> 保持一致。
sourceout	sourceout	string	—	源视频中的结束时间（CSS 时间），与源 <ef-video> 保持一致。
src	src	string	""	用于生成缩略图的源视频文件 URL。
thumbnail-spacing-px	thumbnailSpacingPx	number	—	缩略图之间的最小间距（像素）（默认为 thumbnailWidth）。
thumbnail-width	thumbnailWidth	number	—	每张缩略图的宽度（像素）（默认为根据 height 得出的值）。
trimend	trimend	string	—	从剪辑末尾修剪的时长（CSS 时间），与源 <ef-video> 保持一致。
trimstart	trimstart	string	—	从剪辑开头修剪的时长（CSS 时间），与源 <ef-video> 保持一致。
variants	variants	string	""	自适应变体列表 URL，与源 <ef-video> 保持一致。
viewport-width	viewportWidth	number	—	可见视口宽度（像素），用于虚拟化缩略图生成。

CSS 部件

• canvas — 渲染胶片条的画布部件。

ef-time-display

此元素会格式化已解析的 PlaybackBridge 中以秒为单位的 currentTime 和 duration 值。

属性

属性	React prop	类型	默认值	描述
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 自定义属性

自定义属性	默认值	描述
--ef-font-family	system-ui	字体系列（当前未纳入共享主题令牌集）。
--ef-font-size-xs	0.75rem	字体大小（当前未纳入共享主题令牌集）。

CSS 部件

• time — 显示格式化后的当前时间和时长文本的 span。

ef-timeline

此元素会渲染合成的层级结构和轨道行。

属性

属性	React prop	类型	默认值	描述
follow-playhead	followPlayhead	boolean	true	播放期间自动滚动时间线，使播放头保持可见。
hierarchy-width	labelWidth	number	160	层级面板的宽度（像素）。
pixels-per-second	pixelsPerSecond	number	100	缩放级别 — 每秒合成时间渲染的像素数。
row-height	rowHeight	number	28	每个轨道行的高度（像素）。
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• scrub-overlay — 覆盖整个区域的部件。用户拖动擦洗时，它会捕获指针拖动事件。

ef-timeline-row

此元素用于渲染一条时间线行。

CSS 自定义属性

自定义属性	默认值	描述
--trim-handle-width	6px	覆盖此行中所渲染剪辑内嵌套的 <ef-trim-handles> 自身的 --trim-handle-width。

CSS 部件

• bar — 此部件是有颜色的剪辑条。
• label — 此部件是行的标签区域。它显示元素名称、图标和详细文本。
• track — 此部件是行的轨道区域。它显示剪辑条。

触发事件

• timeline-select（{ elementId: string }）— 用户点击此行时触发此事件。

ef-timeline-ruler

此元素是带刻度线和秒数标签的时间标尺。

属性

属性	React 属性	类型	默认值	描述
duration	duration	number	—	总时长，单位为秒。
duration-ms	durationMs	number	—	总时长，单位为毫秒；未通过 duration 提供时使用（Motion Designer 时间线）。
fps	fps	number	30	帧率——决定何时显示单帧刻度线。
pixels-per-second	pixelsPerSecond	number	100	缩放级别——每秒合成时间渲染的像素数。
zoom-scale	zoomScale	number	—	缩放倍数；当设置了 duration-ms 时，用于推导 effectivePixelsPerSecond。

CSS 部件

• canvas — 此部件是刻度线画布。
• container — 此部件是标尺的外层容器。

ef-toggle-loop

点击此元素可切换已解析的 PlaybackBridge 上的循环模式。

属性

属性	React 属性	类型	默认值	描述
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• button — 点击目标。此部件直接位于 <slot> 元素上。

插槽

• （默认插槽）— 在此处放置自定义按钮或图标元素。点击它可切换循环模式。

ef-toggle-play

点击此元素可在播放和暂停之间切换。

属性

属性	React 属性	类型	默认值	描述
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 部件

• button — 点击目标，包含通过插槽传入的 play 和 pause 内容。

插槽

• slot="pause" — 目标正在播放时显示。点击目标可暂停播放。
• slot="play" — 播放暂停时显示。点击目标可开始播放。

ef-transform-handles

此元素是一个选择叠加层，带有拖动、调整大小和可选的旋转控制柄。

属性

属性	React 属性	类型	默认值	描述
canvas-scale	canvasScale	number	1	当前画布缩放比例，用于保持控制柄的命中区域在屏幕上的尺寸一致。
corners-only	cornersOnly	boolean	false	仅显示角部调整大小控制柄，隐藏边缘控制柄。
enable-drag	enableDrag	boolean	true	允许通过选择区域主体进行拖动。
enable-resize	enableResize	boolean	true	显示调整大小控制柄。
enable-rotation	enableRotation	boolean	false	显示旋转控制柄。
lock-aspect-ratio	lockAspectRatio	boolean	false	将调整大小限制为原始宽高比。
min-size	minSize	number	—	调整大小时的最小宽度／高度（像素）。
rotation-step	rotationStep	number	—	旋转时按角度进行吸附的增量。

CSS 自定义属性

自定义属性	默认值	描述
--ef-transform-handles-border-color	var(--ef-color-primary)	边界框叠加层的轮廓颜色。
--ef-transform-handles-dragging-border-color	var(--ef-color-primary)	拖动时边界框的轮廓颜色。
--ef-transform-handles-handle-border-color	var(--ef-color-primary)	调整大小控制柄的边框颜色。
--ef-transform-handles-handle-color	var(--ef-color-bg-elevated)	调整大小控制柄的填充颜色。
--ef-transform-handles-rotate-handle-color	var(--ef-color-success)	旋转控制柄的颜色。

CSS 部件

• drag-area — 此部件是覆盖整个叠加层的不可见拖动区域。仅当 enable-drag 为 true 时显示。
• handle — 此部件对应所有调整大小控制柄。默认有八个控制柄；当 corners-only 为 true 时有四个。
• handle-e — 此部件是东侧边缘的调整大小控制柄。
• handle-n — 此部件是北侧边缘的调整大小控制柄。
• handle-ne — 此部件是东北角的调整大小控制柄。
• handle-nw — 此部件是西北角的调整大小控制柄。
• handle-s — 此部件是南侧边缘的调整大小控制柄。
• handle-se — 此部件是东南角的调整大小控制柄。
• handle-sw — 此部件是西南角的调整大小控制柄。
• handle-w — 此部件是西侧边缘的调整大小控制柄。
• overlay — 此部件是位于所选元素上方的外部边界框。
• rotate-handle — 此部件是旋转控制柄的命中区域。仅当 enable-rotation 为 true 时显示。
• rotate-handle-circle — 此部件是旋转控制柄内部可见的圆形旋钮。

触发的事件

• bounds-change ({ bounds: { x: number; y: number; width: number; height: number; rotation?: number; } }) — 拖动或调整大小时，每次指针移动都会触发此事件。
• rotation-change ({ rotation: number }) — 拖动旋转控制柄时会触发此事件。

ef-tree

该元素是一个通用的、由数据驱动的树形组件。

属性

属性	React 属性	类型	默认值	说明
expand-all	expandAll	boolean	true	默认展开所有项目。
header	header	string	""	显示在树形组件上方的标题文本（当启用 show-header 时）。
selected-id	selectedId	string | null	—	当前选中项目的 ID。
show-header	showHeader	boolean	false	是否显示标题行。

CSS 自定义属性

自定义属性	默认值	说明
--tree-bg	var(--ef-color-bg)	树形容器的背景颜色。
--tree-border	var(--ef-color-border)	边框颜色。
--tree-hover-bg	var(--ef-color-border-subtle)	鼠标悬停时的行背景颜色。
--tree-selected-bg	var(--ef-color-primary-subtle, rgba(110,168,254,0.18))	选中时的行背景颜色。
--tree-text	var(--ef-color-text)	文本颜色。

CSS 部件

• container — 此部件是树形组件的外层包装器。
• empty — 此部件是空状态提示信息。
• header — 此部件是可选标题。show-header 为 true 时显示。

触发事件

• tree-select（{ id: string \| null; item: TreeItem \| null }）— 用户点击某一行时触发此事件。

ef-tree-item

此元素为 EFTreeElement 渲染一行内容和一个递归的 children 容器。

CSS 自定义属性

自定义属性	默认值	说明
--tree-expand-icon-size	1rem	展开/折叠箭头图标的尺寸。
--tree-icon-gap	0.25rem	图标与标签之间的间距。
--tree-indent	1rem	每个嵌套层级的缩进宽度。
--tree-item-font-size	0.75rem	行标签的字体大小。
--tree-item-height	1.5rem	行高。
--tree-item-padding-left	0.5rem	行的左内边距。
--tree-item-padding-right	0.5rem	行的右内边距。

CSS 部件

• children — 此部件是嵌套子项目的包装器。它会接收 data-collapsed 属性。
• expand-icon — 此部件是展开和折叠箭头。
• icon — 此部件是可选的项目图标。
• label — 此部件是项目标签文本。
• row — 此部件是项目行。它会接收 data-selected 属性。

ef-trim-handles

此元素用于渲染以秒为单位的入点和出点手柄。

属性

属性	React prop	类型	默认值	描述
element-id	elementId	string	""	此修剪手柄所编辑元素的 ID，包含在 trim-change 事件详情中。
intrinsic-duration	intrinsicDuration	number	—	未修剪的源素材时长（秒），用于计算拖动范围。
mode	mode	"standalone" \	"track"	—
pixels-per-second	pixelsPerSecond	number | null	—	缩放级别 — 每秒合成时间渲染的像素数。
seek-target	seekTarget	string	""	用户拖动手柄时要定位的时间元素 ID。
show-overlays	showOverlays	boolean	true	显示覆盖在已修剪部分上的暗色叠层。

CSS 自定义属性

自定义属性	默认值	描述
--trim-handle-active-color	#3b82f6	悬停或拖动时的手柄颜色。
--trim-handle-border-radius-end	0 2px 2px 0	末端（右侧）手柄可见旋钮的边框圆角。
--trim-handle-border-radius-start	2px 0 0 2px	起始端（左侧）手柄可见旋钮的边框圆角。
--trim-handle-color	rgba(255, 255, 255, 0.7)	静止时的手柄颜色。
--trim-handle-width	8px	每个修剪手柄命中区域的宽度。
--trim-overlay-color	rgba(0, 0, 0, 0.4)	绘制在已修剪区域上的暗色叠层颜色。
--trim-selected-border-color	transparent	选中指示器边框的颜色（独立模式）。
--trim-selected-border-width	0px	选中指示器边框的粗细（独立模式）。

CSS 部件

• handle — 此部件匹配两个修剪手柄：起始手柄和末端手柄。
• handle-end — 此部件是右侧的末端修剪手柄。
• handle-inner — 此部件是每个修剪手柄内的可见旋钮。
• handle-start — 此部件是左侧的起始修剪手柄。
• overlay — 此部件匹配两个暗色叠层。每个叠层覆盖一段已修剪区域。
• overlay-end — 此部件是覆盖在已修剪末端部分上的暗色叠层。
• overlay-start — 此部件是覆盖在已修剪起始部分上的暗色叠层。
• region — 此部件是可拖动的中间区域，仅在独立模式下显示。
• selected-border — 此部件匹配选中指示器的边框，仅在独立模式下显示。
• selected-border-bottom — 此部件是选中指示器的底部边框。
• selected-border-top — 此部件是选中指示器的顶部边框。

插槽

• slot="handle-end" — 此插槽用于放置末端修剪手柄可见旋钮的自定义内容。末端手柄位于右侧。
• slot="handle-start" — 此插槽用于放置起始修剪手柄可见旋钮的自定义内容。起始手柄位于左侧。

触发事件

• trim-change（{ elementId: string; type: "start" \| "end" \| "region"; value: { start: number; end: number } }）— 用户拖动修剪手柄或区域时，此事件会持续触发。
• trim-change-end（{ elementId: string; type: "start" \| "end" \| "region" }）— 用户释放修剪手柄后，此事件触发一次。

ef-volume

此元素是一个取值范围为 0 到 1 的滑块。

属性

Attribute	React prop	Type	Default	Description
target	target	string	""	此组件控制或读取的目标元素 ID。

CSS 自定义属性

Custom property	Default	Description
--ef-volume-fill-color	var(--ef-color-primary, #fff)	已填充（进度）轨道的颜色。
--ef-volume-height	4px	轨道和滑块的高度。
--ef-volume-track-color	var(--ef-color-border, rgba(255, 255, 255, 0.2))	未填充轨道的颜色。

CSS 部件

• slider — 原生 <input type="range"> 音量滑块元素。

ef-waveform-strip

此元素是一个时间线波形条。

属性

Attribute	React prop	Type	Default	Description
color	color	string	—	波形颜色（任何有效的 CSS 颜色值）；默认使用音轨的主题颜色。
duration	duration	number	—	剪辑修剪后的时长（秒），用于布局波形。
height	height	number	—	波形条的高度（像素）（默认为元素渲染后的高度，或 32）。
media	media	"audio" \	"video"	—
pixels-per-second	pixelsPerSecond	number	100	缩放级别 — 每秒合成时间渲染的像素数。
scroll-left	scrollLeftInClip	number	—	时间线视口左边缘在剪辑内的滚动偏移 — 与 ef-thumbnail-strip 一致。
sourcein	sourcein	string	—	源中的起始时间（CSS 时间，例如 "1.5s"），与源元素保持一致。
sourceout	sourceout	string	—	源中的结束时间（CSS 时间），与源元素保持一致。
src	src	string	""	用于解码波形包络的源音频/视频文件 URL。
trimend	trimend	string	—	从剪辑末尾修剪的时长（CSS 时间），与源元素保持一致。
trimstart	trimstart	string	—	从剪辑开头修剪的时长（CSS 时间），与源元素保持一致。
variants	variants	string	—	自适应变体列表 URL，与源 <ef-audio>/<ef-video> 保持一致。
viewport-width	viewportWidth	number	—	可见视口宽度（像素），用于对波形绘制进行虚拟化。

CSS 部件

• canvas — 此部件是用于渲染波形的画布。

ef-workbench

此元素将层级面板、画布和选择视图、时间线以及传输控件组合成一个面板布局，仅限 DOM 预览模式。

属性

Attribute	React prop	Type	Default	Description
rendering	rendering	boolean	false	当原生渲染主机（EF_FRAMEGEN）负责帧捕获时为 True — 将工作台收起为仅显示空白的 .stage（不显示工具栏/侧边栏/传输控件/时间线等界面）。
resolution	resolution	string	"1920x1080"	合成的实际渲染分辨率，格式为 "WIDTHxHEIGHT"（例如 "1920x1080"、"1080x1920"）。

CSS 自定义属性

Custom property	Default	Description
--ef-color-danger	#dc2626	危险操作和错误状态的颜色。
--ef-color-hover	#333	工具栏和缩放按钮的悬停背景颜色。
--ef-color-success	#059669	导出弹出层中成功状态的颜色。
--ef-color-text-subtle	var(--ef-color-text-muted)	导出弹出层标签的次要文本颜色。
--ef-color-warning	#d97706	警告和已取消状态的颜色。
--ef-workbench-sidebar-width	260px	左侧层级面板的宽度。
--ef-workbench-timeline-height	260px	底部时间线面板的高度。

插槽 -（默认插槽）— 此插槽用于放置组合内容。组合内容是一个轻 DOM <ef-configuration>、<ef-canvas> 或 <ef-timegroup> 元素，工作台会根据需要自动为其添加包装。

• slot="toolbar-end" — 标题工具栏右侧的扩展点，位于内置主题／导出控件之后。将元素指定为 slot="toolbar-end"。
• slot="toolbar-start" — 标题工具栏左侧的扩展点。将元素指定为 slot="toolbar-start"。这些元素会保留为 <ef-workbench> 的轻 DOM 子元素（因此页面 CSS 和主题的 --ef-color-* 自定义属性仍会应用于它们），并会在渲染模式下与编辑器的其他界面元素一同隐藏。

触发事件

• export-complete（{ /** 使用自定义 target 时省略。 */ buffer?: ArrayBuffer; mimeType: string; }）— 导出成功完成时触发一次此事件，并附带 RenderTimegroupToVideoResult 详情值。
• export-error（unknown）— 导出期间发生错误时触发此事件。详情值包含抛出的错误。
• export-progress（{ frame: number; totalFrames: number; /** 刚完成渲染的组合时间（秒）。 */ time: number; /** 导出的总时长（秒），即 to - from。 */ duration: number; /** 自开始渲染以来经过的墙钟时间（毫秒）。 */ elapsedMs: number; /** * 根据截至目前的平均每帧耗时估算的剩余墙钟时间（毫秒）。首帧生成前为 0。 */ estimatedRemainingMs: number; /** * 每秒墙钟时间内渲染的组合时长（秒）。大于 1表示导出速度快于实时速度。首帧生成前为0。 */ speedMultiplier: number; /** * 最近捕获帧的实时缩略图，每隔 {@link RenderTimegroupToVideoOptions.progressPreviewInterval} 帧就地重绘。 * 每次进度回调都会传入同一个 canvas 实例——请直接嵌入（例如，将其添加到状态弹出框中），而不要复制。 * 当 progressPreviewInterval为0 时省略。 */ framePreviewCanvas?: HTMLCanvasElement; }）— 导出期间会重复触发此事件，并附带一个 RenderProgress 详情值，其中包含帧计数和总帧数。
• export-start（unknown）— EFWorkbenchElement.exportVideo 开始时触发一次此事件。

方法

• exportVideo(options?: RenderTimegroupToVideoOptions): Promise<RenderTimegroupToVideoResult> — 通过离屏 createRenderClone 和 renderTimegroupToVideo 调用，将合成渲染为 MP4。默认以此工作台的 resolution 渲染。实时交互式预览不受影响。此方法会分发冒泡的 export-start、export-progress、export-complete 和 export-error 事件，因此外围 UI 无需轮询即可显示进度。此方法会返回编码后的缓冲区。工具栏上的 Export 按钮也会将缓冲区下载为 .mp4 文件。下载逻辑请参见 .runToolbarExport。
  • options.width（可选）：number — 输出宽度，单位为像素。默认为 timegroup.getBoundingClientRect() 的宽度。
  • options.height（可选）：number — 输出高度，单位为像素。默认为 timegroup.getBoundingClientRect() 的高度。
  • options.fps（可选）：number — 输出帧率。默认为 timegroup.fps。
  • options.from（可选）：number — 导出范围的起点，单位为合成秒数。默认为 0。
  • options.to（可选）：number — 导出范围的终点，单位为合成秒数。默认为完整时长。
  • options.videoCodec（可选）："avc" \| "hevc" \| "vp9" \| "av1" \| "vp8" — 输出视频编解码器。默认为 "avc"。
  • options.audioCodec（可选）："aac" \| "opus" \| "mp3" \| "vorbis" \| "flac" \| "pcm-s16" \| "pcm-s16be" \| "pcm-s24" \| "pcm-s24be" \| "pcm-s32" \| "pcm-s32be" \| "pcm-f32" \| "pcm-f32be" \| "pcm-f64" \| "pcm-f64be" \| "pcm-u8" \| "pcm-s8" \| "ulaw" \| "alaw" — 输出音频编解码器。默认为 AAC。没有原生 AAC 编码器的浏览器（例如 Linux 上的 Chrome）会在首次使用时加载 WASM AAC 编码器。仅当没有 AAC 编码器接受音频设置，或页面的内容安全策略阻止 WASM 编码器时（它需要 blob: workers 和 'wasm-unsafe-eval'），默认设置才会回退到 Opus。
  • options.videoBitrate（可选）：number \| Quality — 原始比特率（单位为每秒比特数），或 mediabunny Quality 预设（例如 QUALITY_HIGH）。默认为 QUALITY_HIGH。
  • options.audioBitrate（可选）：number \| Quality — 原始比特率（单位为每秒比特数），或 mediabunny Quality 预设（例如 QUALITY_HIGH）。默认为 QUALITY_HIGH。
  • options.audioSampleRate（可选）：number — 混合音轨的采样率。默认为 48000。
  • options.includeAudio（可选）：boolean — 当合成包含可处理音频的叶节点时，混合并编码音轨。默认为 true。设为 false 可导出静音视频（仅视频）。
  • options.scale（可选）：number — 按此系数缩小编码后的输出（0.5 = 一半大小的 MP4）。帧仍会以完整合成尺寸捕获，因此合成布局（px 字体、vw 单位、换行）不受影响，然后再绘制到较小的编码画布中，与旧版 Lit 流程的缩放行为一致。默认为 1。
  • options.progressPreviewInterval（可选）：number — 每 N 帧重绘一次 RenderProgress.framePreviewCanvas。默认为 DEFAULT_PROGRESS_PREVIEW_INTERVAL。设为 0 可完全省略预览并跳过其 drawImage 开销。
  • options.strictVideoPaint（可选）：boolean — 传递给 seekForRender。最终渲染捕获时默认为 true。
  • options.prefetchHorizonSec（可选）：number — 设置在导出播放头前方多少秒处打开即将使用的播放层输入。默认为 DEFAULT_EXPORT_PREFETCH_HORIZON_SEC。设为 0 可禁用预取，恢复为先前仅按需即时加载的行为。
  • options.capture（可选）：FrameCaptureStrategy — 将帧捕获到编码画布的方式。"auto"（默认）在浏览器支持时使用原生 HTML-in-Canvas，否则使用 foreignObject 序列化器；两种方式都由浏览器自身引擎进行栅格化，以保证输出符合浏览器的渲染效果。"painter" 会选择交互式预览所用的快速近似 Canvas2D 绘制器。如果正确渲染路径失败，剩余帧会退回到绘制器。
  • options.target（可选）：Target — 覆盖默认的 BufferTarget。例如，可使用 AppendOnlyStreamTarget 作为 EF_RENDER.renderStreaming 分块式 CLI 或 Playwright 输出的目标。设置此项后会省略 result.buffer，因为调用方已通过目标消费字节。此时 fastStart 默认值变为 "fragmented"，而不是 "in-memory"，因为流式目标无法回溯以修改末尾的 moov box。
  • options.fastStart（可选）：false \| "in-memory" \| "reserve" \| "fragmented" — 设置 mediabunny 的 moov 放置策略。默认为 "in-memory"；如果提供了自定义 target，则默认为 "fragmented"。
  • options.videoHardwareAcceleration（可选）："no-preference" \| "prefer-hardware" \| "prefer-software" — 视频编码器的 hardwareAcceleration 设置。默认为 "prefer-hardware"（通过 VideoEncoder.isConfigSupported 检查；不存在 HW 编码器时回退到 "no-preference"）：否则，mediabunny 的量化器比特率模式会选择软件编码器，其速度比 macOS 上的 VideoToolbox 慢约 8 倍。
  • options.signal（可选）：AbortSignal — 中止正在进行的渲染。
  • options.onProgress（可选）：((progress: RenderProgress) => void) — 每编码一帧后调用。