Доступ к свойствам слоев

Модель слоёв в Lottie Web напрямую отражает структуру композиции, созданной в After Effects. При экспорте через Bodymovin каждый слой превращается в объект внутри массива layers, где фиксируются ключевые параметры анимации, трансформации и привязки к ресурсам.

Типовая структура слоя включает:

  • ty — тип слоя (shape, text, image, precomp)
  • nm — имя слоя
  • ind — индекс слоя
  • ks — трансформации (position, scale, rotation, opacity)
  • shapes — векторные контуры (для shape layers)
  • t — текстовая конфигурация
  • refId — ссылка на precomposition или asset

Ключевой момент заключается в том, что Lottie Web не работает напрямую со слоями как с DOM-элементами. После парсинга JSON создаётся внутренняя сцена, которая абстрагирует структуру слоёв в набор рендер-элементов.

Инициализация анимации и точка доступа к дереву слоёв

Доступ к слоям возможен только через экземпляр анимации, возвращаемый lottie.loadAnimation.

import lottie from "lottie-web";

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

После инициализации создаётся объект анимации, внутри которого содержится рендер-дерево. Именно оно отражает структуру слоёв в рабочем виде.

Наиболее важные точки доступа:

  • animation.renderer — активный рендерер (svg/canvas/html)
  • animation.renderer.elements — список внутренних элементов сцены
  • animation.animationData — исходный JSON
  • animation.getDuration() — длительность анимации
  • animation.goToAndStop() / goToAndPlay() — управление временем

Отображение слоёв в рендер-движке

Lottie Web преобразует JSON-слои в набор объектов рендера. В зависимости от выбранного режима (SVG, Canvas, HTML) структура отличается, но логика остаётся общей:

  • каждый слой становится BaseElement
  • трансформации инкапсулируются в TransformManager
  • shape layers превращаются в SVGShapeElement
  • текстовые слои — в TextElement
  • precomposition — в отдельную вложенную сцену

В SVG-режиме каждый слой обычно соответствует группе <g> в DOM, но доступ к ней через стандартный DOM API ограничен, поскольку библиотека управляет обновлениями самостоятельно.

Доступ к элементам слоя через renderer

Наиболее прямой способ получить доступ к слоям — использование внутреннего массива элементов рендера:

const elements = animation.renderer.elements;

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

  • element.data — оригинальный слой из JSON
  • element.layerId — идентификатор слоя
  • element.transform — объект трансформаций
  • element.updateFrame() — обновление состояния

Пример обхода:

elements.forEach(el => {
  console.log(el.data.nm);
});

Этот подход позволяет связать визуальные элементы с исходной структурой After Effects.

Поиск слоя по имени

Имена слоёв (nm) часто используются как основной идентификатор для логики управления. Несмотря на отсутствие официального API поиска, доступ можно реализовать через обход дерева элементов.

function findLayerByName(animation, name) {
  return animation.renderer.elements.find(el => el.data && el.data.nm === name);
}

Такой способ зависит от реализации рендерера, но на практике используется в большинстве проектов с Lottie Web.

Работа с трансформациями слоя

Каждый слой содержит объект трансформаций ks, который в рендер-слое преобразуется в управляемую структуру.

Основные параметры:

  • o — opacity
  • p — position
  • r — rotation
  • s — scale
  • a — anchor point

В рендер-элементе доступ к этим данным осуществляется через transform:

const layer = findLayerByName(animation, "Icon");

layer.transform.opacity = 50;
layer.transform.position[0] += 10;

Изменения могут не всегда применяться напрямую, так как многие значения кешируются и пересчитываются на уровне кадра.

Обновление слоя в runtime

Lottie Web не предоставляет полноценного публичного API для мутации слоёв в реальном времени, однако существует механизм принудительного обновления через перерисовку кадра.

animation.goToAndStop(animation.currentFrame, true);

или

animation.triggerRenderFrame();

(последний метод относится к внутренним API и может отсутствовать в некоторых версиях)

При изменении свойств слоя важно учитывать:

  • необходимость пересчёта матриц трансформации
  • кеширование shape paths
  • особенности SVG-рендеринга

Доступ к shape и path внутри слоя

Shape layers представляют собой дерево объектов:

  • shapes → группы
  • it → элементы (fill, stroke, path)

Внутри рендер-слоя это преобразуется в структуру ShapeElement.

Пример обхода:

const layer = findLayerByName(animation, "Button");

layer.elements.forEach(el => {
  if (el.shapes) {
    console.log(el.shapes);
  }
});

Для более глубокого доступа используется рекурсивный обход:

function traverseShapes(group) {
  group.shapes.forEach(item => {
    if (item.it) traverseShapes(item);
    if (item.ty === "fl") console.log("Fill color", item.c);
  });
}

Доступ к текстовым слоям

Текстовые слои преобразуются в TextElement, который содержит:

  • textData — исходная текстовая конфигурация
  • renderedText — текущая строка
  • transform — позиционирование

Пример получения текста:

const textLayer = findLayerByName(animation, "Title");

console.log(textLayer.textData.d.k[0].s.t);

Изменение текста возможно только через обновление структуры данных:

textLayer.textData.d.k[0].s.t = "New Text";
animation.goToAndStop(animation.currentFrame, true);

Precomposition и вложенные слои

Precomp layers (ty: 0) представляют собой вложенные композиции. Внутри они имеют собственный набор слоёв, который рендерится отдельным деревом.

Доступ:

const precomp = findLayerByName(animation, "Scene 2");

const nestedElements = precomp.layers;

Внутренние слои precomp не всегда доступны напрямую через основной renderer.elements, так как они инкапсулируются в отдельный контекст.

Различия доступа в SVG и Canvas рендерере

Поведение доступа к слоям существенно зависит от рендерера.

SVG renderer

  • создаёт DOM-структуру
  • слои соответствуют <g>, <path>, <text>
  • возможен частичный DOM inspection

Canvas renderer

  • отсутствует DOM
  • вся сцена рисуется в bitmap-контексте
  • доступ возможен только через внутренние объекты

HTML renderer

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

Стабильные и нестабильные API

Lottie Web разделяет доступ к слоям на две категории:

Публичные возможности

  • управление временем (play, pause, setSpeed)
  • события (complete, loopComplete)
  • загрузка и конфигурация

Внутренние структуры

  • renderer.elements
  • transform объектов
  • shapes дерева
  • textData

Использование внутренних структур даёт гибкость, но привязывает код к версии библиотеки.

Практический паттерн управления слоями

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

  1. Назначение уникальных имён слоям в After Effects
  2. Поиск слоя через renderer.elements
  3. Изменение трансформаций или данных
  4. Принудительный рендер кадра

Пример общей схемы:

function setLayerOpacity(animation, name, value) {
  const layer = animation.renderer.elements.find(
    el => el.data && el.data.nm === name
  );

  if (!layer) return;

  layer.transform.opacity = value;
  animation.goToAndStop(animation.currentFrame, true);
}

Особенности кеширования и пересчёта состояния

Lottie активно использует кеширование:

  • path shapes кешируются после первого построения
  • матрицы трансформаций пересчитываются только при изменении
  • текстовые блоки могут переинициализироваться

Из-за этого изменения в слоях могут требовать принудительного обновления кадра или повторного запуска анимации с текущей позиции.

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

Несмотря на наличие внутренних структур, прямое управление слоями ограничено архитектурой библиотеки:

  • отсутствует официальная система поиска слоёв
  • нет стабильного API для изменения структуры композиции
  • некоторые рендереры скрывают элементы полностью

Это приводит к тому, что управление слоями строится через:

  • соглашения об именовании
  • обход рендер-дерева
  • модификацию JSON до загрузки анимации
Оглавление