<Sequence> 元件

什麼是 <Sequence>？

<Sequence> 讓你能夠對元件或動畫的某個部分進行時間位移。透過 Sequence，你可以控制子元件從哪一幀開始出現、顯示多少幀，以及進行嵌套排列來建構複雜的時間軸。

基本範例

// MyTrailer.tsx
const MyTrailer = () => {
  return (
    <>
      <Sequence durationInFrames={30}>
        <Intro />
      </Sequence>
      <Sequence from={30} durationInFrames={30}>
        <Clip />
      </Sequence>
      <Sequence from={60}>
        <Outro />
      </Sequence>
    </>
  );
};

• <Intro> 從第 0 幀顯示到第 29 幀。
• <Clip> 從第 30 幀顯示到第 59 幀。
• <Outro> 從第 60 幀顯示到 Composition 結束。

時間位移對 useCurrentFrame() 的影響

<Sequence> 的所有子元件在呼叫 useCurrentFrame() 時，會接收到已被 from 偏移的值。

// MyTrailer.tsx
import { Sequence, useCurrentFrame } from "remotion";
 
const Intro = () => <div>{useCurrentFrame()}</div>;
 
const MyTrailer = () => {
  return (
    <>
      <Intro />
      <Sequence from={30}>
        <Intro />
      </Sequence>
    </>
  );
};

• 在第 0 幀時，會渲染 <div>0</div>。
• 在第 30 幀時，會同時渲染 <div>30</div> 和 <div>0</div>。

位於 <Sequence from={30}> 內部的 <Intro> 元件，其內部的 useCurrentFrame() 回傳的是相對於 Sequence 起始點的幀數，而非整個 Composition 的絕對幀數。

用 durationInFrames 控制顯示時長

透過 durationInFrames prop，你可以定義子元件應該被掛載多少幀。一旦超出時間範圍，子元件就會被卸載（unmount）。

// trim-end.tsx
const ClipExample: React.FC = () => {
  return (
    <Sequence durationInFrames={45}>
      <BlueSquare />
    </Sequence>
  );
};

版面配置

預設情況下，<Sequence> 的子元件會被包裝在一個 <AbsoluteFill> 元件中，讓內容自動填滿整個畫面。如果你不想要這個行為，可以加上 layout="none" prop：

<Sequence layout="none">
  <MyComponent />
</Sequence>

嵌套 Sequence（Cascading）

Sequence 可以互相嵌套，時間會累加（cascading）。例如，一個從第 60 幀開始的 Sequence，放在一個從第 30 幀開始的 Sequence 內部，其子元件會從第 90 幀開始出現。

延伸範例

以下所有範例都以一個藍色方塊動畫為基礎：

// MyVideo.tsx
const MyVideo = () => {
  return <BlueSquare />;
};

延遲出現（Delay）

將內容包在 <Sequence from={30}> 中，讓它延遲 30 幀出現：

// delay.tsx
const MyVideo = () => {
  return (
    <Sequence from={30}>
      <BlueSquare />
    </Sequence>
  );
};

裁剪結尾（Trim End）

用有限的 durationInFrames 讓元件在指定時間後卸載：

// trim-end.tsx
const ClipExample: React.FC = () => {
  return (
    <Sequence durationInFrames={45}>
      <BlueSquare />
    </Sequence>
  );
};

裁剪開頭（Trim Start）

傳入負的 from 值可以裁剪內容的開頭。時間向後移，動畫在內容出現時就已經播放了 15 幀：

// trim-start.tsx
const TrimStartExample: React.FC = () => {
  return (
    <Sequence from={-15}>
      <BlueSquare />
    </Sequence>
  );
};

同時延遲與裁剪（Trim and Delay）

用兩個 <Sequence> 嵌套來同時裁剪開頭並延遲出現。內層傳入 from={-15} 裁掉前 15 幀，外層傳入 from={30} 再向前位移 30 幀：

// trim-and-delay.tsx
const TrimAndDelayExample: React.FC = () => {
  return (
    <Sequence from={30}>
      <Sequence from={-15}>
        <BlueSquare />
      </Sequence>
    </Sequence>
  );
};

序列播放

若要讓多個片段依序播放，請使用 <Series /> 輔助元件，它能自動計算每個片段的起始幀，避免手動計算 from 值。

Props 說明

from?

（從 v3.2.36 起為可選，先前版本為必填）

子元件「認為影片從幾幀開始」的起始幀。當 Sequence 處於 from 幀時，其子元件認為自己在第 0 幀。從 v3.2.36 起，此 prop 預設為 0。

durationInFrames?

Sequence 應該顯示多少幀。若子元件不在顯示時間範圍內，它們將被卸載。預設值為 Infinity，表示 Sequence 不限制顯示時長。

height? v4.0.80

為 Sequence 指定特定的高度（style={{height: height}}），並覆蓋子元件中 useVideoConfig() 返回的 height 值。適用於包含為特定高度設計的元件。

width? v4.0.80

為 Sequence 指定特定的寬度（style={{width: width}}），並覆蓋子元件中 useVideoConfig() 返回的 width 值。

name?

為 Sequence 命名，它將在 Remotion Studio 的時間軸中顯示為標籤。此屬性純粹用於幫助你在時間軸中追蹤各個 Sequence。

layout?

"absolute-fill"（預設）或 "none"。預設情況下，Sequence 會絕對定位，讓它們互相疊加。若你想自行處理版面配置，傳入 layout="none"。（從 v1.4 起可用）

style? v3.0.27

套用到容器的 CSS 樣式。若 layout 設為 none，則沒有容器，設定此樣式是不允許的。

className? v3.3.45

套用到容器的 CSS class 名稱。若 layout 設為 none，則沒有容器，設定此屬性是不允許的。

premountFor? v4.0.140

預先掛載 Sequence 指定幀數。從 v5.0 起，預設值從 0 改為 fps（1 秒）。

postmountFor? v4.0.340

與 premountFor 相同，但作用於 Sequence 結束之後。只有當你預期使用者會頻繁在時間軸上向後 seek，並想避免閃爍時才使用此選項。

styleWhilePremounted? v4.0.252

在 Sequence 預掛載時套用到容器的 CSS 樣式。一般的 style 仍然會套用，但 styleWhilePremounted 可以覆蓋其中的屬性。

showInTimeline? v4.0.110

若設為 false，該軌道將不會在 Studio 的時間軸中顯示。子 <Sequence> 預設仍然會顯示，除非它們也設定了 showInTimeline={false}。

加入 React Ref

從 v3.2.13 起，你可以為 <Sequence> 加入 React ref。若使用 TypeScript，需要以 HTMLDivElement 來指定型別：

const MyComp = () => {
  const ref = useRef<HTMLDivElement>(null);
  return (
    <Sequence from={10} ref={ref}>
      {content}
    </Sequence>
  );
};

在 @remotion/three 中的注意事項

<Sequence> 預設會回傳一個 <div> 元件，但這在 <ThreeCanvas> 內部是不被允許的。請加上 layout="none" 來避免錯誤：

<Sequence layout="none">
  {/* ThreeJS 內容 */}
</Sequence>

相容性

相關資源

• 使用 Sequence 重用元件
• <Composition /> 元件
• <Series /> 元件