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

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

Подключение библиотеки не тем способом

Vivus может использоваться как через CDN, так и через сборщики модулей. Ошибка возникает, когда разработчик смешивает подходы: подключает скрипт как глобальный, но пытается использовать его как ES-модуль или наоборот.

При глобальном подключении должно быть доступно:

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

и только после этого:

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

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

import Vivus from 'vivus';

Ошибка проявляется как Vivus is not defined или Vivus is not a constructor.

Попытка анимации внешнего SVG-файла через

Vivus работает только с DOM-элементом SVG, а не с изображением как ресурсом. Одна из ключевых ошибок — использование конструкции:

<img src="image.svg" id="my-svg">

В таком случае библиотека не получает доступ к внутренним <path> элементам, и анимация невозможна.

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

<svg id="my-svg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200">
  <path d="..." />
</svg>

Vivus работает только с inline SVG, так как требуется прямой доступ к DOM-узлам путей.

Инициализация до загрузки DOM

Часто экземпляр Vivus создаётся до того, как SVG присутствует в DOM. В результате querySelector внутри библиотеки возвращает null.

Типичный сценарий ошибки:

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

при размещении скрипта в <head> без ожидания загрузки страницы.

Решение заключается в гарантии наличия элемента:

document.addEventListener('DOMContentLoaded', () => {
  new Vivus('my-svg', { duration: 150 });
});

или размещение скрипта перед закрывающим </body>.

Несовпадение идентификаторов и селекторов

Vivus принимает либо ID элемента, либо DOM-ссылку. Ошибки возникают при:

  • опечатках в ID
  • использовании класса вместо ID без учёта множественных элементов
  • дублировании ID на странице

Пример проблемного кода:

<svg id="logo-animation"></svg>
new Vivus('logo_animaton', { duration: 200 });

В этом случае библиотека не найдёт элемент и не выдаст визуального эффекта, а ошибка может остаться незамеченной.

SVG без корректных path-элементов

Vivus анимирует только контуры (<path>, <line>, <polyline>, <polygon>). Если SVG состоит исключительно из:

  • <rect>
  • <circle>
  • <image>
  • групп без путей

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

Дополнительно проблема возникает, когда пути объединены в один сложный shape без корректных stroke-данных.

Отсутствие stroke и stroke-dasharray поведения

Vivus визуально имитирует рисование через работу с обводкой. Если SVG изначально не содержит stroke или он скрыт через CSS, эффект может быть незаметен.

Проблемный CSS:

path {
  stroke: none;
}

Или:

path {
  stroke: transparent;
}

Также вмешательство fill без обводки часто создаёт впечатление отсутствия анимации.

Запуск на скрытых элементах

Одна из неочевидных ошибок — инициализация Vivus на элементе с display: none.


  display: none;
}

В этом случае библиотека не может корректно вычислить размеры и длины путей, что приводит к некорректной инициализации.

Аналогичная проблема возникает при:

  • visibility: hidden
  • элементах внутри неактивных вкладок
  • модальных окон без отображения

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

Vivus не предназначен для многократного создания экземпляров на одном и том же SVG без сброса состояния. Типичная ошибка:

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

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

Некорректный выбор типа анимации

Параметр type определяет стратегию отрисовки. Ошибки возникают при передаче неподдерживаемых значений или неверном понимании поведения.

Поддерживаемые режимы:

  • delayed
  • sync
  • oneByOne

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

Проблемы с параметром duration

duration ожидает числовое значение. Часто встречается ошибка передачи строки:

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

В результате вычисления временных интервалов становятся некорректными, анимация либо не запускается, либо завершается мгновенно.

Ошибки при работе в SPA (React, Vue, Angular)

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

Типичная ошибка:

  • вызов конструктора в теле компонента
  • отсутствие useEffect / mounted-хука

Проблема проявляется как null-селектор или неработающая анимация после рендера.

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

SVG-спрайты и символы <use>

Vivus не всегда корректно работает с SVG, собранными через <symbol> и <use>, поскольку реальные пути могут находиться вне текущего DOM-узла.

Ошибка выглядит как:

  • элемент найден
  • но пути внутри не анимируются

Ошибки при серверном рендеринге

При использовании SSR (например, Next.js) попытка создать экземпляр Vivus на сервере приводит к ошибке, так как отсутствует window и DOM.

Типичный симптом:

ReferenceError: window is not defined

Инициализация должна происходить только на клиенте.

Изменение SVG после инициализации

Если DOM-структура SVG меняется после создания экземпляра Vivus (например, через JS или динамическую загрузку), библиотека не пересчитывает пути автоматически.

Это приводит к состоянию, когда:

  • анимация рассчитана на старые path
  • новые элементы игнорируются
  • визуальный результат частично отсутствует

Конфликты CSS-трансформаций

Применение transform, scale, rotate к SVG или его контейнеру до инициализации может исказить расчёт длины пути. Особенно критично:

  • transform: scale(0)
  • transform: translateZ(0) в некоторых старых браузерах
  • анимации через CSS одновременно с Vivus

Ошибки из-за отсутствия viewBox

SVG без viewBox часто приводит к некорректному масштабированию и вычислению длины путей.

<svg width="200" height="200">

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

Несоответствие координат при импортированных SVG

SVG, экспортированные из графических редакторов, часто содержат:

  • избыточные группы <g>
  • трансформации на уровне групп
  • вложенные координатные системы

Vivus может корректно обработать структуру, но анимация выглядит «ломаной» из-за некорректного расчёта пути.

Итоговая природа большинства проблем

Большинство ошибок инициализации связано не с самой библиотекой, а с несоответствием ожиданий:

  • Vivus работает только с уже отрисованным inline SVG
  • требует доступных path-элементов
  • чувствителен к моменту инициализации
  • не компенсирует ошибки разметки SVG

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

Оглавление