Remotion 文档交互式 Demo 系统从组件到 注册的完整实践【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion本文以 Remotion 仓库中的技能文档 .agents/skills/docs-demo/SKILL.md 为主体系统讲解如何在 Remotion 官方文档站中新增一个可交互的Demo组件包括 demo 组件的编写、DemoType注册、demos数组挂载、MDX 引用方式以及选项options控制体系的完整参数说明。读完本文你可以独立完成一个带滑块、复选框、下拉框等交互控件的文档示例并理解这些控件如何以inputProps的形式驱动remotion/player渲染同时了解 Effects 演示走另一套 schema 驱动注册体系的差异。整体架构两套并行的演示注册体系文档站中的可交互演示基于remotion/player将 Remotion 合成composition内联渲染在 MDX 页面中demo 组件统一存放于 packages/docs/components/demos/ 目录。从源码结构看仓库中存在两套并行的演示体系通用 Demo 体系使用Demo type... /组件定义在 demos/types.ts渲染逻辑在 demos/index.tsx适用于形状库shapes、转场transitions、spring、shader 等各类示例Effects Demo 体系使用EffectsDemo typeeffects-... /注册在 effects-demos/registry.ts。它不复用通用Demo的 options 数组而是直接引用真实 effect 的definition.schemaInteractivitySchema来自动生成控件见 effects-demos/types.ts 中的EffectsDemoTypeexport type EffectsDemoType { id: string; effectName: string; effectImportPath: string; comp: React.FC; schema: InteractivitySchema; initialValues?: Recordstring, unknown; compWidth: number; compHeight: number; fps: number; durationInFrames: number; autoPlay: boolean; controls: boolean; logLevel: LogLevel; };因此为remotion/effects中的某个效果写演示时应走EffectsDemo注册路径下文第六节而形状、转场、动画原语等示例则走本文重点讲解的通用Demo流程。第一步创建 demo 组件在 packages/docs/components/demos/ 下新建组件文件例如MyDemo.tsx。它就是一个标准的 React 组件可以使用useCurrentFrame()、useVideoConfig()等 Remotion hooks。以现存的 Circle.tsx 为例它演示了 demo 组件的典型形态import {Circle} from remotion/shapes; import React from react; import {AbsoluteFill} from remotion; export const CircleDemo: React.FC{ readonly radius: number; readonly darkMode: boolean; } ({radius, darkMode}) { return ( AbsoluteFill style{{ justifyContent: center, alignItems: center, }} Circle fill{darkMode ? white : var(--ifm-link-color)} radius{radius} / /AbsoluteFill ); };这里有两点值得注意组件把交互参数如radius声明为普通 React props——这些 props 正是注册时options数组中各项name对应的值由框架通过inputProps注入见第五节框架还会额外注入一个darkMode布尔值表示文档站当前是否处于深色模式组件可据此调整配色。这一注入点在 demos/index.tsx 第 308 行可以确认inputProps{{...state, darkMode: colorMode dark}}。第二步注册 DemoType在 demos/types.ts 中导入组件并导出一个DemoType对象。技能文档要求的核心字段是id在Demo type... /中引用的唯一字符串、compReact 组件、compWidth/compHeight画布尺寸如 1280x720、fps帧率通常 30、durationInFrames动画时长、autoPlay是否自动播放、options交互控件数组可为空[]。而源码中DemoType的实际定义types.ts 第 111–122 行比技能文档列出的字段更完整还包含controls与logLevel两个字段export type DemoType { id: string; comp: React.FC; compWidth: number; compHeight: number; fps: number; durationInFrames: number; options: Option[]; autoPlay: boolean; controls: boolean; logLevel: LogLevel; };字段类型说明idstring唯一标识供Demo typemy-demo /引用compReact.FC要渲染的演示组件compWidth/compHeightnumber合成画布宽高现有 demo 多为 1280×720 或 1280×400转场小示例用 540×280fpsnumber帧率现有注册项统一为 30durationInFramesnumber总帧数现有 demo 多为 150 帧5 秒 30fps转场演示用 60–90 帧optionsOption[]播放器下方的交互控件定义可为空数组autoPlayboolean是否自动播放现有转场/噪声类 demo 为true形状类多为falsecontrolsboolean是否显示播放器原生控制条源码中所有注册项均为falselogLevelLogLevel传入Player的日志级别源码中统一为info技能文档给出的最简注册示例如下对应无交互参数的演示export const myDemo: DemoType { comp: MyDemoComp, compHeight: 720, compWidth: 1280, durationInFrames: 150, fps: 30, id: my-demo, autoPlay: true, options: [], };实际仓库中的注册项还补全了controls与logLevel字段例如 types.ts 第 889–900 行的fadePresentationDemoexport const fadePresentationDemo: DemoType { comp: FadeDemo, compHeight: 280, compWidth: 540, durationInFrames: 60, fps: 30, id: fade, autoPlay: true, controls: false, logLevel: info, options: [], };第三步加入 demos 数组在 demos/index.tsx 中从./types导入你导出的 demo 常量并把它追加到模块级demos数组第 116–180 行。该数组目前挂载了 60 多个演示项涵盖 HTML-in-Canvas、形状库、转场、spring、shader、rough-notation、TransitionSeries 等类别const demos: DemoType[] [ htmlInCanvasDemo2DBlur, // ... arrowDemo, triangleDemo, rectDemo, calloutDemo, // ... fadePresentationDemo, pushCutPresentationDemo, // ... ];Demo组件在渲染时会用demos.find((d) d.id type)按id查找注册项若找不到会直接抛出no demo错误demos/index.tsx 第 196–199 行。也就是说漏加到数组里不会在编译期报错而是运行时立即抛错这是新增 demo 时最容易踩的坑。第四步在 MDX 页面中引用完成注册后在任意文档 MDX 页面中即可用一行代码嵌入演示Demo typemy-demo /组件会按id解析出对应的DemoType随后完成初始化选项状态 → 渲染Player→ 渲染控件行。查找与失败即抛错的逻辑保证了文档作者写错type时能在开发期立刻发现问题而不是静默渲染空页面。Options 控件体系详解options 是在播放器下方生成交互控件的配置数组。技能文档说明每个 option 必须有name与optional取值no、default-enabled、default-disabled并列出四种类型type: numeric— 滑块配min、max、step、defaulttype: boolean— 复选框配defaulttype: enum— 下拉框配values数组与defaulttype: string— 文本输入配default对照源码 demos/types.ts 第 69–109 行的Option类型定义实际支持的类型比技能文档多了两种且支持条件显示export type Option { name: string; optional: no | default-enabled | default-disabled; showIf?: { option: string; value: string | number | boolean | null; }; } ( | {type: numeric; min: number; default: number; max: number; step: number} | {type: boolean; default: boolean} | {type: enum; default: string; values: string[]} | {type: string; default: string; optional: no} | {type: color; default: string} | { type: uv-coordinate; min: number; default: readonly [number, number]; max: number; step: number; } );相比技能文档源码中额外的能力包括能力说明type: color颜色选择器control.tsx中渲染为input typecolortype: uv-coordinateUV 坐标对渲染为两个联动滑块值形如[number, number]showIf条件显示仅当指定option的当前值等于value时该控件才出现在页面上string强制optional: no文本输入项在类型层面被约束为不可选无启用开关optional 三态语义optional字段决定控件是否带有“启用/停用”复选框其语义在 control.tsx 与 demos/index.tsx 中共同体现no控件恒常启用值始终来自default不渲染额外的启用复选框见control.tsx第 80 行option.optional no ? null : (...)default-enabled控件前出现一个默认勾选的复选框default-disabled控件默认关闭。初始状态初始化时demos/index.tsx 第 206–219 行const initialState useMemo(() { return demo.options .map( (o) [ o.name, o.optional default-disabled ? null : o.default, ] as const, ) .reduce((a, b) { a[b[0]] b[1]; return a; }, {}); }, [demo.options]);即default-disabled的项初始值为null。在Control组件中const enabled value ! null——null即代表该选项被停用。用户勾掉复选框时setValue(null)勾上时setValue(option.default)control.tsx 第 82–88 行。这一设计意味着 demo 组件在接收 props 时应容忍该参数为null通常写作prop{radius ?? defaultRadius}或先判空对应仓库中形状组件普遍采用的“可选参数”模式。控件到值的映射Demo渲染时每个 option 由Control option{...} value{state[name]} setValue{...} /承载demos/index.tsx 第 336–353 行且先经过shouldShowOption按showIf过滤const shouldShowOption ( option: Option, state: Recordstring, unknown, ): boolean { if (!option.showIf) { return true; } return state[option.showIf.option] option.showIf.value; };不同type在 control.tsx 中的具体渲染形态为numeric渲染input typerange并在右侧用code回显当前数值enum渲染selectboolean渲染input typecheckboxstring渲染全宽文本框color渲染input typecoloruv-coordinate渲染两个滑块并显示[u, v]形式的值。选项值如何到达组件inputProps 通道技能文档指出“Option values are passed to the component asinputProps。Access them as regular React props.”——这句话在 demos/index.tsx 第 270–313 行的Player调用中得到完整印证Player key{key} acknowledgeRemotionLicense component{demo.comp} compositionWidth{demo.compWidth} compositionHeight{demo.compHeight} durationInFrames{demo.durationInFrames} fps{demo.fps} style{{ width: 100%, aspectRatio: demo.compWidth / demo.compHeight, }} logLevel{demo.logLevel} errorFallback{/* Restart 按钮点击后重置 state 并递增 key */} inputProps{{...state, darkMode: colorMode dark}} autoPlay{demo.autoPlay} controls{demo.controls} initiallyMuted loop /整条数据链路是options定义 →initialState求初始值 → 用户操作控件更新state→inputProps{{...state, darkMode}}注入 Player → 组件以普通 props 形式收到参数。Player会按fps与durationInFrames驱动逐帧重渲染因此任何参数变化都会即时反映在合成画面上loop与initiallyMuted是文档站统一配置的播放行为。错误兜底与 RestarterrorFallback会渲染错误信息并提供 Restart 按钮点击后触发restart回调把state重置回initialState并递增key强制重建Playerdemos/index.tsx 第 243–246 行。这为组件运行期异常如 shader 编译失败提供了页面内自恢复手段。附加能力形状可拖拽进 Studio从源码结构看Demo还集成了一项技能文档未提及的增强对部分形状类 demo页面底部会出现 “Drag current shape into a layer in the Studio” 拖拽把手demos/index.tsx 第 325–335 行通过makeShapeComponentDragDataFromDemoState把当前 demo 的选项状态打包为拖拽数据用户可直接拖入 Remotion Studio 的图层面板。该能力由shapeDragData是否为null控制新 demo 默认不启用。EffectsDemoschema 驱动的独立注册路径如前所述效果演示不走通用 options 数组而在 effects-demos/registry.ts 中为每个 effect 注册一条EffectsDemoType。该文件顶部定义了一组公共默认值const defaults { compHeight: 720, compWidth: 1280, durationInFrames: 1, fps: 30, autoPlay: false, controls: false, logLevel: info, } as const;每条注册项的关键在于schema直接取自真实 effect 工厂函数的definition.schema例如{ ...defaults, id: effects-brightness, effectName: brightness, effectImportPath: remotion/effects/brightness, comp: EffectsBrightnessPreview, schema: brightness().definition.schema, },这种“引用真实 schema 而非手写 options 数组”的做法保证了文档里的控件范围、默认值与生产 effect 的定义永远一致。注册项还可选地提供initialValues覆盖初始值如effects-blur用initialValues: {radius: 40}或在 schema 之上做局部收紧如shrinkwrapDemoSchema把phase的min/max收窄到-10~10。渲染端 effects-demos/index.tsx 的流程与通用 Demo 高度对称但更自动化effectsDemos.find((d) d.id type)查找注册项找不到抛Effects demo not foundgetInitialValuesFromSchema({schema, initialValues})从 schema 自动推导初始值getActiveSchemaFields依据当前值计算当前激活的字段集合只渲染这些字段的SchemaControl——相当于 schema 层面的showIf控件变更时通过fillSchemaDefaults回填 schema 默认值避免状态缺项每个 effects demo 都带一个拖拽把手onDragStart时调用StudioProtocolInternals.makeDragData({type: effect, name, importPath, config: state})支持把配置好的效果直接拖进 Studio。小结新增一个文档 demo 的完整清单综合技能文档与源码实现为 Remotion 文档新增一个通用交互演示的落地清单是在 packages/docs/components/demos/ 新建MyDemo.tsx组件 props 与options中各项name一一对应必要时接收注入的darkMode在 demos/types.ts 导出DemoType常量补全id、comp、compWidth/compHeight、fps、durationInFrames、autoPlay、controls、logLevel、options在 demos/index.tsx 的demos数组中挂载该常量漏掉会触发运行时no demo抛错在目标 MDX 页面写Demo typemy-demo /若演示对象是remotion/effects中的某个 effect则改走 effects-demos/registry.ts用effect().definition.schema注册EffectsDemoType并在 MDX 中使用EffectsDemo typeeffects-... /。这套“注册表 统一 Player 封装”的架构让文档作者只需关心组件本身与参数声明播放行为、深色模式适配、控件渲染、错误重启和向 Studio 拖拽均由 demos/index.tsx 与 control.tsx 统一承担是当前仓库中形状库、转场、效果等全部文档示例页的共同底座。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考