Props 解析流程

四層 Props 解析

Remotion 的 Props 系統有四個層級，每一層都可以覆蓋上一層的值：

第 1 層：Default Props（Composition 定義中的預設值）
    ↓ 被覆蓋
第 2 層：Input Props（CLI / Studio / API 傳入）
    ↓ 被覆蓋
第 3 層：calculateMetadata（動態計算，可修改 Props）
    ↓
第 4 層：最終 Props（元件實際收到的值）

範例

// 第 1 層：Default Props
<Composition
  defaultProps={{
    title: "預設標題",
    color: "#ffffff",
    items: [],
  }}
  calculateMetadata={calculateMetadata}
/>

# 第 2 層：CLI 傳入（覆蓋 title）
npx remotion render MyVideo out.mp4 --props='{"title": "CLI 標題"}'

// 第 3 層：calculateMetadata（注入 items）
const calculateMetadata = async ({ props }) => {
  const data = await fetch("https://api.example.com/items");
  const items = await data.json();
  return {
    props: { ...props, items },
    durationInFrames: items.length * 90,
  };
};

// 第 4 層：元件收到的最終 Props
// title: "CLI 標題"（第 2 層覆蓋了第 1 層）
// color: "#ffffff"（保留第 1 層的值）
// items: [...]（第 3 層注入）

視覺化流程

Default Props        Input Props         calculateMetadata
{                    {                   {
  title: "預設",       title: "CLI",       items: [...],
  color: "#fff",                          durationInFrames: 270,
  items: [],                            }
}                    }

合併結果（最終 Props）：
{
  title: "CLI",      ← 被 Input Props 覆蓋
  color: "#fff",     ← 保留 Default Props
  items: [...],      ← 被 calculateMetadata 注入
}

Studio 中的行為

在 Studio 中修改 Props 時，修改的值等同於 Input Props（第 2 層）。流程是：

1. 使用者在 Studio 修改一個值
2. 該值覆蓋 Default Props
3. calculateMetadata 被重新呼叫
4. 預覽更新

如果 calculateMetadata 是 async 的，Studio 會顯示載入指示器。

常見模式

模式一：純靜態 Props

不需要 calculateMetadata，直接用 Default Props + Input Props：

<Composition
  defaultProps={{ title: "Hello", color: "#fff" }}
  // 沒有 calculateMetadata
/>

模式二：動態長度

Props 決定影片長度：

calculateMetadata = ({ props }) => ({
  durationInFrames: props.items.length * 90,
});

模式三：資料注入

在渲染前從 API 取得資料並注入 Props：

calculateMetadata = async ({ props }) => {
  const data = await fetch(props.apiUrl).then((r) => r.json());
  return { props: { ...props, data } };
};

小結

• Props 有四層解析：Default → Input → calculateMetadata → 最終值
• 每一層只覆蓋有指定的欄位
• calculateMetadata 可以同時修改 Props 和影片規格
• Studio 中的修改等同於 Input Props