Apply и Generate

#Overview

Два способа записать контент датасета в Figma через маппинг:

---

#Apply Data

Apply Data исполняет правила маппинга и записывает значения dataset в совпавшие узлы Figma.

Пайплайн Apply

1. Строится карта полей из всех маппингов (Target Layer -> fields).
2. Собираются target-узлы в выбранном scope.
3. Для каждого поля резолвится dataset (dataset поля -> dataset маппинга -> автоопределение).
4. Считается row index (fill strategy + group fill mode + контекст выделения).
5. Вычисляется expression и применяются директивы/картинки/текст.
6. Выполняются post-pass этапы (если включены):
   • Auto-hide unused
   • Slot repeater
   • Composition templates ({{ ... }})

Scope

selection — самый безопасный режим для быстрых итераций.

Порядок полей, если несколько маппингов пишут в один target

Apply приоритизирует поля так:

1. группа cell/table,
2. группы, начинающиеся с cell/,
3. остальные поля (стабильно по mapping id).

Матрица обработки значений

Auto-hide unused: фактическое поведение

Когда autoHideUnused=true и feature доступна:

• auto-hide запускается в границах конкретного row/container,
• скрываются неиспользованные TEXT-узлы в этой границе,
• узлы-цели маппинга и уже затронутые узлы защищены от скрытия,
• это не логика «скрыть, если значение пустое», а cleanup по mapping-target правилам.

#Generate instance

Generate instance дублирует шаблон и применяет по одной строке dataset на каждую сгенерированную строку.

Preconditions

• Feature Generate должна быть включена.
• Должен быть выбран mapping (в picker попадают .map.json с хотя бы одним полем).
• Dataset для mapping должен содержать строки.
• Выделение должно быть валидным шаблонным контекстом (instance/component или frame/list host).

Количество строк

• All: генерация на все строки dataset.
• Limit: генерация min(limit, datasetRows).

Общий flow генерации

1. Резолвится container + template из текущего выделения.
2. Опционально проверяется Bind component (targetComponentKey).
3. Чистятся предыдущие siblings в container, сохраняется template anchor.
4. Дублируются строки и вставляются по порядку.
5. Выполняется Apply по сгенерированным строкам выбранным mapping.
6. Разворачиваются composition templates ({{...}}) построчно.
7. Сгенерированные узлы выделяются.

Стратегия дублирования

Frame/list host

• строка 1: существующий template,
• строка 2: клон template,
• строка 3+: клон предыдущей вставленной строки.

Slot host

• обычный slot mode: строка 2 от template, строка 3+ от предыдущей строки,
• table-row slot mode: каждая новая строка клонируется от предыдущей.

Такая стратегия нужна для стабильности во вложенных instance-деревьях.

Apply-фаза после Generate

Generate применяет:

• выбранный mapping к сгенерированным строкам,
• composition templates для каждой строки.

Другие mapping-файлы в текущем default-пайплайне автоматически не применяются.

#Известные ограничения Figma (важно)

1) Ghost-строка во вложенных slot/table

Для глубоких структур вида WTable -> rows(SLOT) -> row(INSTANCE) Figma может оставлять одну master-наследованную строку, которую plugin API не может безопасно удалить.

Если cleanup не смог её убрать/скрыть, показывается разовое уведомление и нужна ручная очистка.

2) Порог производительности на глубоко вложенных instance

Запись текста в глубокие instance sublayer может быть очень медленной (сотни миллисекунд на ячейку), особенно в nested-table кейсах.

Для больших dataset по возможности используйте более плоские row-template структуры.

3) Доступность шрифтов

Плагин прогревает шрифты автоматически, но недоступный шрифт всё равно может блокировать обновление текста.

#Практические рекомендации

1. Начинайте с Selection scope для безопасной итерации.
2. Давайте слоям явные и уникальные target-имена.
3. Включайте Bind component для строгой валидации шаблона в Generate.
4. Для больших таблиц делите генерацию на батчи или упрощайте структуру строки.
5. Уведомления про slot/table edge-cases считайте ограничением API, а не только ошибкой маппинга.

#Связанные страницы

• Ключи, директивы, JSON-схемы: Файлы и маппинги
• Общий workflow: Обзор Database