Скачивание и локальное подключение

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

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

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

Наиболее распространённый способ интеграции — использование npm. Библиотека устанавливается как зависимость проекта и попадает в директорию node_modules.

npm install lottie-web

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

import lottie from "lottie-web";

или в CommonJS-окружении:

const lottie = require("lottie-web");

Структура пакета включает минимизированную сборку, исходные модули и дополнительные файлы для разных сценариев использования. В большинстве современных сборщиков (Webpack, Vite, Rollup) автоматически выбирается оптимальная версия.

Локальное подключение через файл библиотеки

При отсутствии сборщика используется прямое подключение JavaScript-файла. В этом случае библиотека скачивается вручную из репозитория или берётся из папки build установленного пакета.

Типичный путь внутри npm-пакета:

node_modules/lottie-web/build/player/lottie.min.js

Файл можно скопировать в структуру проекта:

/assets/libs/lottie/lottie.min.js

И подключить через тег script:

<script src="assets/libs/lottie/lottie.min.js"></script>

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

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

Альтернативный вариант — использование CDN-версии. Он подходит для быстрых прототипов и простых страниц без локальной сборки.

<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>

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

Структура файлов библиотеки

Внутри дистрибутива Lottie Web присутствуют несколько вариантов сборок:

build/
 ├── player/
 │    ├── lottie.js
 │    ├── lottie.min.js
 ├── lottie_light.js
 ├── lottie_svg.js

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

  • lottie.js — полная версия с поддержкой всех возможностей
  • lottie.min.js — минимизированная версия для продакшена
  • lottie_light.js — облегчённая сборка
  • lottie_svg.js — версия, оптимизированная для SVG-рендера

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

Локальное хранение JSON-анимаций

Lottie Web работает с анимациями в формате JSON, экспортируемыми из Adobe After Effects через Bodymovin. Эти файлы также обычно хранятся локально.

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

/assets
   /lottie
      animation1.json
      animation2.json

Загрузка анимации осуществляется через путь к локальному файлу:

lottie.loadAnimation({
  container: document.getElementById("animation"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  path: "assets/lottie/animation1.json"
});

Использование локального JSON позволяет полностью исключить сетевые зависимости во время исполнения.

Размещение в проекте без сборщика

В проектах без Webpack или Vite структура обычно строится вокруг простого HTML:

/project
  index.html
  /js
    lottie.min.js
    app.js
  /assets
    animation.json

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

<script src="js/lottie.min.js"></script>
<script src="js/app.js"></script>

В app.js уже доступен глобальный объект:

lottie.loadAnimation({
  container: document.querySelector("#anim"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  path: "assets/animation.json"
});

Особенности локального использования

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

Ограничения file://

Открытие HTML напрямую из файловой системы может блокировать загрузку JSON через fetch. Браузеры часто запрещают такие запросы из соображений безопасности.

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

Работа через локальный сервер

При локальном использовании HTTP-сервера структура остаётся идентичной, но доступ к ресурсам становится стабильным. Любой статический сервер подходит для корректной работы загрузки JSON.

Кэширование файлов

При локальной разработке браузер может кэшировать как JavaScript-библиотеку, так и JSON-анимации. Это влияет на отображение изменений.

Поскольку Lottie Web активно используется в UI-анимациях, обновление файлов требует контроля кэша, особенно при итеративной разработке.

Разделение среды разработки и продакшена

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

В типичной схеме:

  • разработка — подключение из node_modules
  • продакшен — сборка и минификация в dist
  • статические ресурсы — перенос в CDN или локальный сервер

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

Минификация и оптимизация

Файл lottie.min.js представляет собой сжатую версию библиотеки. Он уменьшает размер загрузки за счёт удаления пробелов, сокращения имён переменных и оптимизации структуры кода.

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

Совместимость версий

Разные версии Lottie Web могут отличаться API и внутренней реализацией рендеринга. При локальном хранении фиксированная версия становится частью проекта, что исключает неожиданные изменения поведения.

Версионная структура npm-пакета позволяет явно контролировать:

  • стабильность API
  • поддержку SVG/Canvas
  • работу с mask и path-анимациями
  • производительность на мобильных устройствах

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

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

const anim1 = lottie.loadAnimation({
  container: document.querySelector("#a1"),
  renderer: "svg",
  loop: true,
  autoplay: true,
  path: "assets/a1.json"
});

const anim2 = lottie.loadAnimation({
  container: document.querySelector("#a2"),
  renderer: "svg",
  loop: false,
  autoplay: true,
  path: "assets/a2.json"
});

Каждый экземпляр управляет собственным состоянием и ресурсами рендеринга.

Организация локальных зависимостей

При масштабировании проекта целесообразно выделять отдельный слой для сторонних библиотек:

/vendor
   lottie/
      lottie.min.js
/assets
/js
/css

Такой подход упрощает обновление и контроль версий, особенно если библиотека используется без пакетного менеджера.

Интеграция в модульные сборки

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

import lottie from "../vendor/lottie/lottie.min.js";

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

Поведение в изолированных окружениях

В некоторых сценариях, например в WebView или iframe, локально подключённая версия работает автономно. Это особенно важно для приложений, где доступ к внешним ресурсам ограничен.

Lottie Web в таких условиях сохраняет способность воспроизводить анимации полностью офлайн, при условии локального хранения JSON и скриптов.

Контроль загрузки ресурсов

При локальной интеграции важно учитывать последовательность загрузки:

  1. библиотека lottie.min.js
  2. DOM-структура контейнера
  3. JSON-анимации

Нарушение порядка приводит к ошибкам инициализации, поскольку библиотека не находит целевые DOM-элементы.

Использование относительных путей

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

path: "./assets/lottie/animation.json"

Даже незначительное изменение директории влияет на доступность JSON-файлов.

Работа в офлайн-режиме

Полностью локальная конфигурация позволяет использовать анимации без подключения к интернету. Это достигается за счёт хранения:

  • библиотеки JavaScript
  • JSON-анимаций
  • HTML-структуры

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

Оглавление