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.

Метод animate() интерфейса Element это быстрый способ создания Animation, которая применяется к элементу и сразу запускается. Метод возвращает созданный экземпляр Animation.

Примечание: Элементы могут иметь несколько анимаций. Чтобы получить список анимаций, которые влияют на элемент, можно использовать метод Element.getAnimations().

Синтаксис

animate(keyframes, options)

Параметры

keyframes

Массив объектов кадров или объект кадра, свойства которого являются массивами значений для итерации. Смотрите форматы кадров для получения подробной информации.

options

Целое число, представляющее продолжительность анимации (в миллисекундах) или объект, содержащий одно или более свойств, описанных в параметре options конструктора KeyframeEffect()

id Необязательный

Уникальное для animate() свойство: строка указывающая на анимацию.

rangeEnd Необязательный

Указывает окончание диапазона анимации, JavaScript-эквивалент 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, где визуально показывается поведение разных значений.
Объект, содержащий свойства rangeName (строка) и offset (свойства CSSNumericValue), представляющие <timeline-range-name> и <length-percentage>, описанные в предыдущем пункте. Например:
js
```
{
  rangeName: 'entry',
  offset: CSS.percent('100'),
}
```
CSSNumericValue, описывающее смещение, например:
js
```
CSS.percent("100");
```

rangeStart Необязательный

Указывает начало диапазона анимации, JavaScript-эквивалент CSS-свойства animation-range-start. rangeStart может принимать такие же значения, как rangeEnd.

timeline Необязательный

Уникальное для animate() свойство: AnimationTimeline для связи с анимацией, JavaScript-эквивалент CSS-свойства animation-timeline. По умолчанию равно Document.timeline.

Примеры

Вращение и масштабирование

В этом примере мы используем метод animate() для вращения и масштабирования элемента.

HTML

html

<div class="newspaper">Вращение газеты<br />вызывает головокружение</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);
});

Result

В демо Down the Rabbit Hole (with the Web Animation API), мы используем удобный метод animate() для создания и запуска анимации на элементе #tunnel, чтобы заставить его бесконечно крутиться в падении. Обратите внимание на массив объектов, в котором переданы кадры, а также блок с настройкой продолжительности.

document.getElementById("tunnel").animate(
  [
    // кадры
    { transform: "translateY(0px)" },
    { transform: "translateY(-300px)" },
  ],
  {
    // настройки продолжительности
    duration: 1000,
    iterations: Infinity,
  },
);

Явное указание кадров начала и окончания

В современных версиях браузеров можно указывать состояние только начала или окончания анимации (то есть один кадр), а браузер сам определит недостающую информацию. Например, рассмотрим эту простую анимацию — объект кадра выглядит следующим образом:

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

Мы указали только состояние окончания анимации, а начальное состояние будет определено автоматически.

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

Спецификации

Specification
Web Animations # dom-animatable-animate