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 上查看此页面 • 报告此内容的问题