Свойство CSS `animation-range`

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

Составные свойства

Это сокращённое свойство для следующих свойств CSS:

• animation-range-start
• animation-range-end

Синтаксис

/* Range start value only*/
/* Single value syntax */
animation-range: normal;
animation-range: 20%;
animation-range: 100px;
animation-range: cover;
animation-range: contain;
/* Two value syntax */
animation-range: cover 20%;
animation-range: contain 100px;

/* Range start and end values */
/* Two value syntax */
animation-range: normal 25%;
animation-range: 25% normal;
animation-range: 25% 50%;
animation-range: entry exit;
/* Three value syntax */
animation-range: cover cover 200px;
animation-range: 10% exit 90%;
animation-range: entry 10% 90%;
/* Four value syntax */
animation-range: cover 0% cover 200px;
animation-range: entry 10% exit 100%;

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

Значения

Сокращённое свойство animation-range задаётся одним или несколькими отдельными диапазонами анимации, разделёнными запятыми. Каждый диапазон анимации задаётся от одного до четырёх значений, разделённых пробелами и состоящих из значений <timeline-range-name>, значений <length-percentage> и/или ключевого слова normal.

<animation-range-start>

Ключевое слово normal, значение <length-percentage>, значение <timeline-range-name> или пара <timeline-range-name> <length-percentage>, представляющие animation-range-start. Если задано <timeline-range-name> без <length-percentage>, для <length-percentage> по умолчанию используется 0%.

<animation-range-end>

Ключевое слово normal, значение <length-percentage>, значение <timeline-range-name> или пара <timeline-range-name> <length-percentage>, представляющие animation-range-end. Если задано <timeline-range-name> без <length-percentage>, для <length-percentage> по умолчанию используется 100%.

Описание

Сокращённое свойство animation-range задаёт значения animation-range-start и animation-range-end, определяющие точки начала и конца анимации на её временной шкале. По умолчанию стили, заданные в ключевых кадрах анимации, применяются к элементу только во время его анимации. Применение ключевых кадров анимации к элементу зависит от временной шкалы этой анимации. По умолчанию анимации применяются только в пределах начальной и конечной точек временной шкалы. Чтобы применить анимацию за пределами этого диапазона, задайте для animation-fill-mode значение backwards, forwards или both. Эти три значения animation-fill-mode применяют стили первого ключевого кадра до начальной точки, стили последнего ключевого кадра после окончания анимации или стили обоих кадров до и после неё соответственно.

Область прокрутки, известная как диапазон видимости прогресса просмотра, — это область, в которой элемент, являющийся объектом анимации с именованной временной шкалой прогресса просмотра, считается видимым. По умолчанию это весь диапазон области прокрутки, но его можно настроить с помощью свойства view-timeline-inset.

Если в качестве компонентов свойства <animation-range> указаны два значения, они интерпретируются в порядке <animation-range-start>, затем <animation-range-end>. Значением каждого компонента может быть ключевое слово normal, значение <length-percentage> или значение <timeline-range-name>, за которым может следовать <length-percentage>. Эти значения разделяются пробелами. Значение normal эквивалентно 0% для начала и 100% для конца. Задание normal вместе с <length-percentage> для начального или конечного диапазона недопустимо.

Определение начального диапазона и значения конечного диапазона по умолчанию

Если вы задаёте только <animation-range-start> — указывая одно значение <length-percentage>, одно значение <timeline-range-name>, ключевое слово normal или одно значение <timeline-range-name>, за которым следует одно значение <length-percentage>, — вычисленное значение <animation-range-end> определяется по особым правилам:

Если указано одно значение <length-percentage> или ключевое слово normal, это значение задаёт <animation-range-start>, а для <animation-range-end> неявно устанавливается значение normal. Например:

• animation-range: 20%; эквивалентно animation-range-start: 20%; animation-range-end: normal;
• animation-range: normal; эквивалентно animation-range-start: normal; animation-range-end: normal;

Если указано одно значение <timeline-range-name> (без следующего за ним <length-percentage>), это имя диапазона временной шкалы применяется к обоим компонентам — <animation-range-start> и <animation-range-end>, — подразумевая соответственно диапазоны 0% и 100%. Например:

• animation-range: contain; эквивалентно animation-range-start: contain 0%; animation-range-end: contain 100%;
• animation-range: cover; эквивалентно animation-range-start: cover 0%; animation-range-end: cover 100%;

Если указано одно значение <timeline-range-name>, за которым в этом порядке следует одно значение <length-percentage>, эта пара задаёт <animation-range-start>, а заданное <timeline-range-name> применяется к <animation-range-end> в точке 100%. Например:

• animation-range: cover 20%; эквивалентно animation-range-start: cover 20%; animation-range-end: cover 100%;
• animation-range: contain 100px; эквивалентно animation-range-start: contain 100px; animation-range-end: contain 100%;

Явное задание начального и конечного диапазонов двумя значениями

Если в объявлении animation-range указаны два или более значения, и это не одно значение <timeline-range-name>, за которым следует <length-percentage>, то оба значения — <animation-range-start> и <animation-range-end> — задаются явно.

Если указаны два значения и первое из них — ключевое слово normal или значение <length-percentage>, оно задаёт <animation-range-start>, а второе значение задаёт <animation-range-end>. Например:

• animation-range: normal 25%; эквивалентно animation-range-start: normal; animation-range-end: 25%;
• animation-range: 25% 50%; эквивалентно animation-range-start: 25%; animation-range-end: 50%;
• animation-range: 25% contain; эквивалентно animation-range-start: 25%; animation-range-end: contain 100%;
• animation-range: 25% normal; эквивалентно animation-range-start: 25%; animation-range-end: normal;

Несколько анимаций

При задании диапазонов для нескольких анимаций сокращённое свойство animation-range задаётся одним или несколькими отдельными диапазонами анимации, разделёнными запятыми. Каждый диапазон animation-range применяется к анимациям в том порядке, в котором указаны значения animation-name. Если количество анимаций и значений свойства animation-range не совпадает, лишние значения animation-range игнорируются, когда их больше, чем анимаций. Если анимаций больше, чем диапазонов, список значений animation-range повторяется, пока для каждой анимации не будет задан соответствующий диапазон. Например, если задать animation-range: 25% 75%, normal;, диапазон анимации всех нечётных по порядку анимаций будет 25% 75%, а всех чётных — 0% 100%.

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

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

animation-range = 
  [ <'animation-range-start'> <'animation-range-end'>? ]#

Примеры

Базовое использование свойства animation-range

В этом примере мы сокращаем длительность анимации прокрутки с прогрессом просмотра, используя свойство animation-range для смещения начала и конца анимации, а также демонстрируем влияние свойства animation-fill-mode на сокращённые временные шкалы анимации.

HTML

В середине большого объёма текста мы размещаем элемент, который будем анимировать. Мы добавляем много текста, чтобы содержимое выходило за границы контейнера, но для краткости скрываем его. Также мы добавляем флажок, позволяющий включать и отключать свойство animation-fill-mode, чтобы продемонстрировать его влияние на сокращённые временные шкалы анимации. Он тоже скрыт.

<div class="content">
  <h1>Content</h1>

  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
    tempor incididunt ut labore et dolore magna aliqua. Risus quis varius quam
    quisque id. Et ligula ullamcorper malesuada proin libero nunc consequat
    interdum varius. Elit ullamcorper dignissim cras tincidunt lobortis feugiat
    vivamus at augue.
  </p>

  <p>
    Dolor sed viverra ipsum nunc aliquet. Sed sed risus pretium quam vulputate
    dignissim. Tortor aliquam nulla facilisi cras. A erat nam at lectus urna
    duis convallis convallis. Nibh ipsum consequat nisl vel pretium lectus.
    Sagittis aliquam malesuada bibendum arcu vitae elementum. Malesuada bibendum
    arcu vitae elementum curabitur vitae nunc sed velit.
  </p>

<div class="animatedElement"></div>

  <p>
    Adipiscing enim eu turpis egestas pretium aenean pharetra magna ac. Arcu
    cursus vitae congue mauris rhoncus aenean vel. Sit amet cursus sit amet
    dictum. Augue neque gravida in fermentum et. Gravida rutrum quisque non
    tellus orci ac auctor augue mauris. Risus quis varius quam quisque id diam
    vel quam elementum. Nibh praesent tristique magna sit amet purus gravida
    quis. Duis ultricies lacus sed turpis tincidunt id aliquet. In egestas erat
    imperdiet sed euismod nisi. Eget egestas purus viverra accumsan in nisl nisi
    scelerisque. Netus et malesuada fames ac.
  </p>
  <label>
    <input type="checkbox" /> Add <code>animation-fill-mode: both;</code>
  </label>
</div>

CSS

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

Временная шкала прогресса просмотра создаётся путём задания функции view() в качестве значения свойства animation-timeline для нашего animatedElement. В результате элемент анимируется, перемещаясь вверх по документу при прокрутке. Мы объявляем свойство animation-timeline после сокращённого свойства, поскольку сокращённое свойство сбрасывает это свойство.

Наконец, объявление animation-range задаёт начало анимации позже ожидаемого и её завершение раньше.

.animatedElement {
  background-color: deeppink;
  animation: appear 1ms linear;
  animation-timeline: view();
  animation-range: entry 10% exit -25%;
}

@keyframes appear {
  from {
    background-color: rebeccapurple;
    opacity: 0;
    transform: scaleX(0);
  }

  to {
    background-color: darkturquoise;
    opacity: 0.75;
    transform: scaleX(0.75);
  }
}

Мы также добавляем условный стиль: когда установлен флажок, к анимируемому элементу применяется свойство animation-fill-mode:

:has(:checked) .animatedElement {
  animation-fill-mode: both;
}

Для краткости остальные стили скрыты.

.animatedElement {
  width: 300px;
  height: 200px;
  margin: 0 auto;
  background-color: deeppink;
}

:has(:checked) .animatedElement {
  animation-fill-mode: both;
}

.content {
  width: 75%;
  max-width: 800px;
  margin: 0 auto;
}

p,
h1 {
  font-family: "Helvetica", "Arial", sans-serif;
}

h1 {
  font-size: 3rem;
}

p {
  font-size: 1.5rem;
  line-height: 1.5;
}
@supports not (animation-range: normal) {
  body::before {
    content: "Your browser does not support the 'animation-range' property.";
    background-color: wheat;
    display: block;
    text-align: center;
    padding: 1rem 0;
  }
}

Результат

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

Обратите внимание: значения свойства ключевого кадра from, или 0%, не применяются к анимируемому элементу, пока верхняя граница блока не окажется на 10% ниже нижней границы контейнера; до этого элемент имеет исходный размер, полностью непрозрачен и окрашен в пурпурный цвет. В этот момент применяется анимация, и элементу задаются значения, определённые селектором ключевого кадра 0%. Когда достигается animation-range-end, расположенная на 25% ниже верхнего края области прокрутки, элемент возвращается к исходному стилю.

Как правило, при создании анимаций, управляемых прокруткой, следует задавать animation-fill-mode: both. Возврат к исходному состоянию происходит потому, что мы не задали для элемента свойство animation-fill-mode, которое позволяет применять стили анимации к элементу до и после её выполнения. Изначально мы не указывали это свойство в примере, чтобы лучше показать действие animation-range.

Установите флажок, чтобы применить к анимируемому элементу свойство animation-fill-mode, а затем прокрутите страницу ещё раз: теперь стили анимации должны применяться непрерывно.

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

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

См. также

• animation-timeline
• animation-range-end
• animation-range-start
• scroll-timeline
• timeline-scope
• view-timeline-inset
• animation-fill-mode
• Разбираемся в именах диапазонов временной шкалы
• Модуль CSS-анимации, управляемые прокруткой
• Визуализатор диапазонов временной шкалы просмотра