Установка и подключение к проекту

Vivus — легковесная JavaScript-библиотека для анимации SVG, создающая эффект «рисования» линий. Установка возможна несколькими способами в зависимости от архитектуры проекта.

Установка через npm

Использование менеджера пакетов npm — стандартный способ для современных проектов.

npm install vivus

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

import Vivus from 'vivus';

При использовании сборщиков (например, Webpack, Vite или Parcel) импорт автоматически включается в итоговый бандл.

Установка через yarn

Альтернативный способ установки:

yarn add vivus

Импорт аналогичен:

import Vivus from 'vivus';

Подключение через CDN

Для быстрого прототипирования или небольших проектов библиотека может быть подключена напрямую через CDN.

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

После подключения объект Vivus становится доступен в глобальной области видимости:

new Vivus('my-svg');

Структура проекта и подготовка SVG

Vivus работает только с inline SVG, встроенными непосредственно в HTML. Использование <img> или background-image не поддерживается.

Пример корректной структуры:

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

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

  • SVG должен быть встроен в HTML
  • Все анимируемые элементы должны быть представлены через <path>
  • Атрибут viewBox обязателен для корректного масштабирования

Подключение в HTML-файле

Минимальный пример подключения:

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <title>Vivus Example</title>
</head>
<body>

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

<script src="https://cdn.jsdelivr.net/npm/vivus@latest/dist/vivus.min.js"></script>
<script>
  new Vivus('my-svg');
</script>

</body>
</html>

Подключение в модульных проектах

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

import Vivus from 'vivus';

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

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

  • Инициализация выполняется после загрузки DOM
  • Возможна передача параметров конфигурации
  • Поддерживается модульная структура кода

Проверка корректности подключения

Признаки успешного подключения:

  • В консоли отсутствуют ошибки
  • SVG появляется на странице
  • Анимация запускается при инициализации Vivus

Типичные ошибки:

1. SVG не анимируется

  • Причина: используется <img> вместо inline SVG

2. Ошибка Vivus is not defined

  • Причина: скрипт не подключён или подключён после использования

3. Ничего не происходит

  • Причина: отсутствует id у SVG или он не совпадает с переданным в Vivus

Организация файлов

Рекомендуемая структура проекта:

project/
│
├── index.html
├── js/
│   └── main.js
├── svg/
│   └── illustration.svg
└── package.json

Если SVG хранится в отдельном файле, его необходимо вставить в HTML:

  • вручную (копированием содержимого)
  • через загрузку и вставку в DOM (например, через fetch)

Пример динамической загрузки:

fetch('/svg/illustration.svg')
  .then(response => response.text())
  .then(data => {
    document.body.insertAdjacentHTML('beforeend', data);
    new Vivus('my-svg');
  });

Минимальная конфигурация запуска

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

new Vivus('my-svg');

Расширенный вариант:

new Vivus('my-svg', {
  type: 'delayed',
  duration: 150,
  start: 'autostart'
});

Подключение нескольких SVG

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

new Vivus('svg1');
new Vivus('svg2');
new Vivus('svg3');

Либо через цикл:

['svg1', 'svg2', 'svg3'].forEach(id => {
  new Vivus(id);
});

Совместимость и требования

  • Поддержка современных браузеров (Chrome, Firefox, Edge, Safari)
  • Не требуется дополнительных зависимостей
  • Размер библиотеки — около 10 КБ (minified)

Рекомендации по подключению

  • Для продакшена предпочтительно использовать npm/yarn и сборку
  • Для прототипов — CDN
  • SVG оптимизировать (например, через SVGO)
  • Избегать сложных и перегруженных SVG для повышения производительности

Проверка загрузки DOM

Инициализация должна происходить после полной загрузки SVG:

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

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

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

Подключение с defer

Для корректной загрузки скриптов можно использовать атрибут defer:

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

Это гарантирует выполнение скриптов после построения DOM.

Интеграция с фреймворками

В средах React, Vue или Angular подключение выполняется через npm, а инициализация — в жизненном цикле компонента.

Пример для React:

import { useEffect } from 'react';
import Vivus from 'vivus';

function App() {
  useEffect(() => {
    new Vivus('my-svg');
  }, []);

  return (
    <svg id="my-svg">
      <path d="..." />
    </svg>
  );
}

Резюме ключевых шагов подключения

  • Установка через npm/yarn или подключение через CDN
  • Вставка inline SVG в HTML
  • Инициализация Vivus с указанием id
  • Проверка загрузки DOM перед запуском
  • Устранение типичных ошибок при подключении
Оглавление