Element: метод animate()
========================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
Метод **`animate()`** интерфейса `Element` это быстрый способ создания `Animation`, которая применяется к элементу и сразу запускается. Метод возвращает созданный экземпляр `Animation`.

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

Синтаксис
---------


```js
animate(keyframes, options)
```

### Параметры

`keyframes`

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

`options`

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

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

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

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

Указывает окончание диапазона анимации, JavaScript-эквивалент CSS-свойства `animation-range-end` (en-US). `rangeEnd` может принимать разные типы:

* Строка `normal` (означает отсутствие изменений в диапазоне анимации), CSS-представление смещение анимации `<length-percentage>` (en-US), `<timeline-range-name>` или `<timeline-range-name>` с последующим `<length-percentage>`. Например:
```

"normal"
"entry"
"cover 100%"
```

Смотрите `animation-range` (en-US) для подробного описания доступных значений. Также полезно будет ознакомится с материалом View Timeline Ranges Visualizer, где визуально показывается поведение разных значений.
* Объект, содержащий свойства `rangeName` (строка) и `offset` (свойства `CSSNumericValue` (en-US)), представляющие `<timeline-range-name>` и `<length-percentage>`, описанные в предыдущем пункте. Например:

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

* `CSSNumericValue` (en-US), описывающее смещение, например:

```js
CSS.percent("100");
```


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

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

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

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


### Возвращаемое значение

Возвращает `Animation`.

Примеры
-------

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

В этом примере мы используем метод `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


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


#### Result

### «Спускаясь в кроличью нору»

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


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

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

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


```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 |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `Animation`
* `Element.getAnimations()` (en-US)
* `animation-range-end` (en-US), `animation-range-start` (en-US), `animation-timeline` (en-US)
* CSS scroll-driven animations (en-US)
* Web Animations API