remotion-interactivity

透過以特定方式撰寫 Remotion 標記，Remotion Studio 能夠辨識程式碼的結構並使其具備互動功能：

• 允許點擊選取項目
• 允許拖放、調整大小和旋轉
• 編輯 CSS 樣式
• 讓關鍵影格和緩動函數值可編輯

如果標記過於複雜，Studio 無法使其互動，則這些值將變為灰色。

優先使用具有獨立時間軸的互動元件

對於填滿其父容器的元件，請使用 Interactive.withSchema({wrapInSequence: true, layout: 'absolute-fill'})。包裝器提供其視覺根節點和時間軸項目，並預設裁剪溢出內容，因此內部元件可以傳回 fragment。將時間設定、預先載入、尺寸和每個實例的樣式放在匯出的元件上。

將屬於一起的視覺元素保持在同一元件中，以便它們一起移動和裁切。內部佈局容器仍可提供對齊、在較小區域內裁剪或動畫群組；只填滿場景的容器通常是不必要的。卡片、文字框和具有自身邊界的 SVG 可以使用預設的 layout: 'none'，並將 style 轉發給其視覺根節點。

import {Video} from '@remotion/media';
import type React from 'react';
import {Interactive, useVideoConfig, type InteractivitySchema} from 'remotion';

type SceneProps = {
  readonly title: string;
};

const SceneInner: React.FC<SceneProps> = ({title}) => {
  const {fps} = useVideoConfig();

  return (
    <>
      <Video
        name="Background footage"
        src="https://remotion.media/video.mp4"
        premountFor={fps}
        objectFit="cover"
        style={{width: '100%', height: '100%'}}
      />
      <Interactive.Div
        name="Scene title"
        style={{
          position: 'absolute',
          left: 80,
          bottom: 80,
          color: 'white',
          fontFamily: 'Helvetica, Arial, sans-serif',
          fontSize: 80,
        }}
      >
        {title}
      </Interactive.Div>
    </>
  );
};

const sceneSchema = {
  title: {type: 'string', default: '', description: '標題'},
} as const satisfies InteractivitySchema;

export const Scene = Interactive.withSchema({
  Component: SceneInner,
  componentName: 'Scene',
  schema: sceneSchema,
  wrapInSequence: true,
  layout: 'absolute-fill',
});

選擇 Schema 欄位

Schema 中的每個鍵都是一個 prop，Studio 可以在呼叫處讀取和編輯。 不在 schema 中的 props 仍然可以運作，但無法在 Studio 中編輯。 鍵可以使用點表示法，例如 style.color。

類型	用途	可設定關鍵影格
string	字串，例如標題、提示或程式碼片段	否
number	數字，可選 min、max、step、integer	是
boolean	開/關切換	是 (長按)
color	CSS 顏色字串	是
enum	在 variants 之間選擇，每個都有自己的巢狀 schema	可選 (長按)
array	數字、顏色、列舉等清單	否
asset	媒體來源，可選 assetType	否
font-family	CSS 字型系列	否
font-weight	字型粗細	是
translate、scale、rotation-css、rotation-degrees、transform-origin	變換	是
uv-coordinate	元素上標準化的 [x, y] 點	是
svg-path	SVG 路徑資料	是
remotion-captions	Caption[] 資料	否
hidden	保持在控制項之外的值	—

每個欄位都需要 default，並且應該有 description，Studio 會將其顯示為標籤。 設定 keyframable: false 以顯示靜態控制項。

公開內容和每個實例的外觀，例如文字和強調色。\n不要為 style.translate、style.scale、style.rotate、style.transformOrigin 和 style.opacity 新增欄位：wrapInSequence: true 已經新增了它們。

若要讓根節點的 CSS 屬性可依實例編輯，請展開內建的 schema 片段：

const cardSchema = {
  ...Interactive.textSchema, // style.color, style.fontSize, style.fontWeight, ...
  ...Interactive.backgroundSchema, // style.backgroundColor
  ...Interactive.borderRadiusSchema, // style.borderRadius, ...
} as const satisfies InteractivitySchema;

也可用：Interactive.borderSchema，以及用於接受字幕的元件的 Interactive.captionsSchema。 對於接受 React.ReactNode children 的元件，請新增 ...Interactive.childrenSchema。 它提供對子內容的控制，並可能隨著時間演進以支援更豐富的內容。 目前，它使用一個標籤為「文字」的字串欄位，預設值為 ''。 如果元件需要僅字串的子元素，請改為宣告一個明確的 children 欄位，其 type: 'string'。 Interactive.textSchema 控制排版樣式；childrenSchema 控制內容。 children 片段不包含在 baseSchema 中，也不會自動新增到自訂元件。 巢狀標記和計算後的子元素目前是唯讀的。 text-content 是 string 欄位類型的已棄用別名。 請參閱 InteractivitySchema 以了解所有選項。

將可重複使用的元件註冊為已連接的組合

將重要的場景和可重複使用的元件（具有自己的圖層或動畫）註冊為獨立組合。Studio 將這些稱為已連接的組合：它們可以在自己的時間軸中開啟，同時與父影片共用相同的元件實作。

在元件內部定義所需的樣式和載入字型，使其無需父容器即可運作。請參閱父容器獨立性。

註冊與父容器渲染相同的匯出元件參考。對於上面的範例，請使用 component={Scene}，而不是 SceneInner 或內聯包裝器。使用 wrapInSequence: true，則不需要額外的 <Sequence> 來連接。

import {Composition} from 'remotion';
import {Scene} from './Scene';

export const RemotionRoot = () => (
  <Composition
    id="Scene"
    component={Scene}
    width={1280}
    height={720}
    fps={30}
    durationInFrames={30}
    defaultProps={{
      title: '一個新的視角',
    }}
  />
);

選擇一個唯一的 ID、具有代表性的內聯預設值，以及適合預覽元件的尺寸、fps 和持續時間。註冊預設值不會自動從父實例複製 props。請參閱已連接的組合以了解註冊和提取詳細資訊。

將時間設定直接放在元件上

避免在一個已經接受時間 props 的元件周圍使用單獨的 <Sequence>。使用 wrapInSequence: true 建立的內建互動元件和自訂元件可以直接接收 name、from、durationInFrames、trimBefore、playbackRate 和 premountFor。

<Scene
  name="開場場景"
  from={30}
  durationInFrames={90}
  premountFor={fps}
  style={{opacity: 0.9}}
  title="一個新的視角"
/>

當移除一個冗餘的序列時，請將其時間設定和名稱移至子元件。保留任何現有的子元件時間設定；不要覆蓋或雙重套用偏移。元件內部的 useCurrentFrame() 呼叫會讀取其本地影格，而呼叫處的樣式表達式仍會使用呼叫者的影格。在移動動畫樣式時，請保留此區別。

當 <Sequence> 為多個兄弟元素提供共用時間設定、包裝一個不處理時間設定的元件，或提供子元件無法直接接受的尺寸時，請保留它。受管理的根節點也可以接受 width 和 height 給 useVideoConfig()。對於連續的佈局（無論是否有轉場），請保留 <TransitionSeries.Sequence>；直接的 from props 無法取代這些行為。

為每個可獨立編輯的項目賦予其自己的 JSX 節點

Studio 會編輯建立項目的 JSX 來源節點。如果多個執行期項目來自同一個 JSX 節點，則它們共用一個來源編輯目標。

對於每個應可獨立編輯的組合註冊、剪輯、場景、圖層或序列，請撰寫一個單獨的 JSX 節點，並將其可編輯的 props 保留在該節點上。這適用於 <Composition>、<Still>、內建媒體元件、<Sequence>、<TransitionSeries.Sequence> 和自訂元件。

例如，像這樣建立一個可編輯的時間軸：

import { TransitionSeries } from "@remotion/transitions";

<TransitionSeries>
  <TransitionSeries.Sequence name="簡介" durationInFrames={90}>
    <Introduction />
  </TransitionSeries.Sequence>
  <TransitionSeries.Sequence name="示範" durationInFrames={150}>
    <Demo />
  </TransitionSeries.Sequence>
</TransitionSeries>

.map() 或其他程式化迴圈會從一個 JSX 來源節點建立多個執行期項目。這適用於有意識地作為單一範本控制的重複輸出，例如視覺化長條圖或粒子。但是，當實例需要獨立的 ID 或名稱、props、元資料、時間設定、排序、在 Studio 中刪除或複製時，這就不合適了。

使用 Interactive 讓 HTML 元素具有互動性

每個 HTML 和 SVG 元素（<Img> 除外，它已經是互動的）都可以使用 Interactive 變成互動式：

<Interactive.Div
  name="問候卡片"
  style={{fontSize: 80, padding: 24}}
>
  哈囉
</Interactive.Div>

這允許在 Studio 中設定樣式和關鍵影格。請合理使用，如果一個元件有許多元素，時間軸可能會變得雜亂。

優先使用內聯文字

如果文字是固定的且只使用一次，請直接將其寫入互動元素內部，而不是將其提取到常數中。

// 👍 固定副本保持可編輯
<Interactive.Div name="標題">
  Remotion 最佳實踐
</Interactive.Div>

只有在文字是動態的或重複使用時，才使用 prop 或變數。

為互動元素賦予描述性名稱

為元素新增 name prop，使其易於識別。 避免使用計算出的名稱，請將其硬編碼。

<>
  <Interactive.Div name="主角標題" style={{fontSize: 80}}>
    發布日
  </Interactive.Div>
  <Img name="頭像" src="https://remotion.media/image.jpeg" />
  <Video name="背景" src="https://remotion.media/video.mp4" />
  <Interactive.Div name="標題">
    發布日
  </Interactive.Div>
</>

保持所有 CSS 樣式內聯

最好的方法是直接將一個純物件傳遞給 style——不要引用常數、不要展開物件、不要做數學運算。

<Interactive.Div
  style={{
    fontSize: 80,
    color: 'red',
  }}
>
  Hello World!
</Interactive.Div>

const baseStyle = useMemo(() => {
  return {
    fontSize: 12 // ❌ 非內聯樣式不受支援
  }
}, []);

<Interactive.Div
  style={{
    ...baseStyle, // ❌ 展開不受支援
    color: RED, // ❌ 引用常數不受支援
    scale: frame * 10 // ❌ 數學運算不受支援
  }}
>
  Hello World!
</Interactive.Div>

使用 interpolate() 製作動畫

將動畫撰寫為對變化的屬性進行內聯 interpolate() 呼叫。 輸出範圍、緩動函數、外推法和 output 屬性應使用硬編碼值。

輸入範圍可以額外使用直接從 useVideoConfig() 解構的 durationInFrames、fps、width 和 height。支援裸識別碼，例如 durationInFrames、與數字相乘，例如 2 * fps 或 fps * 2，以及減去數字，例如 durationInFrames - 1。

const {fps, durationInFrames} = useVideoConfig();

// 👍 內聯值可以被標準化和設定關鍵影格
<Interactive.Div
  name="產品卡片"
  style={{
    color: 'white',
    fontSize: 80,
    scale: interpolate(frame, [0, fps], [0, 1], {
      easing: Easing.spring({damping: 200}),
      output: 'perceptual-scale',
      extrapolateLeft: 'clamp',
      extrapolateRight: 'clamp'
    }),
    rotate: interpolate(frame, [0, 1 * fps], ['0deg', '20deg'], {
      easing: Easing.spring({damping: 200}),
      extrapolateLeft: 'clamp',
      extrapolateRight: 'clamp'
    }),
    translate: interpolate(
      frame,
      [durationInFrames - 30, durationInFrames],
      ['0px 0px', '0px 120px'],
      {
        easing: Easing.spring({damping: 200}),
        extrapolateLeft: 'clamp',
        extrapolateRight: 'clamp'
      }
    ),
  }}
>
  主打產品
</Interactive.Div>

支援的輸出值：

• output: 'perceptual-scale' 用於縮放，可產生更自然的視覺效果。
• output: 'translate-x' 和 output: 'translate-y' 用於平移。
• 對於旋轉，請使用 rotate 屬性而不是 transform: rotate()。

避免在互動元素上使用 CSS transform 屬性；它會與互動式變換設定衝突。

讓互動式時間軸與 SVG 配合良好

對於 SVG，請使用 <Interactive.Svg> 或 Interactive.withSchema({layout: 'none'})。預設的 SVG 佈局是 none。對於 <SVG> 和圖示，layout: 'absolute-fill' 通常是不必要的。

對於複雜的 SVG，請為每個需要獨立時間軸控制的元素使用單獨的 <Interactive.Svg> 元素。

管理 SVG 變換

• 將 SVG transform 屬性與 origin 屬性（從 0 0 開始）一起使用，以獲得更好的 Studio 支援。
• 使用 transform-box: 'fill-box' 使變換相對於元素本身的邊界框。
• 對於旋轉，SVG 使用 degrees，而 CSS 使用 deg。
• 當使用 Interactive.Svg 時，Remotion 會將 CSS transform 對應到 SVG transform 屬性。