Инициализация библиотеки

Vivus распространяется как самостоятельный JavaScript-файл и может быть подключён несколькими способами: через CDN, локальный файл или систему сборки модулей.

Через CDN:

<script src="https://cdn.jsdelivr.net/npm/vivus@latest/dist/vivus.min.js"></script>

Локальное подключение:

<script src="js/vivus.min.js"></script>

Использование с npm:

npm install vivus
import Vivus from 'vivus';

При использовании модульных сборщиков (например, Webpack или Vite) важно убедиться, что SVG-файлы корректно обрабатываются и доступны в DOM.

Подготовка SVG

Vivus работает только с inline SVG, а не с <img> или background-image.

Корректный вариант:

<svg id="my-svg" viewBox="0 0 200 200">
  <path d="M10 10 L190 10 L190 190 L10 190 Z" />
</svg>

Некорректный вариант:

<img src="image.svg">

Ключевые требования к SVG:

  • Все анимируемые элементы должны быть представлены в виде <path>, <line>, <polyline>, <polygon>, <circle> или <rect>
  • Желательно предварительно оптимизировать SVG (например, через SVGO)
  • Чем меньше лишних групп (<g>), тем проще управлять анимацией

Базовая инициализация

Создание экземпляра Vivus — основной шаг запуска анимации:

new Vivus('my-svg');

Где 'my-svg' — это id SVG-элемента.

По умолчанию:

  • Анимация запускается автоматически
  • Используется тип анимации delayed
  • Скорость — стандартная

Конструктор Vivus

Полная сигнатура конструктора:

new Vivus(element, options, callback);

Параметры:

1. element

  • Строка (id элемента) или сам DOM-элемент
new Vivus(document.getElementById('my-svg'));

2. options

  • Объект конфигурации анимации

3. callback

  • Функция, вызываемая после завершения анимации

Основные параметры инициализации

type — тип анимации

Определяет способ прорисовки SVG:

new Vivus('my-svg', {
  type: 'delayed'
});

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

  • delayed — элементы рисуются с задержкой (по умолчанию)
  • sync — все линии рисуются одновременно
  • oneByOne — поочерёдная отрисовка
  • scenario — кастомный сценарий через data-атрибуты
  • scenario-sync — синхронный сценарий

duration — длительность

Количество кадров анимации:

new Vivus('my-svg', {
  duration: 200
});

Чем больше значение, тем медленнее анимация.

start — момент запуска

Определяет, когда начинается анимация:

new Vivus('my-svg', {
  start: 'autostart'
});

Возможные значения:

  • autostart — запуск сразу
  • manual — запуск вручную
  • inViewport — запуск при появлении в области видимости

delay — задержка между элементами

new Vivus('my-svg', {
  delay: 50
});

Актуально для типов delayed и oneByOne.

dashGap — зазор штриха

new Vivus('my-svg', {
  dashGap: 20
});

Контролирует расстояние между штрихами при анимации.

forceRender — принудительный рендер

new Vivus('my-svg', {
  forceRender: false
});

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

reverseStack — порядок анимации

new Vivus('my-svg', {
  reverseStack: true
});

Меняет порядок отрисовки элементов на обратный.

Callback-функция

Функция, выполняемая после завершения анимации:

new Vivus('my-svg', {}, function () {
  console.log('Анимация завершена');
});

Можно использовать для:

  • запуска другой анимации
  • изменения классов
  • взаимодействия с UI

Ручное управление инициализацией

При использовании start: 'manual' требуется явный запуск:

const animation = new Vivus('my-svg', {
  start: 'manual'
});

animation.play();

Дополнительные методы:

animation.stop();
animation.reset();
animation.finish();

Инициализация при появлении в viewport

new Vivus('my-svg', {
  start: 'inViewport'
});

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

Важно:

  • SVG должен быть в DOM на момент инициализации
  • Не работает корректно при display: none

Использование data-атрибутов (scenario)

Для сложных анимаций можно управлять каждым элементом через HTML:

<path d="..." data-start="0" data-duration="20"></path>
<path d="..." data-start="30" data-duration="10"></path>

Инициализация:

new Vivus('my-svg', {
  type: 'scenario'
});

Параметры:

  • data-start — момент начала
  • data-duration — длительность
  • data-delay — задержка

Инициализация после загрузки DOM

Важно гарантировать, что SVG уже присутствует в документе:

document.addEventListener('DOMContentLoaded', function () {
  new Vivus('my-svg');
});

Или:

window.onl oad = function () {
  new Vivus('my-svg');
};

Разница:

  • DOMContentLoaded — быстрее, не ждёт загрузки изображений
  • window.onload — ждёт полной загрузки страницы

Повторная инициализация

Если SVG динамически изменяется, требуется пересоздание экземпляра:

let vivus = new Vivus('my-svg');

// позже
vivus.reset().play();

Или полностью:

vivus = new Vivus('my-svg');

Типичные ошибки при инициализации

1. SVG не inline

  • Vivus не работает с <img>

2. Неверный id

new Vivus('wrong-id'); // ошибка

3. SVG отсутствует в DOM

  • Инициализация происходит слишком рано

4. Отсутствие путей

  • Если SVG содержит только <g>, анимации не будет

5. display: none

  • Vivus не может вычислить длину путей

Минимальный рабочий пример

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/vivus@latest/dist/vivus.min.js"></script>
</head>
<body>

<svg id="my-svg" viewBox="0 0 100 100">
  <path d="M10 10 L90 10 L90 90 L10 90 Z" stroke="black" fill="none"/>
</svg>

<script>
  new Vivus('my-svg', {
    duration: 150,
    type: 'oneByOne'
  });
</script>

</body>
</html>

Ключевые аспекты инициализации

  • Экземпляр Vivus управляет всей анимацией SVG
  • Конфигурация задаётся через объект options
  • Inline SVG — обязательное условие
  • Инициализация должна происходить после загрузки DOM
  • Поведение анимации полностью определяется параметрами конструктора
Оглавление