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 上檢視此頁面 • 報告此內容的問題