Типы данных и интерфейсы

Библиотека анимации Velocity.js опирается на строго определённый набор типов данных, которые используются для описания целевых свойств, параметров анимации и конфигураций. Понимание структуры этих данных критично для корректного построения анимаций и предсказуемого поведения движка.

Числовые значения

Числа являются основой большинства анимационных свойств. Они применяются для:

  • координат (translateX, translateY)
  • размеров (width, height)
  • прозрачности (opacity)
  • углов вращения (rotate, rotateZ)

Velocity.js поддерживает как целые числа, так и числа с плавающей точкой:

Velocity(element, {
  opacity: 0.5,
  translateY: 150.75,
  rotateZ: 45
});

Особенность обработки чисел заключается в автоматической интерполяции значений между начальным и конечным состоянием. Движок самостоятельно определяет шаги анимации и применяет easing-функцию.

Строковые значения

Строки используются для передачи значений с единицами измерения:

Velocity(element, {
  width: "200px",
  height: "50%",
  translateX: "10rem"
});

Поддерживаются стандартные CSS-единицы:

  • px
  • %
  • em / rem
  • vh / vw

Velocity.js анализирует строку, выделяет числовую часть и единицу измерения, после чего интерполирует только числовой компонент.

Массивы значений

Массивы используются для описания последовательных состояний или ключевых кадров:

Velocity(element, {
  translateX: [0, 100]
});

Внутренняя интерпретация массива строится по принципу:

  • первый элемент — конечное значение
  • второй элемент — начальное значение

При необходимости могут добавляться дополнительные параметры, такие как привязка к стилю:

Velocity(element, {
  opacity: [1, 0]
}, {
  duration: 800
});

Объекты как структурированные значения

Объекты применяются для более сложных анимационных описаний, особенно при работе с transforms:

Velocity(element, {
  translate: { x: 100, y: 50 },
  scale: 1.2
});

Такая структура позволяет группировать логически связанные параметры и упрощает управление многомерными трансформациями.

Интерфейс параметров анимации

Конфигурационный объект Velocity.js определяет поведение анимации. Он содержит набор строго типизированных полей, каждое из которых влияет на исполнение.

Основная структура параметров

Типизированное представление параметров может быть описано следующим образом:

interface VelocityOptions {
  duration?: number;
  easing?: string | number[];
  delay?: number;
  loop?: number | boolean;
  begin?: (elements: Element[]) => void;
  complete?: (elements: Element[]) => void;
  progress?: (elements: Element[], percentComplete: number) => void;
  display?: string;
  visibility?: string;
  queue?: string | boolean;
}

duration

Определяет длительность анимации в миллисекундах.

Velocity(element, { opacity: 1 }, { duration: 1200 });

Тип данных: number

Поведение линейно зависит от времени исполнения, но фактическая траектория управляется easing-функцией.

easing

Определяет функцию интерполяции.

Допустимые типы:

  • строка ("easeInOutQuad")
  • массив чисел (кастомная кривая Безье)
Velocity(element, { translateY: 300 }, { easing: "ease-out" });

Кастомный вариант:

easing: [0.25, 0.1, 0.25, 1]

Массив интерпретируется как параметры кривой Безье.

delay

Задержка перед стартом анимации.

Velocity(element, { opacity: 0 }, { delay: 300 });

Тип: number

Используется для построения последовательных цепочек анимаций.

loop

Управляет повторением анимации.

Допустимые значения:

  • true — бесконечный цикл
  • number — количество повторений
Velocity(element, { rotateZ: 360 }, { loop: 3 });

Типы callback-функций

Velocity.js использует набор обратных вызовов для контроля жизненного цикла анимации.

begin

Вызывается перед стартом анимации.

begin: (elements) => {
  elements.forEach(el => {
    el.classList.add("animating");
  });
}

Тип параметра elements — массив DOM-элементов.

progress

Отслеживает прогресс выполнения анимации.

progress: (elements, percent) => {
  console.log(percent);
}

Тип percent — число от 0 до 1.

complete

Срабатывает после завершения анимации.

complete: (elements) => {
  elements.forEach(el => {
    el.classList.remove("animating");
  });
}

Типизация свойств анимации

Свойства, передаваемые в Velocity.js, можно классифицировать по типам поведения.

CSS-свойства

Наиболее распространённый тип данных. Поддерживаются стандартные CSS-параметры:

Velocity(element, {
  opacity: 0,
  width: "300px",
  backgroundColor: "#fff"
});

Тип значения:

type CSSValue = number | string;

Transform-свойства

Velocity.js использует оптимизированный механизм для transform-операций.

Velocity(element, {
  translateX: 100,
  translateY: 50,
  scale: 0.8,
  rotateZ: 90
});

Типизация:

interface TransformProperties {
  translateX?: number | string;
  translateY?: number | string;
  translateZ?: number | string;
  scale?: number;
  rotateX?: number;
  rotateY?: number;
  rotateZ?: number;
}

SVG-значения

Поддержка SVG включает анимацию атрибутов:

Velocity(circle, {
  r: 80,
  cx: 150,
  cy: 150
});

Тип данных: числовые значения без единиц измерения.

Интерфейсы элементов и коллекций

Velocity.js работает не только с одиночными элементами, но и с коллекциями DOM.

Element

Базовый тип:

type Element = HTMLElement | SVGElement;

Поддерживаются все стандартные DOM-узлы, включая SVG.

ElementCollection

type ElementCollection = NodeListOf<Element> | Element[];

Анимация применяется ко всем элементам коллекции одновременно, с возможностью stagger-эффектов через дополнительные плагины.

Типизация вызова Velocity

Основная функция библиотеки имеет перегруженную сигнатуру:

function Velocity(
  elements: Element | ElementCollection,
  properties: Record<string, any>,
  options?: VelocityOptions
): Promise<void> | void;

Особенности типов:

  • elements — цель анимации
  • properties — объект анимационных значений
  • options — конфигурация исполнения

Возвращаемое значение может быть Promise, если включена поддержка промисов.

Интерфейсы очередей анимации

Velocity.js использует систему очередей для управления последовательностью анимаций.

type QueueOption = string | boolean;

Поведение:

  • true — использование стандартной очереди
  • false — отключение очереди
  • string — именованная очередь

Пример:

Velocity(element, { opacity: 1 }, { queue: "fx" });

Кастомные типы и расширения

Velocity.js позволяет расширять систему типов через плагины.

Пользовательские свойства

Velocity.RegisterEffect({
  name: "fadeSlide",
  defaultDuration: 800,
  calls: [
    [{ opacity: 1, translateY: 0 }, 0.5],
    [{ opacity: 0, translateY: 20 }, 0.5]
  ]
});

Типизация эффекта:

interface VelocityEffect {
  name: string;
  defaultDuration: number;
  calls: Array<[Record<string, any>, number]>;
}

Кастомные easing-функции

Velocity.Easings.customBezier = function (t) {
  return t * t * (3 - 2 * t);
};

Тип:

type EasingFunction = (t: number) => number;

Типы данных времени выполнения

В процессе анимации Velocity.js оперирует внутренними значениями:

  • текущий прогресс (number)
  • временные метки (timestamp)
  • вычисленные стили (CSS computed values)
  • интерполированные состояния (intermediate frames)

Эти данные не доступны напрямую, но определяют точность и плавность анимации.

Совместимость типов с JavaScript средой

Velocity.js не требует строгой типизации, однако при использовании TypeScript структура интерфейсов позволяет:

  • избежать ошибок передачи параметров
  • унифицировать анимационные конфигурации
  • расширять функциональность без нарушения API

Типовая модель строится вокруг гибридной системы:

  • динамические значения JavaScript
  • формализованные интерфейсы TypeScript
  • интерпретируемые runtime-типы движка анимации
Оглавление