setFrameProgress

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

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

Смысл прогресса кадра в архитектуре Vivus

Внутри Vivus каждый SVG-путь преобразуется в набор измеряемых сегментов. При анимации библиотека управляет параметрами:

  • длиной каждого пути
  • текущей точкой отрисовки stroke-dashoffset
  • порядком появления элементов (в зависимости от режима animMode)

Прогресс кадра представляет собой нормализованное состояние анимации, при котором:

  • 0 соответствует полностью скрытому состоянию
  • 1 соответствует полностью отрисованному SVG

Между этими значениями происходит интерполяция состояния всех элементов графики.

Принцип работы setFrameProgress

Метод setFrameProgress устанавливает внутреннее состояние анимационного цикла без запуска автоматического таймера воспроизведения. В результате вычисляется промежуточное состояние всех SVG-элементов.

Типовая сигнатура в логике библиотеки:

vivus.setFrameProgress(progress);

где progress — число в диапазоне от 0 до 1.

При передаче значения происходит пересчёт:

  • текущей позиции stroke-dashoffset для каждого пути
  • видимой части линии
  • текущего “кадра” анимационной последовательности

Математическая интерпретация прогресса

Каждый путь SVG имеет собственную длину L. При заданном прогрессе p вычисляется видимая часть:

visible_length = L * p

Оставшаяся часть скрывается через смещение обводки:

offset = L * (1 - p)

Таким образом, метод setFrameProgress фактически управляет коэффициентом заполнения пути.

visible_length = Lp

offset = L(1 - p)

Отличие от play и stop

В отличие от методов управления воспроизведением:

  • play() запускает автоматическую анимацию с временным интервалом
  • stop() приостанавливает текущий цикл
  • reset() возвращает состояние к начальному кадру

setFrameProgress не зависит от таймера и не использует внутренний requestAnimationFrame цикл. Он устанавливает состояние мгновенно и детерминированно.

Применение в управляемой анимации

Ручная установка прогресса используется в сценариях, где требуется синхронизация SVG с внешними источниками времени или состоянием интерфейса:

  • прокрутка страницы (scroll-driven animation)
  • синхронизация с аудио-воспроизведением
  • интерактивные визуализации данных
  • переходы между состояниями интерфейса
  • контроль анимации через ползунки и инпуты

В таких случаях прогресс анимации становится функцией внешнего параметра:

p = f(state)

Связь с временной шкалой

При интеграции с пользовательским вводом или временем метод позволяет рассматривать Vivus как систему временной интерполяции.

Если обозначить время анимации как t, а общую длительность как T, то:

p = t / T

p =

Таким образом, изменение времени напрямую преобразуется в изменение состояния SVG.

Особенности работы с несколькими путями

При наличии нескольких элементов SVG каждый путь имеет собственную нормализованную длину, но общий прогресс применяется ко всем одновременно.

Внутренний алгоритм выполняет:

  • вычисление длины каждого пути
  • применение глобального коэффициента прогресса
  • индивидуальный пересчёт dasharray и dashoffset

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

Ограничения точности

При экстремально малых или больших значениях прогресса возможны особенности:

  • значения ниже 0 интерпретируются как 0
  • значения выше 1 интерпретируются как 1
  • дробная точность зависит от реализации браузерного SVG engine

Также стоит учитывать, что визуальная плавность зависит от плотности точек пути, так как Vivus оперирует геометрией, а не растровыми пикселями.

Взаимодействие с режимами animTimingFunction

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

При использовании линейной модели прогресса:

p(t) = t

p(t) = t

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

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

В архитектуре управления состоянием интерфейса setFrameProgress часто становится конечной точкой вычислительного конвейера:

  • входные данные (скролл, жест, таймер)
  • нормализация в диапазон 0–1
  • передача в Vivus
  • обновление SVG

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

Поведение при резком изменении значения

При скачкообразной смене прогресса отсутствует промежуточная интерполяция. Это означает:

  • нет сглаживания между кадрами
  • визуальное состояние перескакивает напрямую
  • каждый вызов полностью пересчитывает отрисовку

Такой режим подходит для дискретных состояний интерфейса, но не для кинематически плавных переходов без внешнего интерполятора.

Влияние на производительность

Каждый вызов setFrameProgress инициирует перерасчёт геометрии всех путей SVG. При сложных изображениях с большим количеством сегментов это может приводить к:

  • увеличению нагрузки на layout engine
  • частым repaint операций
  • росту стоимости пересчёта stroke-dasharray

Оптимизация достигается ограничением частоты вызовов и использованием throttle или requestAnimationFrame в внешнем коде управления.

Оглавление