Element：animate() 方法

Baseline 广泛可用 *

此功能已经成熟，并可在许多设备和浏览器版本上使用。自 ⁨2020 年 3 月⁩起，它已在各浏览器中推出。

* 此特性的某些部分可能存在不同级别的支持。

Element 接口的 animate() 方法是一个快捷方法，它会创建一个新的 Animation 对象，将其应用到该元素，然后播放动画。它会返回创建的 Animation 对象实例。

注意： 元素可以应用多个动画。你可以通过调用 Element.getAnimations() 来获取影响某个元素的动画列表。

语法

animate(keyframes, options)

参数

关键帧

可以是一个关键帧对象数组，或者一个属性是值数组的关键帧对象。有关更多详细信息，请参阅关键帧格式。

options

可以是表示动画持续时间（以毫秒为单位）的整数，或者一个包含一个或多个在 KeyframeEffect() options 参数和/或以下选项中描述的计时属性的对象。

id 可选

animate() 方法的独特属性：用于引用动画的字符串。

rangeEnd 可选

指定动画在其时间轴上的附加范围的结束位置，即动画将在时间轴上的哪个位置结束。这是 CSS animation-range-end 属性的 JavaScript 等效项。rangeEnd 可以接受以下几种不同的值类型：

可以是字符串 normal（表示动画的附加范围不改变），CSS <length-percentage>（表示偏移量），<timeline-range-name>，或者后面跟着 <length-percentage> 的 <timeline-range-name>。例如："normal"、"entry" 或 "cover 100%"。

有关可用值的详细描述，请参阅 animation-range。还可以查看 View Timeline Ranges Visualizer，它以易于理解的视觉格式准确地显示了不同值的含义。
一个包含 rangeName（字符串）和 offset（CSSNumericValue）属性的对象，分别表示前面项目符号中描述的 <timeline-range-name> 和 <length-percentage>。例如：{ rangeName: "entry", offset: CSS.percent("100") }。
一个表示偏移量的 CSSNumericValue，例如：CSS.percent("100")。

rangeStart 可选

指定动画在其时间轴上的附加范围的开始位置，即动画将在时间轴上的哪个位置开始。这是 CSS animation-range-start 属性的 JavaScript 等效项。rangeStart 可以接受与 rangeEnd 相同的值类型。

timeline 可选

animate() 方法的独特属性：要与动画关联的 AnimationTimeline。默认为 Document.timeline。这是 CSS animation-timeline 属性的 JavaScript 等效项。

返回值

返回一个 Animation 对象。

示例

旋转和缩放

在此示例中，我们使用 animate() 方法来旋转和缩放一个元素。

HTML

html

<div class="newspaper">Spinning newspaper<br />causes dizziness</div>

CSS

css

html,
body {
  height: 100%;
}

body {
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: black;
}

.newspaper {
  padding: 0.5rem;
  text-transform: uppercase;
  text-align: center;
  background-color: white;
  cursor: pointer;
}

JavaScript

const newspaperSpinning = [
  { transform: "rotate(0) scale(1)" },
  { transform: "rotate(360deg) scale(0)" },
];

const newspaperTiming = {
  duration: 2000,
  iterations: 1,
};

const newspaper = document.querySelector(".newspaper");

newspaper.addEventListener("click", () => {
  newspaper.animate(newspaperSpinning, newspaperTiming);
});

结果

“爱丽丝梦游仙境”演示

在 “爱丽丝梦游仙境”（使用 Web Animation API）演示中，我们使用便捷的 animate() 方法立即创建并播放 #tunnel 元素的动画，使其向上无限流动。请注意作为关键帧传递的对象数组以及计时选项块。

document.getElementById("tunnel").animate(
  [
    // keyframes
    { transform: "translateY(0px)" },
    { transform: "translateY(-300px)" },
  ],
  {
    // timing options
    duration: 1000,
    iterations: Infinity,
  },
);

隐含的 to/from 关键帧

浏览器可以使用当前状态来推断动画的开始或结束状态。默认情况下，如果只提供一个关键帧，它将被视为结束状态，而开始状态将从元素的当前计算样式中推断出来。但是，您可以通过指定 offset 来指示提供的关键帧应放置在动画时间轴上的哪个位置。

<div>
  <img
    id="logo"
    src="/shared-assets/images/examples/firefox-logo.svg"
    alt="Firefox logo" />
</div>
<button id="run">Animate - use current as start</button>
<button id="run2">Animate - use current as end</button>
<button id="run3">Animate - use current as both ends</button>

div {
  width: 100%;
}

#logo {
  width: 200px;
  height: 200px;
}

const logo = document.getElementById("logo");
document.getElementById("run").addEventListener("click", () => {
  logo.animate({ transform: "translateX(300px)" }, 1000);
});
document.getElementById("run2").addEventListener("click", () => {
  logo.animate({ transform: "translateX(300px)", offset: 0 }, 1000);
});
document.getElementById("run3").addEventListener("click", () => {
  logo.animate({ transform: "translateX(300px)", offset: 0.5 }, 1000);
});

我们在时间轴上指定了一个关键帧，开始和/或结束状态可以被填充以创建完整的动画。

timeline、rangeStart 和 rangeEnd

timeline、rangeStart 和 rangeEnd 属性的典型用法可能如下所示：

const img = document.querySelector("img");

const timeline = new ViewTimeline({
  subject: img,
  axis: "block",
});

img.animate(
  {
    opacity: [0, 1],
    transform: ["scaleX(0)", "scaleX(1)"],
  },
  {
    fill: "both",
    duration: 1,
    timeline,
    rangeStart: "cover 0%",
    rangeEnd: "cover 100%",
  },
);

规范

规范
Web 动画 # dom-animatable-animate

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

此页面最后修改于 ⁨2025 年 9 月 25 日⁩，作者是 MDN 贡献者。

在 GitHub 上查看此页面 • 报告此内容的问题