Animation：commitStyles() 方法

Baseline 已廣泛支援

此特性已經十分成熟，可在許多裝置和瀏覽器版本上使用。自 2020 年 7 月以來，它已在各大瀏覽器中可用。

Web Animations API 的 Animation 介面的 commitStyles() 方法會將動畫當前樣式的計算值寫入其目標元素的 style 屬性。

它主要用於將動畫最終狀態的樣式寫入目標元素，以便在動畫結束後樣式仍然保留。

語法

commitStyles()

引數

無。

返回值

無（undefined）。

描述

commitStyles() 方法主要用於將動畫最終狀態的計算值寫入目標元素的 style 屬性，以便在動畫結束後樣式仍然保留。這可以在動畫完成後完成（即 Animation 物件的 finished 屬性已解決）。

`commitStyles()` 配合 fill 模式

在舊版瀏覽器中，您必須指定 fill 模式才能在動畫結束後將樣式提交到元素之後。

以下程式碼顯示瞭如何為名為 animatedElement 的元素設定動畫，並設定 fill: "forwards" 以在動畫結束後保留動畫樣式。動畫結束後，我們使用 commitStyles() 將樣式提交到元素。

// Start the animation
const animation = animatedElement.animate(
  { transform: "translate(100px)" },
  { duration: 500, fill: "forwards" },
);

// Wait for the animation to finish
await animation.finished;
// Commit animation state to he animatedElement style attribute
animation.commitStyles();
// Cancel the animation
animation.cancel();

由於 fill 會無限期地保留動畫，一旦我們提交了樣式，就取消動畫。

請注意，僅使用 fill 也可以達到相同的效果，但不建議使用無限期填充動畫。動畫優先於所有靜態樣式，因此無限期填充動畫可以阻止目標元素被正常設定樣式。

注意： 您也可以透過將最終狀態設定為元素的初始樣式，然後將動畫設定為最終樣式來避免顯式儲存最終狀態。

不設定 fill 模式的 `commitStyles()`

在新版瀏覽器中，您無需設定 fill 模式（有關具體版本，請參閱瀏覽器相容性表格）。

注意： 沒有辦法透過功能檢測來檢查這種新行為。目前大多數程式碼應繼續按上一節所示設定 fill。

以下程式碼顯示瞭如何為名為 animatedElement 的元素設定動畫，使用 finished 屬性等待動畫完成，然後使用 commitStyles() 將樣式提交到元素。因為我們沒有設定 fill，所以之後不需要取消動畫。

// Start the animation
const animation = animatedElement.animate(
  { transform: "translate(100px)" },
  { duration: 500 },
);

// Wait for the animation to finish
await animation.finished;

// Commit animation state to the animatedElement style attribute
animation.commitStyles();

即使動畫已被自動刪除，commitStyles() 仍然有效。在元素的樣式提交後，它們可以像平常一樣被修改和替換。

示例

使用 fill 和不使用 fill 的動畫

此示例演示瞭如何使用 commitStyles() 在動畫結束時儲存計算樣式，包括使用 fill 和不使用 fill 的情況。它還提供了兩者都未使用時會發生什麼的示例，以供比較。

示例首先顯示兩個按鈕，分別標有“僅 commitStyles()”和“commitStyles() 配合 fill”。這兩個按鈕在您單擊它們時都會進行動畫，並且都呼叫 commitStyles() 來保留動畫的最終狀態。區別在於，“僅 commitStyles()”未指定 fill: "forwards" 來保留動畫的最終狀態。在不符合當前規範的瀏覽器中，最終狀態可能不會被捕獲。

程式碼隨後顯示一個“不使用 commitStyles() 或 fill”按鈕，可用於比較，以及一個“重置”按鈕。

HTML

html

<button class="commit-styles">commitStyles() only</button>
<button class="commit-with-fill">commitStyles() with fill</button>
<button class="no-commit-or-fill">No commitStyles() or fill</button>

<button id="reset" type="button">Reset</button>

button {
  margin: 0.5rem;
  display: block;
}

const reload = document.querySelector("#reset");

reload.addEventListener("click", () => {
  window.location.reload(true);
});

JavaScript

此程式碼定義了一個“僅 commitStyles()”按鈕的點選處理程式。當點選該按鈕時，它會使按鈕向右或向左移動。請注意，commitStyles() 在動畫結束後立即呼叫。

let offset1 = 0;

const commitStyles = document.querySelector(".commit-styles");

commitStyles.addEventListener("click", async (event) => {
  // Start the animation
  offset1 = 100 - offset1;
  const animation = commitStyles.animate(
    { transform: `translate(${offset1}px)` },
    { duration: 500 },
  );

  // Wait for the animation to finish
  await animation.finished;
  // Commit animation state to style attribute
  animation.commitStyles();
});

此程式碼定義了一個“commitStyles() 配合 fill”按鈕的點選處理程式。當點選該按鈕時，它也會使按鈕向右或向左移動。由於它定義了 fill，因此之後需要取消動畫。

請注意，commitStyles() 在動畫結束後立即呼叫。

const commitStylesWithFill = document.querySelector(".commit-with-fill");
let offset2 = 0;

commitStylesWithFill.addEventListener("click", async (event) => {
  // Start the animation
  offset2 = 100 - offset2;
  const animation = commitStylesWithFill.animate(
    { transform: `translate(${offset2}px)` },
    { duration: 500, fill: "forwards" },
  );

  // Wait for the animation to finish
  await animation.finished;
  // Commit animation state to style attribute
  animation.commitStyles();
  // Cancel the animation
  animation.cancel();
});

此程式碼定義了一個“不使用 commitStyles() 或 fill”按鈕的點選處理程式。當點選該按鈕時，它也會使按鈕向右或向左移動。它沒有定義 fill，我們也不會取消動畫。

const noCommitStylesOrFill = document.querySelector(".no-commit-or-fill");
let offset3 = 0;

noCommitStylesOrFill.addEventListener("click", async (event) => {
  // Start the animation
  offset3 = 100 - offset3;
  const animation = noCommitStylesOrFill.animate(
    { transform: `translate(${offset3}px)` },
    { duration: 500 },
  );
});

結果

單擊按鈕進行動畫。請注意，如果當前瀏覽器仍然需要 fill 才能在動畫結束後提交樣式，則第一個按鈕在動畫結束時會“跳躍”。“不使用 commitStyles() 或 fill”按鈕在動畫結束時總是會跳躍，因為最終狀態未儲存。

規範

規範
Web 動畫 # dom-animation-commitstyles

瀏覽器相容性

另見

Web Animations API
用於控制網頁動畫的其他方法和屬性的 Animation。

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 ⁨2025年8月11日⁩，由 MDN 貢獻者進行修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題