CSS-свойство `animation-timeline`

Свойство animation-timeline CSS задаёт временную шкалу, используемую для управления ходом CSS-анимации.

Синтаксис

/* Keyword */
animation-timeline: none;
animation-timeline: auto;

/* Named timeline */
animation-timeline: --timeline_name;

/* Anonymous scroll progress timeline */
animation-timeline: scroll();
animation-timeline: scroll(x root);

/* Anonymous view progress timeline */
animation-timeline: view();
animation-timeline: view(inline);
animation-timeline: view(x 200px auto);

/* Multiple values */
animation-timeline: --progress-bar-timeline, --carousel-timeline;
animation-timeline: auto, view(20% 80%), none, scroll(inline nearest);

/* Global values */
animation-timeline: inherit;
animation-timeline: initial;
animation-timeline: revert;
animation-timeline: revert-layer;
animation-timeline: unset;

Значения

Свойство animation-timeline задаётся одним или несколькими значениями, разделёнными запятыми. Каждое из них может быть одним из следующих:

none

Анимация не связана с временной шкалой и не выполняется.

auto

Временная шкала анимации — стандартная DocumentTimeline документа. Это значение по умолчанию.

scroll()

Задаёт корневой элемент, ближайший прокручиваемый контейнер или сам элемент в качестве анонимной временной шкалы прогресса прокрутки и, при необходимости, направление прокрутки контейнера.

view()

Задаёт ближайший родительский контейнер прокрутки в качестве анонимной временной шкалы прогресса просмотра, при необходимости переопределяя направление оси baseline по умолчанию, а также начальные и конечные отступы auto.

<dashed-ident>

Имя временной шкалы прокрутки или прогресса просмотра, определённое свойством scroll-timeline-name или view-timeline-name контейнера прокрутки (либо сокращённым свойством scroll-timeline или view-timeline).

Описание

Стандартная временная шкала анимации CSS-кадров — основанная на времени DocumentTimeline. Свойство animation-timeline можно использовать для задания именованной или анонимной временной шкалы прогресса прокрутки либо прогресса просмотра. Также его можно использовать, чтобы явно задать стандартную временную шкалу документа, основанную на времени, для управления ходом анимации элемента, либо указать отсутствие временной шкалы. В последнем случае элемент не будет анимироваться.

С помощью свойства animation-timeline можно задать следующие типы временных шкал:

DocumentTimeline

Стандартная временная шкала документа, ход которой определяется временем, прошедшим с момента первой загрузки документа в браузере. Эта временная шкала традиционно используется для CSS-анимаций. Она выбирается значением auto или если значение animation-timeline не указано, поскольку это значение используется по умолчанию.

Временная шкала прогресса прокрутки

Ход анимации определяется прокруткой прокручиваемого элемента, или контейнера прокрутки, по горизонтали или вертикали. Элемент, задающий временную шкалу прогресса прокрутки, можно указать двумя способами:

Именованная временная шкала прогресса прокрутки

Контейнер прокрутки получает явное имя: свойству scroll-timeline-name (или сокращённому свойству scroll-timeline) присваивается значение <dashed-ident>; затем это имя <dashed-ident> задаётся как значение свойства animation-timeline.

Анонимная временная шкала прогресса прокрутки

Свойству animation-timeline анимируемого элемента присваивается функция scroll(). Два необязательных параметра функции задают контейнер прокрутки, предоставляющий временную шкалу прогресса прокрутки, и используемую ось прокрутки.

Временная шкала прогресса просмотра

Ход покадровой анимации зависит от изменения видимости элемента внутри контейнера прокрутки; этот элемент называется объектом наблюдения. По умолчанию временная шкала находится в точке 0%, когда элемент впервые становится видимым у одного края контейнера прокрутки, и в точке 100%, когда его конечный край выходит за противоположный край контейнера прокрутки. Временную шкалу прогресса просмотра можно задать двумя способами:

Именованная временная шкала прогресса просмотра

Объекту наблюдения явно задаётся имя: свойству view-timeline-name (или сокращённому свойству view-timeline) присваивается значение <dashed-ident>. Если свойству animation-timeline анимируемого элемента присвоить это значение <dashed-ident>, видимость объекта наблюдения будет управлять ходом анимации элемента. Обратите внимание, что анимируемый элемент и объект наблюдения не обязательно должны совпадать.

Анонимная временная шкала прогресса просмотра

Свойству animation-timeline анимируемого элемента присваивается функция view(), и элемент анимируется в зависимости от его видимости в области прокрутки ближайшего родительского контейнера прокрутки.

Без временной шкалы

Все временные шкалы анимации можно удалить, выбрав значение none. Если задано значение animation-timeline: none, анимация не выполняется, поскольку ей не с чем синхронизироваться.

Свойство animation-timeline включено в сокращённое свойство animation как значение, используемое только для сброса. Это означает, что включение animation сбрасывает ранее объявленное значение animation-timeline до auto. Поскольку этот компонент сокращённого свойства используется только для сброса, задать конкретное значение через animation нельзя. При создании CSS-анимаций, управляемых прокруткой, объявление animation-timeline должно идти после объявления любого сокращённого свойства animation, чтобы оно подействовало.

Если указать несколько значений, разделённых запятыми, каждое значение animation-timeline применяется к одной анимации в порядке следования значений animation-name. Если в объявлении animation-timeline больше значений, чем значений animation-name, лишние значения временной шкалы игнорируются. Если значений animation-timeline меньше, чем значений animation-name, значения animation-timeline повторяются по порядку, пока для каждой animation-name не будет задана соответствующая временная шкала.

Если две или более временные шкалы имеют одинаковое имя <dashed-ident> и одинаковую специфичность, будет использоваться последняя из объявленных в каскаде. Если временная шкала с именем, указанным в animation-timeline, не найдена, связанная с этим значением animation-name не будет привязана к временной шкале.

Формальное определение

Формальный синтаксис

animation-timeline = 
  <single-animation-timeline>#

<single-animation-timeline> = 
  auto |
  none |
  <dashed-ident> |
  <scroll()> |
  <view()>

<scroll()> = 
  scroll( [ <scroller> || <axis> ]? )

<view()> = 
  view([<axis> || <'view-timeline-inset'>]?)

<scroller> = 
  root |
  nearest |
  self

<axis> = 
  block |
  inline |
  x |
  y

Примеры

Основы использования

В этом примере показано базовое использование свойства animation-timeline вместе со значениями none, auto и значением по умолчанию (auto).

HTML

У нас есть элемент <article> с тремя дочерними элементами <section>. У каждого элемента <section> есть уникальный id и дочерний элемент <div>.

<article>
  <section id="none">
    <div></div>
  </section>
  <section id="auto">
    <div></div>
  </section>
  <section id="default">
    <div></div>
  </section>
</article>

CSS

Мы используем гибкую блочную раскладку, чтобы разместить три секции рядом. С помощью генерируемого содержимого отображаем id. Мы применяем одинаковые стили ко всем элементам и задаём анимацию rotate @keyframes, поворачивающую элемент на один полный оборот. С помощью сокращённого свойства animation мы задаём бесконечные двухсекундные итерации анимации rotate с линейным ходом и чередованием направления.

article {
  display: flex;
  gap: 10px;
  text-align: center;
}
section {
  background-color: beige;
  padding: 20px;
}
section::after {
  content: attr(id);
  display: block;
}
div {
  height: 100px;
  width: 100px;
  background-color: magenta;
  animation: rotate 2s infinite alternate linear;
}
@keyframes rotate {
  to {
    rotate: 1turn;
  }
}

Единственное различие — объявление animation-timeline (или его отсутствие в случае default) для каждого <div>.

#none div {
  animation-timeline: none;
}
#auto div {
  animation-timeline: auto;
}

@layer no-support {
  @supports not (animation-timeline: none) {
    body::before {
      content: "Your browser doesn't support the `animation-timeline` property";
      background-color: wheat;
      display: block;
      text-align: center;
      padding: 1rem 0;
    }
  }
}

Поскольку свойство animation-timeline включено в сокращённое свойство animation как значение, используемое только для сброса, объявление animation-timeline должно идти после сокращённого свойства animation или иметь более высокую специфичность, чем сокращённое свойство animation, чтобы примениться.

Результаты

Обратите внимание, что объявление значения auto даёт тот же эффект, что и значение animation-timeline по умолчанию. Значение none удаляет все временные шкалы элемента, поэтому в случае none анимация не выполняется.

Задание именованной временной шкалы прогресса прокрутки

В этом примере в качестве временной шкалы анимации задаётся горизонтальная временная шкала прогресса прокрутки.

HTML

Наш контейнер включает три расширяющих элемента, ширины которых достаточно, чтобы контейнер стал контейнером прокрутки. В среднем элементе находится фигура, которую мы будем анимировать.

<div id="container">
  <div class="stretcher"></div>
  <div class="stretcher">
    <div id="shape"></div>
  </div>
  <div class="stretcher"></div>
</div>

CSS

Мы задаём контейнеру гибкую раскладку и устанавливаем для него width, равную половине общей ширины его гибких дочерних элементов. Значение scroll свойства overflow-x добавляет горизонтальную полосу прокрутки.

Наша временная шкала прогресса прокрутки, заданная с помощью свойств scroll-timeline-name и scroll-timeline-axis, называется --square-timeline. Эта временная шкала применяется к элементу #shape с помощью свойства animation-timeline: --square-timeline.

#container {
  display: flex;
  width: 300px;
  border: 1px solid;

  overflow-x: scroll;
  scroll-timeline-axis: inline;
  scroll-timeline-name: --square-timeline;
}

.stretcher {
  flex: 0 0 200px;
}

Приведённый ниже CSS задаёт квадрат, который поворачивается в чередующихся направлениях в соответствии с временной шкалой, указанной свойством animation-timeline. Ему присвоена временная шкала --square-timeline, названная выше. Анимация выполняется дважды, чередуя направление по мере перемещения через область просмотра. Для наглядности анимационного эффекта мы добавили срезанные углы.

#shape {
  background-color: deeppink;
  width: 100px;
  height: 100px;
  border-radius: 25px;
  corner-shape: notch;

  animation: rotateAnimation 1ms linear 2 alternate;
  animation-timeline: --square-timeline;
}

@keyframes rotateAnimation {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

@layer no-support {
  @supports not (animation-timeline: --square-timeline) {
    body::before {
      content: "Your browser doesn't support named animation timelines.";
      background-color: wheat;
      display: block;
      text-align: center;
      padding: 1rem 0;
    }
  }
}

Результат

Прокрутите страницу, чтобы увидеть анимацию элемента.

Задание анонимной временной шкалы прогресса прокрутки

В этом примере расширяется предыдущий: с помощью функции scroll() применяется анонимная временная шкала прогресса прокрутки.

CSS

Мы используем весь CSS из предыдущего примера, изменяя только значение свойства animation-timeline, чтобы переопределить значение из предыдущего примера. Временная шкала задаётся значением scroll(inline nearest), которое выбирает полосу прокрутки по встроенному направлению ближайшего родительского элемента с полосами прокрутки. Это вертикальная полоса прокрутки элемента #container, поскольку у элементов .stretcher нет переполняющего содержимого, и поэтому они не являются контейнерами прокрутки.

#shape {
  animation-timeline: scroll(inline nearest);
}

@layer no-support {
  @supports not (animation-timeline: scroll()) {
    body::before {
      content: "Your browser doesn't support the scroll() function.";
      background-color: wheat;
      display: block;
      text-align: center;
      padding: 1rem 0;
    }
  }
}

Результат

Прокрутите страницу, чтобы увидеть анимацию квадратного элемента.

Задание именованной временной шкалы прогресса просмотра

В этом примере показано, как создать и применить именованную временную шкалу прогресса просмотра. Будут анимированы два элемента, каждый из которых использует отдельный элемент в качестве контейнера прокрутки.

HTML

<main class="scroller">
  <div class="container">
    <h1>Directions</h1>
    <h2>Lincoln Memorial to Martin Luther King, Jr. Memorial</h2>
    <ol>
      <li>Head south on Lincoln Memorial Circle</li>
      <li>Turn right toward Independence Ave</li>
      <li>Turn left onto Independence Ave</li>
      <li>Turn right onto West Basin Dr</li>
      <li>Look up when you reach 64 Independence Ave!</li>
    </ol>
    <section>

В нашем HTML-коде много текста в контейнере внутри контейнера прокрутки; для краткости мы его скрыли. В середине этого длинного текста находятся два элемента <div>, которые мы будем анимировать: в первом случае — в зависимости от видимости самого элемента, во втором — в зависимости от видимости его родителя.

<div class="animated-element self">SELF</div>
<div class="animated-element parent">PARENT</div>

</section>
<h2>Martin Luther King, Jr. Memorial to Lincoln Memorial</h2>
<ol>
  <li>Head north toward Independence Ave SW</li
  ><li>Turn left onto Independence Ave</li
  ><li>Turn right toward the Korean War Veterans Memorial</li
  ><li>Take a photo of the memorial as you walk past it.</li
  ><li>Head north on Lincoln Memorial Circle</li
  ><li>Look up. You can't miss it!</li>
</ol>
  </div>
</main>

CSS

Мы создаём покадровую анимацию, изменяющую непрозрачность и масштаб элемента, и применяем её к обоим анимируемым элементам:

@keyframes animation-effect {
  0% {
    opacity: 0;
    scale: 0;
  }
  100% {
    opacity: 1;
    scale: 1;
  }
}

.animated-element {
  animation: animation-effect 1ms linear;
}

Элемент self явно назначается контейнером прокрутки для самого себя: свойству view-timeline-name присваивается значение <dashed-ident>, а это имя <dashed-ident> задаётся как значение свойства animation-timeline. В случае parent мы задаём container в качестве контейнера прокрутки для анимируемого элемента:

.self {
  view-timeline-name: --self-scroller-element;
  animation-timeline: --self-scroller-element;
}
.container {
  view-timeline-name: --parent-scroller-element;
}
.parent {
  animation-timeline: --parent-scroller-element;
}

Дополнительные объявления CSS скрыты для краткости.

@layer setup {
  section {
    display: flex;
    gap: 10px;
  }
  main {
    width: 400px;
    padding: 1em;
    height: 300px;
    overflow: scroll;
    border: 1px solid;
    background-color: beige;
    font-family: sans-serif;
  }

  li {
    margin-bottom: 0.75lh;
  }

  .animated-element {
    height: 200px;
    width: calc(100% - 2em);
    margin: auto;
    background-color: forestgreen;
    background-image:
      repeating-linear-gradient(37deg, transparent 0 52px, beige 52px 57px),
      repeating-linear-gradient(94deg, transparent 0 52px, beige 52px 57px);
    border: 1px solid;
    font-size: 3em;
    place-content: center;
  }
}

Результат

Прокрутите контейнер, чтобы увидеть анимацию обоих элементов.

Обратите внимание, как видимость элемента self управляет его собственной анимацией. В этом случае элемент находится на ключевом кадре 0%, когда верхний край входит в область просмотра, или видимую часть области прокрутки, и достигает ключевого кадра 100% только тогда, когда нижний край выходит за пределы области просмотра.

Элемент parent становится видимым только тогда, когда видим его родительский элемент, а это значит, что к моменту его появления в области просмотра анимация уже пройдена примерно на 25%. Когда элемент выходит за верхнюю границу области просмотра, анимация пройдена примерно на 75%.

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

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

См. также

• animation, animation-composition, animation-delay, animation-direction, animation-duration, animation-fill-mode, animation-iteration-count, animation-name, animation-play-state, animation-timing-function
• scroll-timeline-name, scroll-timeline-axis, scroll-timeline
• view-timeline-name, view-timeline-axis, view-timeline, view-timeline-inset
• AnimationTimeline
• Руководство: использование CSS-анимаций
• Модуль CSS-анимации
• Модуль CSS-анимации, управляемые прокруткой