Element: animate() メソッド

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2020.

* Some parts of this feature may have varying levels of support.

Element インターフェイスの animate() メソッドは、新しい Animation を生成し、この要素へ適用し、そしてアニメーションの再生を行うショートカットメソッドです。生成した Animation オブジェクトのインスタンスを返します。

メモ: 要素には複数のアニメーションを適用することができます。Element.getAnimations() を呼び出すと、要素に作用するアニメーションのリストを取得することができます。

構文

js
animate(keyframes, options)

引数

keyframes

キーフレームオブジェクトの配列、またはプロパティが反復処理可能な値の配列である単一のキーフレームオブジェクトのどちらかです。詳しくは Keyframe の書式を参照してください。

options

アニメーションの再生時間を表す整数値（ミリ秒単位）、または KeyframeEffect() のオプションの引数や以下のオプションで記述された 1 つ以上のタイミングプロパティを含むオブジェクトのどちらかです。

id 省略可

animate() の固有のプロパティです。このアニメーションを参照する文字列です。

rangeEnd 省略可

タイムラインに沿ったアニメーションの適用範囲の終わり、つまりタイムラインのどこでアニメーションが終わるかを指定します。CSS の animation-range-end プロパティに相当します。rangeEnd は以下のように、様々な値を取ることができます。

  • 文字列で、normal（アニメーションの範囲に変更がないことを意味します）、オフセットを表す CSS の <length-percentage>、<timeline-range-name>、<timeline-range-name> のいずれかと、それに続く <length-percentage> です。例えば次のようになります。

    "normal"
"entry"
"cover 100%"

    利用できる値の詳細については animation-range を参照してください。また、View Timeline Ranges Visualizer も調べてみてください。様々な値が意味していることを、視覚的な形式で簡単に示すことができます。

  • 前の箇所で記述されている <timeline-range-name> と <length-percentage> を表す rangeName（文字列）と offset (CSSNumericValue) プロパティを格納したオブジェクト。例えば、次のようなものです。

    js
    {
  rangeName: 'entry',
  offset: CSS.percent('100'),
}

  • CSSNumericValue で、オフセットを表すもの。例えば、次のようなものです。

    js
    CSS.percent("100");
rangeStart 省略可

タイムラインに沿ったアニメーションの適用範囲、つまりタイムラインのどこからアニメーションが始まるかを指定します。CSS の animation-range-start プロパティに相当します。rangeStart は rangeEnd と同じ種類の値を取ります。

timeline 省略可

animate() に固有のプロパティです。アニメーションに関連付けるAnimationTimeline です。既定値は Document.timeline です。CSS の animation-timeline プロパティに相当します。

返値

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

js
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);
});

結果

ウサギの穴を下るデモ

Down the Rabbit Hole (with the Web Animation API) のデモでは、上に向かって永遠に流れ続けるアニメーションが #tunnel 要素に施されています。ここでは、アニメーションを素早く作成して再生できる animate() メソッドが用いられています。キーフレームとして渡されているオブジェクト配列と、タイミングオプションとして渡されているオブジェクトに注目してください。

js
document.getElementById("tunnel").animate(
  [
    // キーフレーム
    { transform: "translateY(0px)" },
    { transform: "translateY(-300px)" },
  ],
  {
    // タイミングオプション
    duration: 1000,
    iterations: Infinity,
  },
);

暗黙の開始/終了キーフレーム

新しいバージョンのブラウザーでは、アニメーションの開始または終了状態のみ（つまり、単一のキーフレーム）で設定することができ、可能であればブラウザーがアニメーションのもう一方を推測します。例えば、この簡単なアニメーション を考えてみましょう。 Keyframe オブジェクトは次のようなものです。

js
let rotate360 = [{ transform: "rotate(360deg)" }];

アニメーションの終了状態を指定しただけで、開始状態は暗黙になっています。

timeline, rangeStart, rangeEnd

timeline, rangeStart, rangeEnd の各プロパティの典型的な使用例は次の通りです。

js
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%",
  },
);

仕様書

Specification
Web Animations
# dom-animatable-animate

ブラウザーの互換性

関連情報