Файлы и маппинги

#Overview

Эта страница — справочник по трём типам файлов Database.

#Редактор маппинга

Редактор маппинга: поля Key Expression, Target Layer и Fill, привязка к компоненту, Auto-hide unused и секция Auto-fill.

• Add dataset file в тулбаре дерева добавляет строку в дерево: введите имя файла с расширением .json или .csv и нажмите Enter, файл откроется в редакторе. Файл появляется в выбранной папке, папки создаются кнопкой Add folder в том же тулбаре. New mapping работает так же, имя получает .map.json.
• В редакторе маппинга каждое поле — строка с тремя колонками: Key Expression (ключ данных, например [title] или [first] + [last]), Target Layer (имя слоя, кнопка пипетки берёт его из выделения в Figma) и Fill с порядком строк A-Z, Z-A или Rand.
• Над полями выбирается распределение строк между инстансами: Same per instance, Sequential (global) или Random.
• Bind Selected привязывает маппинг к выделенному компоненту, надпись Bound to: показывает его имя, Unbind component снимает привязку. Привязка включает проверку шаблона в Generate и переключатель Auto-hide unused.
• Секция Auto-fill подбирает поля по ключам набора данных: выберите Data file…, при необходимости целевой слой и нажмите Generate.
• Изменения сохраняются кнопкой Save.

Новый файл данных создаётся прямо в дереве: имя с расширением и Enter.

#Форматы dataset

Database поддерживает два формата dataset:

• JSON
• CSV

Dataset может быть локальным или синхронизированным из Git.

Набор данных CSV в режиме Table: строки редактируются в ячейках, колонки добавляются кнопкой +, переключатель Code / Table показывает тот же файл текстом.

В редакторе набора данных: Code показывает файл текстом, Table — таблицей с поиском по строкам, кнопками Paste для вставки таблицы из буфера обмена, Copy all и Add Row. Заголовок колонки переименовывается двойным щелчком, порядок колонок меняется перетаскиванием. Изменения сохраняются кнопкой Save.

JSON

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

• массив объектов (рекомендуется),
• одиночный объект (в apply/generate обрабатывается как датасет из одной строки).

Пример:

[
  {
    "title": "Nike Air Max",
    "price": 129.9,
    "badge": true,
    "user": { "name": "Anna" }
  }
]

Правила резолва JSON-значений

Когда маппинг вычисляет [path]:

1. сначала проверяется прямой ключ (важно для плоских ключей типа sport.name-ru),
2. затем используется dot-path (user.name),
3. если в промежуточной точке массив и индекс не задан, берётся первый элемент.

Если в текст нужно подставить объект, плагин использует приоритет:

ru → en → default → value → text → title → name → fallback в JSON-строку.

CSV

CSV парсится как заголовок + строки данных.

Правила парсера SXL Studio:

• строка 1 — заголовки;
• минимум для непустого результата: 2 строки (заголовок + хотя бы одна строка данных), иначе результат пустой;
• поддерживаются экранированные кавычки ("");
• поддерживаются запятые/переносы внутри quoted-значений;
• дубли заголовков переименовываются в name, name_2, name_3, ...

Преобразование типов:

• числовые строки конвертируются в числа;
• строки с ведущими нулями (например, 001) остаются строками;
• пустые строки остаются пустыми строками;
• CSV-значения не приводятся автоматически к boolean самим CSV-парсером.

Режимы редактора CSV

Для CSV в UI доступны:

• режим Code: редактирование сырого CSV,
• режим Table: табличный редактор.

В режиме Table доступны:

• переименование колонок,
• добавление/удаление/дублирование строк,
• добавление колонок,
• drag-and-drop перестановка колонок,
• сортировка по одной колонке,
• search-фильтр,
• copy/copy all,
• вставка CSV из буфера (новые колонки добавляются автоматически),
• при сохранении удаляются пустые строки/колонки.

#Assets

Поддерживаемые форматы загрузки:

• PNG, JPG/JPEG, GIF, WebP, SVG.

При загрузке WebP/SVG конвертируются в PNG для локального хранения asset.

Значение для картинки в маппинге может быть:

• https://... URL,
• data:image/... URL,
• local-asset://<assetId>,
• имя/путь локального asset,
• путь к файлу в Git.

HTTP-URL отклоняется логикой загрузки изображений. Используйте только HTTPS.

#Схема mapping JSON (.map.json)

Mapping-файл хранится в JSON с $type: "maps".

Ключи верхнего уровня

Ключи FieldConfig

#Справочник Key Expression

Базовый синтаксис

• Ключ в скобках: [title]
• Dot-path: [user.name]
• Несколько ключей: [first] [last]
• Ключ без скобок тоже поддерживается и трактуется как [key]

Конкатенация с +

[a] + [b] обрабатывается как прямая склейка плейсхолдеров.

Модификатор удаления

Используется - (пробел-дефис-пробел):

• [status] - prefix_ → удаляет prefix_
• [code] - *- → удаляет всё до последнего -

Встроенные плейсхолдеры в значениях dataset

После основного вычисления выражения плагин дополнительно раскрывает встроенные [path] внутри итоговой строки, если path существует в этой же строке данных.

Пример:

• значение в dataset: "Total [fts] (NP)"
• fts = 7.5
• результат: "Total 7.5 (NP)"

#Совпадение Target Layer

Узел считается target, если с layerName из mapping совпало:

• name узла,
• или characters у TEXT-узла.

Нормализация при сравнении:

• trim по краям,
• замена NBSP на обычный пробел.

Сравнение остаётся регистрозависимым.

#Приоритет выбора dataset

Для каждого поля dataset выбирается в таком порядке:

1. field.datasetId
2. mapping.datasetId
3. автоопределение по ключам выражения на первой строке dataset
   • сначала ищется полное совпадение,
   • затем частичное.

#Fill-поведение

fillStrategy (уровень поля) — в редакторе колонка Fill

• asc: прямой порядок, в редакторе A-Z,
• desc: обратный порядок, Z-A,
• random: случайная строка, Rand.

groupFillMode (уровень группы) — в редакторе переключатель над полями

• same: свой счётчик строк в каждом контейнере, Same per instance,
• global: общий счётчик для всех контейнеров, Sequential (global),
• random: случайная строка при каждом применении группы, Random.

#Справочник директив

Директивы — это строковые значения в ячейках dataset.

@prop: (свойства компонента)

Синтаксис:

@prop:Property=value
@prop:Visible=true;Label=New

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

• несколько свойств через ;,
• \; поддерживается как экранированная ;,
• применяется только к инстансам компонентов.

@node: / @hide / @show

Поддерживаемые node-директивы:

• @hide → visible=false
• @show → visible=true
• @node:visible=true|false
• @node:opacity=0..1
• @node:locked=true|false

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

• node-директивы можно объединять через ;,
• для текстовых целей директивы видимости обычно применяются к родительскому контейнеру.

@rows: и $visibleRows / $rows

• @rows:3 оставляет видимыми первые 3 дочерних узла и скрывает остальные.
• Также поддерживаются числовые значения из выражений с $visibleRows или $rows.

Примечание: для native SLOT-узлов этот механизм не применяется.

Обычные boolean-значения для INSTANCE

Если значение boolean-подобное (true/false/1/0/yes/no/on/off) и target — INSTANCE, плагин устанавливает первое BOOLEAN component property в этом инстансе.

#Пример mapping-файла

{
  "$type": "maps",
  "id": "map_cards",
  "name": "cards.map.json",
  "createdAt": "2026-05-27T10:00:00.000Z",
  "updatedAt": "2026-05-27T10:05:00.000Z",
  "datasetId": "ds_products",
  "targetComponentKey": "2b8b2...",
  "targetComponentName": "WProductCard",
  "autoHideUnused": true,
  "fields": [
    {
      "id": "f_title",
      "jsonPath": "[title]",
      "layerName": "product-title",
      "fillStrategy": "asc",
      "group": "card/content",
      "groupFillMode": "same"
    },
    {
      "id": "f_badge",
      "jsonPath": "@prop:Visible=[badge]",
      "layerName": "badge",
      "fillStrategy": "asc"
    }
  ]
}

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

• Операции и runtime-поведение: Apply и Generate
• Общий workflow Database: Обзор Database