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

Вызов new Vivus(...) всегда возвращает экземпляр анимации, который становится центральной точкой управления SVG-анимацией. Этот объект содержит состояние текущего прогресса, ссылки на DOM-элемент, параметры таймингов и набор методов для управления жизненным циклом отрисовки путей.

Экземпляр не является «одноразовым результатом» — это активный управляющий объект, который сохраняется в памяти и продолжает существовать до удаления DOM-узла или явного обнуления ссылок. Именно через него осуществляется вся последующая работа: запуск, остановка, сброс и управление прогрессом анимации.

При создании анимации:

const anim = new Vivus('svg-id', {
  duration: 200,
  type: 'delayed'
});

возвращается объект экземпляра, содержащий:

  • состояние текущей анимации
  • конфигурацию, переданную в конструктор
  • внутренние ссылки на обработчики и SVG-пути
  • методы управления отрисовкой

Этот объект можно рассматривать как контроллер SVG-анимации, а не как результат вычисления.

Основные свойства возвращаемого экземпляра

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

el и parent

  • el — ссылка на корневой SVG-элемент, который подвергается анимации
  • parent — DOM-узел, в котором находится SVG (или сам SVG, если он передан напрямую)

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

duration и delay

  • duration — общая длительность анимации в кадрах или условных единицах библиотеки
  • delay — задержка между анимацией отдельных путей (в зависимости от типа анимации)

Эти значения фиксируются в момент создания экземпляра и используются внутренним таймером для расчёта прогресса отрисовки.

type и pathTimingFunction

  • type — стратегия анимации (delayed, oneByOne, sync, scenario)
  • pathTimingFunction — функция распределения времени между сегментами пути

Эти параметры влияют на то, как именно Vivus интерпретирует прогресс и распределяет отрисовку по элементам SVG.

Методы, возвращаемые экземпляром

Практически все методы экземпляра возвращают сам объект, что позволяет строить цепочки вызовов. Это важная особенность API: управление анимацией построено в стиле fluent interface.

play()

Запускает или возобновляет анимацию.

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

  • тот же экземпляр Vivus

Это позволяет продолжать цепочку вызовов:

anim.play().stop();

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

stop()

Останавливает текущую анимацию, фиксируя текущее состояние отрисовки.

Возвращает:

  • экземпляр Vivus

Остановка не сбрасывает прогресс, а лишь приостанавливает обновление SVG-путей.

reset()

Сбрасывает анимацию в исходное состояние, возвращая все пути к начальному виду.

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

  • экземпляр Vivus

После вызова reset() анимация может быть запущена заново без пересоздания объекта.

finish()

Мгновенно завершает анимацию, устанавливая полный прогресс отрисовки.

Возвращает:

  • экземпляр Vivus

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

Возвращаемое значение конструктора

Сам конструктор Vivus возвращает объект, а не undefined или примитив. Это ключевая особенность библиотеки, отличающая её от многих DOM-обёрток.

const instance = new Vivus('svg-id');

instance всегда является активным объектом управления анимацией.

Внутри библиотеки создаётся набор структур:

  • массив SVG-путей
  • таймер анимации
  • состояние прогресса (обычно от 0 до 1 или от 0 до 100)
  • кэш вычисленных длины путей

Все эти данные инкапсулируются внутри возвращаемого объекта.

Прогресс анимации как возвращаемое состояние

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

Типичная модель состояния:

  • 0 — анимация не начата
  • промежуточные значения — частичная отрисовка SVG
  • 1 или 100% — завершённая анимация

В некоторых реализациях доступен метод получения состояния, который возвращает числовое значение прогресса. Это значение используется для синхронизации внешних эффектов (например, управления CSS-анимациями или триггерами интерфейса).

Callback как форма возврата результата

Помимо синхронного возвращаемого объекта, Vivus предоставляет механизм обратного вызова, который фактически дополняет модель возвращаемых значений.

new Vivus('svg-id', {}, function (anim) {
  // anim — тот же возвращаемый экземпляр
});

Здесь callback получает тот же объект, который был возвращён конструктором, что позволяет работать с ним сразу после инициализации.

Особенность заключается в том, что callback не заменяет return, а дублирует доступ к экземпляру в момент готовности SVG.

Цепочки вызовов и возврат this

Практически все методы Vivus возвращают this, что делает экземпляр самоподдерживающимся в цепочках управления:

anim.reset().play().stop().finish();

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

Это важно для:

  • минимизации количества переменных
  • упрощения управления анимациями
  • построения декларативного кода

Отсутствие «чистого» результата выполнения

Vivus не возвращает отдельный результат вроде:

  • массива координат
  • готового SVG
  • структуры данных анимации

Вся модель построена вокруг единственного возвращаемого объекта — экземпляра управления. Это означает, что «результатом выполнения» всегда остаётся живой контроллер, а не вычисленный итог.

Любая информация о состоянии извлекается либо из свойств экземпляра, либо через методы, изменяющие его поведение.

Поведение при повторных вызовах

Повторный вызов методов не создаёт новых возвращаемых объектов. Вместо этого модифицируется существующий экземпляр:

  • повторный play() не создаёт новую анимацию
  • повторный reset() сбрасывает текущее состояние без пересоздания структуры
  • повторный finish() просто фиксирует конечный кадр

Возвращаемое значение остаётся стабильным — это один и тот же объект на протяжении всего жизненного цикла.

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

Возвращаемый объект скрывает внутренние механизмы:

  • расчёт длины path
  • построение dasharray
  • управление requestAnimationFrame
  • распределение временных сегментов

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

Оглавление