Коллекции

#Что это

Collections показывает файлы модов одной коллекции токенов рядом друг с другом в виде матрицы.

Строка — это один путь токена. Колонка — это один мод. Ячейка содержит значение, которое этот мод задаёт для этого пути.

Из этого представления можно:

• сравнить все моды коллекции с одного экрана;
• отредактировать значение на месте — в одной ячейке или сразу во всём выделении;
• создавать, дублировать, переименовывать и удалять токены и группы в тех модах, которым они принадлежат.

Любая запись проходит через предпросмотр. Отмены (undo) в этом представлении нет — вас защищают предпросмотр, проверка готовности к применению и транзакционный откат. Чтобы восстановить состояние после применённой записи, используйте Git Sync.

#Как открыть

Во вкладке Tokens откройте секцию Collections в левой панели. В ней перечислены все коллекции, объявленные в config.json, с названием, количеством модов и бейджем off, если коллекция отключена.

Нажмите на коллекцию, чтобы открыть её матрицу. Список — это дерево с одной точкой табуляции, поэтому по нему можно перемещаться стрелками и активировать сфокусированную коллекцию с клавиатуры.

Если коллекций нет, панель показывает No collections yet — add them in Collection Settings (config.json).

Если в поле поиска боковой панели был текст в момент открытия коллекции, матрица сразу переходит к первому совпавшему пути токена во включённом файле этой коллекции: группы-предки раскрываются, а строка получает фокус. При пустом поле поиска матрица открывается сверху.

Если коллекция перестаёт быть объявленной в config.json, пока представление открыто, матрица заменяется сообщением об этом.

#Шапка и панель инструментов

В шапке — название коллекции, подпись вида 3 modes · 412 paths, кнопка закрытия и кнопка +, добавляющая токен в коллекцию. Если коллекция отключена, кнопка + неактивна, а её подсказка гласит This collection is disabled and read-only.

На панели инструментов:

• Search token path — поиск только по пути токена, тем же нечётким матчером, что и в дереве токенов. Значения не участвуют в поиске.
• Only differing — оставляет строки, в которых моды расходятся в исходном значении или токен отсутствует хотя бы в одном моде.
• счётчик выделения вида 12 cells in 3 modes, скрытый при 0 или 1 выделенной ячейке;
• счётчик строк вида 41 of 412 при активном фильтре или 412 rows, когда фильтра нет;
• строка статуса. По умолчанию в ней написано Click a cell — or press Enter — to edit it. Shift-click selects a range; ⌘/Ctrl-click toggles cells. Если действие заблокировано, на шесть секунд её заменяет причина отказа, а отклонённая ячейка подсвечивается.

#Как читать матрицу

#Колонки — это моды

На каждый мод, объявленный коллекцией, приходится одна колонка, в порядке из config.json, плюс закреплённая слева колонка Token path и колонка Values справа.

В колонку попадают только файлы, помеченные модом как enabled. Файлы с пометкой source намеренно исключены: они участвуют в разрешении алиасов, но не являются целями записи и не могут быть изменены из этого представления.

Мод может включать несколько файлов. Тогда в заголовке появляется числовой бейдж с их количеством, а подсказка перечисляет полные пути файлов. Если геометрию доказать не удалось, подсказка называет конкретную проблему — ambiguous config: …, missing file: …, invalid token JSON: … или no enabled file. Отключённый мод помечен бейджем off.

Значения внутри одного мода с несколькими файлами склеиваются по правилу «побеждает последний».

Нажмите на имя мода, чтобы открыть его файл токенов в обычном редакторе. Если включённых файлов несколько, открывается первый файл колонки; подсказка называет его.

Ширину колонок можно менять перетаскиванием. Она хранится для каждой коллекции и привязана к имени мода.

Колонка Values показывает 2 values для строки и приглушается, когда в строке одно различное значение или меньше. Правый клик по ней открывает меню строки.

#Строки — это пути токенов

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

Пути разделяются слэшем. Точка внутри ключа разделителем не является: spacing/0.5 — это один сегмент, а не два.

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

#Ячейки

Ячейка показывает исходное значение $value дословно. Алиасы показываются, а не вычисляются: {brand.primary} остаётся {brand.primary}. Строки выводятся как есть, числа и булевы значения приводятся к строке, объекты и массивы показываются как JSON, а текст обрезается на 120 символах.

Цветовой образец рисуется для литерального цвета — #rgb, #rrggbb, #rrggbbaa, rgb(), rgba(), hsl(), hsla(). Для алиаса, у которого эффективный тип — цвет, образец является превью, вычисляемым по колонке.

Ячейка мода, который не задаёт этот путь, — пропуск. Она рисуется как —. Это состояние UI: оно никогда не записывается в JSON.

Редактируемые ячейки получают текстовый курсор, подсветку при наведении и небольшую кнопку-ссылку. Нередактируемые ячейки заблокированы, и их доступное описание называет точную причину.

#Заголовки групп

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

Заголовок группы занимает колонку пути и идёт сплошной полосой по треку модов. У группы нет значения на мод, поэтому у неё нет ячеек.

Состояние свёрнутости хранится для каждой коллекции и переживает перезагрузку. Сворачивание группы не меняет счётчик строк: он отражает фильтр, а не свёрнутость.

#Редактирование значения

Нажмите на ячейку, чтобы выделить её и открыть редактор. С клавиатуры переведите фокус на ячейку и нажмите Enter или F2 — либо просто начните печатать: печатный символ открывает редактор с этим символом и заменяет значение, как в таблице.

Все виды ячеек используют одно и то же простое текстовое поле. Литералы, алиасы, forward-ссылки и математика вводятся в него.

#Что можно вводить

Текст разбирается по эффективному $type целевой ячейки — собственному или унаследованному от группы. Тип никогда не угадывается по текущему $value.

Значение без единицы в числовой ячейке записывается как число JSON. Всё остальное записывается строкой.

Пустое значение для нестрокового типа отклоняется с сообщением Value cannot be empty. Фигурные скобки, не образующие корректную ссылку, отклоняются с сообщением Value contains braces but no syntactically valid token reference.

#Алиасы и подсказки

Список подсказок открывается, когда каретка находится внутри незакрытого {…}. Нет скобки — нет списка, поэтому ввод обычного числа или цвета ничем не перекрывается.

К одному и тому же списку ведут три пути: ввести {, нажать ⌘/Ctrl + K или нажать кнопку-ссылку в ячейке.

Список состоит из двух уровней. Сначала — пути, которые задаёт эта коллекция, с бейджем this collection. Затем — все пути рабочей области. Совпадение нечёткое и только по пути, поэтому bg al prim находит bg.alert.primary. В каждой строке есть иконка типа или образец цвета, путь и превью значения.

Кандидаты, тип которых несовместим с целевым, отфильтровываются. Кандидаты с неизвестным типом остаются в списке как forward-ссылки. Список ограничен 50 позициями.

↓ и ↑ двигают подсветку, Enter и Tab принимают, Escape закрывает список и сохраняет набранный текст. При принятии путь вставляется, а каретка ставится после закрывающей скобки, что само по себе закрывает список.

Ссылка, целевой тип которой известен и несовместим, отклоняется жёстко. Ссылка, цель которой не удалось разрешить, принимается с предупреждением: forward-ссылка остаётся ровно в том виде, в каком вы её ввели, на редакторе появляется маркер !, и предупреждение повторяется в предпросмотре.

#Подтверждение записи

Прямо из таблицы ничего не записывается. Любая операция — включая правку значения одной ячейки — проходит одну и ту же транзакцию: план, разбор, применение. Предпросмотр только читает и возвращает состояние «до» и «после» для каждого файла, который был бы изменён.

Поверхностей подтверждения две:

• Компактная встроенная полоса. Используется, когда запись затрагивает не более 4 файлов и все выделенные ячейки видны на экране. В ней написано Write <value> to N cells in …, перечислены файлы и указано, сколько файлов будет записано и сколько останется без изменений. Фокус переходит на основную кнопку сразу, как только готов предпросмотр, поэтому весь жест — это ввод, Enter, Enter. Escape отменяет.
• Полный диалог разбора. Используется для всего, что крупнее или находится за пределами экрана. Он перечисляет все файлы в области операции со статусом и сообщением, показывает пофайловые диффы «до/после», счётчики, предупреждения и отчёт по ссылкам, а все блокеры собирает под заголовком Apply is off until this is resolved.

Обе поверхности запускают одну и ту же транзакцию. Разница в подаче, а не в безопасности.

Если вы вышли из одной ячейки, ничего в ней не изменив, это навигация, а не операция: ничего не записывается и предпросмотр не открывается. Если выделено две ячейки или больше, неизменённое значение всё равно проходит предпросмотр — возможно, вы намеренно распространяете его.

#Всё или ничего

Если редактируемая ячейка входит в текущее выделение ячеек, значение записывается во все выделенные ячейки одной транзакцией. Иначе записывается только эта ячейка.

Всё выделение отклоняется — до того, как что-либо покинет представление, — когда:

• у ячейки нет доказанного точного целевого файла;
• две выделенные ячейки указывают на один и тот же файл и путь;
• значение не разбирается по типу хотя бы одной ячейки;
• тип строки для пропуска не удаётся разрешить;
• ни одна выделенная ячейка не пригодна для записи.

Каждое из этих сообщений заканчивается словами Nothing was written. То же правило действует и в основном потоке плагина: точная запись блокируется на невалидных, конфликтующих и отсутствующих строках, а не применяет часть пакета.

#Запись в отсутствующую ячейку

Значение можно ввести и в ячейку —. Это разрешено только тогда, когда у строки есть один однозначный эффективный $type, общий для всех существующих ячеек в ней. Строка без заданного типа или с разными типами по модам отклоняется.

Если у мода один включённый файл, назначение определяется автоматически.

Если мод включает несколько файлов, у пути, которого ещё нет, нет происхождения, поэтому открывается диалог Choose files for missing cells с одной строкой на пару «путь + мод». Выберите включённый файл по полному пути или Skip this destination. Соседние пути, $type и имена файлов не считаются доказательством принадлежности. Значение проверяется до открытия диалога.

Skip — это только состояние операции: он не создаёт ни токен, ни маркер, ни специальное значение в JSON. Если пропустить все пропуски, ничего не изменится.

#Пока вы редактируете

Черновик закрывается, а не даёт записать то, чего вы уже не видите:

• если файл, на котором открыт редактор, изменился под ним — … changed while you were editing. Press Escape and open the cell again.;
• если мод переехал или был переименован — откройте ячейку в её текущем моде до записи;
• если редактируемая строка ушла под фильтр или в свёрнутую группу;
• если черновик палитры цвета больше не соответствует файлу, моду или владельцу.

#Выделение ячеек, строк и колонок

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

⌘/Ctrl + A выделяет все ячейки всех видимых строк. Строки, скрытые фильтром, и строки внутри свёрнутых групп намеренно не попадают в выделение.

Жеста, выделяющего всю колонку мода одним кликом, нет. Выделите верхнюю ячейку мода и сделайте Shift-клик по его нижней ячейке.

В редактируемой цветовой ячейке образец является кнопкой. Она открывает палитру для этой ячейки, и Apply идёт по тому же пути записи, что и введённое значение: при двенадцати выделенных ячейках один выбранный цвет записывается во все двенадцать одной операцией.

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

#Массовые операции

Операции живут в трёх контекстных меню: ячейка имени токена (операции над строкой), ячейка значения (операции над ячейками) и заголовок группы (операции над группой). Каждое меню открывается строкой-заголовком, называющей радиус поражения — сколько строк и сколько точных файлов-владельцев затронуто, — либо Blocked — и причину, по которой не удалось определить маршрут.

#Создание токена

Используйте Add token… в меню строки или кнопку + в шапке.

Сначала вы выбираете тип токена, затем заполняете стандартный редактор токена: путь, значение, описание и extensions.

Введённый путь нормализуется — и ., и / превращаются в /. Он отклоняется, если пуст, если сегмент начинается с $, если сегмент содержит { или }, если по этому пути уже есть токен, если этот путь уже занят группой или если он вложен бы внутрь существующего токена.

Каждый мод получает одну цель. Мод с одним файлом маршрутизируется автоматически. Мод с несколькими файлами открывает диалог Choose exact token files с одной строкой на мод: включённый файл или Skip. Отключённый мод принимает только Skip. Мод, в котором путь уже есть, тоже принимает только Skip. Мод с недоказанной геометрией файлов предлагает только Skip.

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

Один случай пропустить нельзя: отключённый мод, который делит исходный файл с выбранным включённым назначением. Создание токена там изменило бы и отключённый мод, поэтому операция называет общие файлы и останавливается.

#Дублирование токена

Duplicate as… запрашивает целевой путь. Источник показан только для чтения, ровно в исходном виде. По умолчанию предлагается первый свободный <источник>-copy, <источник>-copy-2 и так далее.

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

Каждый файл дублирует собственное поддерево. Каждый файл мода копирует то, что он хранит по исходному пути, в новый путь, поэтому ни одна тема не получает значений другой темы. Копия — это новый токен: структурные id сбрасываются, а разрешённый $type переносится.

Отключённые моды с отдельными файлами пропускаются, и диалог называет их. Если отключённый мод наблюдает выбранный для записи файл — как enabled или как используемый только для разрешения source — операция останавливается до предпросмотра и записи. Так изменение через включённый мод не сможет незаметно изменить отключённый.

Алиасы не переписываются. Дубликат создаёт новый путь, на который до этого никто не ссылался.

#Переименование токена

Точек входа две: клик по имени токена в ячейке пути для inline-переименования и Edit token fields…, где переименование совмещено с метаданными.

Каждый физический владелец пути во всех включённых модах должен быть доказан, иначе переименование блокируется. Отключённый мод, который задаёт или наблюдает один из затрагиваемых файлов, блокирует переименование: включите этот мод, разделите общий файл или отредактируйте его напрямую.

Ссылки переписываются по умолчанию — по всей рабочей области, в файлах токенов и в композициях, включая файлы за пределами этой коллекции. Полнота переписывания доказывается до применения:

• если граф ссылок знает файл со ссылкой, которую план не покрывает, переименование отклоняется и просит пересчитать предпросмотр;
• если сам граф не может прочитать часть файлов, переименование падает в отказ, а не сообщает «ссылок не найдено».

Флажок Update every reference to this token в диалоговой форме можно снять. Тогда ссылки останутся указывать на путь, которого больше нет, и план получит явное предупреждение с числом таких ссылок и файлов.

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

При полностью успешном применении и только для файлов, которые доказанно держали токен, переименование записывает намерение «старый путь → новый путь». Следующий экспорт переименует существующую Figma-переменную на месте, а не удалит и создаст заново, поэтому привязки сохранятся. Отклонённое или откаченное переименование не записывает ничего.

#Удаление токенов

Delete token… — или Delete N selected tokens… — единственная операция над несколькими строками и единственная разрушительная. Каждая выделенная строка должна успешно определить маршрут до открытия плана; один неоднозначный владелец блокирует все строки.

Отдельной формы нет. Диалог открывается на сообщении Checking what still references these tokens before anything is deleted, основная кнопка отключена, а Cancel намеренно остаётся активной.

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

Ничего не перенаправляется автоматически при удалении, и варианта «удалить всё равно» нет.

#Удаление ячеек в выбранных модах

Remove this cell… — или Remove N existing cells… — удаляет токен только из конкретных файлов модов и оставляет его в остальных.

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

Эта операция всегда несёт постоянное предупреждение: неполная строка mode остаётся валидным JSON. Export Variables завершается за один запуск, сообщает о пропусках, сохраняет существующие значения Figma и оставляет созданные Figma значения для новых назначений.

Действует тот же отказ по графу ссылок, что и при удалении.

#Операции над группами

Правый клик по заголовку группы даёт Rename group…, Duplicate group as… и Delete group….

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

Rename group сохраняет id вложенных токенов, типы, описания, extensions и пользовательские данные и обновляет ссылки на потомков, поэтому следующий экспорт переименует существующие Figma-переменные, а не заменит их. Duplicate group заставляет каждый файл продублировать собственное поддерево группы, поэтому каждый вложенный токен сохраняет значение и метаданные именно этого файла.

Заголовок обрабатывается только тогда, когда он соответствует реальной raw-группе JSON. Две формы отклоняются вместо угадывания, и обе описаны в следующем разделе.

#Метаданные

Edit token fields… открывает диалог метаданных строки: имя и путь, описание, собственный $type токена — включая Inherit from group (remove own $type) — Figma variable scopes и Code Syntax для Web, iOS и Android. $value намеренно не входит в этот диалог. Поля, различающиеся у файлов-владельцев строки, показываются как Mixed — unchanged и остаются нетронутыми, пока вы их не измените.

Edit metadata… в ячейке значения редактирует описание и цепочку цветовых модификаторов figma.modify для произвольного набора точных ячеек. Смешанные значения не подставляются и остаются нетронутыми, пока вы не начнёте их менять. Редактор цветовых модификаторов появляется только тогда, когда у всех выделенных существующих ячеек эффективный тип — Color.

#Горячие клавиши

Таблица — это одна точка табуляции. Внутри неё активная ячейка перемещается клавишами ниже.

#Навигация по таблице

Работает, когда фокус на самой таблице — не на ручке изменения ширины колонки — и не открыты ни редактор, ни inline-переименование, ни контекстное меню, ни диалог.

Стрелка без Shift заменяет выделение ячеек той ячейкой, на которую переходит, — так вы выходите из большого выделения. Перемещение активной ячейки не снимает выделение строк, поэтому чередование ↓ и Space собирает набор строк.

#Встроенный редактор ячейки

Уход из поля фиксирует ввод. Отклонённая фиксация оставляет редактор открытым.

#Диалог значения

Открывается из меню значения, когда выделена ровно одна ячейка.

Поле диалога не фиксирует ввод при потере фокуса, а кнопка Preview неактивна, пока текст не изменён.

#Inline-переименование имени токена

Уход из поля фиксирует ввод. Все клавиши остаются внутри поля, поэтому ввод нового пути никогда не запускает набор-для-правки в таблице.

#Ручка изменения ширины колонки

Ручка доступна по Tab.

#Что закрывает Escape

Escape всегда закрывает самое внутреннее:

1. список подсказок, сохраняя набранный текст;
2. встроенный редактор, отменяя правку;
3. диалог значения, ничего не записывая;
4. поле inline-переименования;
5. любой массовый диалог, выбор файлов или диалог метаданных, ничего не записывая;
6. компактную полосу подтверждения, отменяя запись;
7. контекстное меню;
8. выделение строк и ячеек, когда больше ничего не открыто.

Если ничего не открыто и ничего не выделено, Escape не делает ничего.

#Что Collections отказывается делать и почему

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

Apply включается только тогда, когда нет отказа движка, план не устарел, ни одна строка не является отсутствующей, конфликтующей, невалидной или устаревшей, сводка совпадает со списком строк и хотя бы одна строка готова. Все блокеры перечислены под заголовком Apply is off until this is resolved.

Если запись падает на середине, весь пакет выполняется под одной блокировкой документа, каждый целевой файл помечается как изменённый для Git до записи первого байта, цикл останавливается на первой ошибке, а файлы восстанавливаются в обратном порядке, и каждое восстановление подтверждается обратным чтением. Вы увидите одно из:

• Bulk edit applied to N file(s);
• Nothing to apply — no file changed.;
• Token files changed since the preview — nothing was written. Preview again.;
• Bulk edit failed — every file was restored, nothing changed.;
• Bulk edit failed and could not be undone — N file(s) may still hold the new content. Reload the plugin and check Git. В этом случае дальнейшие записи в документ из плагина блокируются до перезагрузки плагина.

#Ограничения

• Отмены (undo) нет. Восстановление после применённой записи идёт через Git Sync.
• Значения никогда не вычисляются. Ячейка показывает исходное значение. Цветовые образцы для алиасов — только превью.
• Поиск работает по путям, но не по значениям.
• Появляются только файлы enabled. Файлы с пометкой source здесь не видны и не могут быть записаны из этого представления.
• Заголовок мода открывает первый файл этого мода. Если включённых файлов несколько, бейдж показывает их количество, подсказка перечисляет все, но клик открывает один.
• ⌘/Ctrl + A и Shift-диапазоны покрывают только видимые строки — строки под фильтром и строки внутри свёрнутых групп исключены.
• Счётчик строк не учитывает свёрнутые группы. Он отражает фильтр.
• Файл, который перечисляет одну и ту же группу в двух местах, даёт два заголовка. У обоих один и тот же путь группы, поэтому сворачивание одного сворачивает и другой.
• Точка в ключе не является разделителем. Существующий путь переносится ровно в исходном виде, а введённый вами путь нормализуется. Формы переименования и дублирования показывают нормализованный вид под полем, чтобы это было видно.
• Группу, разложенную по двум concern-файлам одного мода, нельзя переименовать, продублировать или удалить как группу. Сначала соберите её в один файл.
• Отключённый мод с отдельными файлами пропускается. Любая запись блокируется, если отключённый мод наблюдает затрагиваемый физический файл как enabled или source.
• Неразрешённые ссылки допустимы. Опечатка в пути принимается с предупреждением, а не отклоняется.
• Математика работает только с числовыми типами и только когда у ячейки есть эффективный $type или предыдущее числовое значение.
• Подсказки алиасов ограничены 50 позициями, а список путей рабочей области загружается лениво. Первый { за сессию может показать пути коллекции до того, как подгрузится список рабочей области.
• Ширины колонок и состояние свёрнутости привязаны к имени мода, для каждой коллекции. Переименование мода в config.json теряет его ширину; перестановка модов — нет.
• Заданная ширина ограничивается только при построении layout, поэтому колонка, не помещающаяся в узкую панель, временно сужается и возвращается к заданной ширине, когда панель расширяется.
• Обычный клик по ячейке значения и выделяет её, и открывает редактор. Чтобы только выделить, держите ⌘/Ctrl или Shift.
• Обычный клик по имени токена начинает inline-переименование. Клик с модификатором — только выделение.
• Rename и Edit token fields недоступны, когда выделено несколько строк — эти операции несут ровно один путь.
• Удаление ячейки оставляет неполную строку. Это валидный JSON; export Variables завершается за один запуск и сообщает о сохранённом или созданном Figma значении mode.
• Полный цикл через JSON нормализует файл: 1.50 становится 1.5, а числовые ключи переезжают в начало своей группы по возрастанию. Это видно в диффе «до/после», а семантически идентичный файл не записывается вовсе.
• Определённые отступы и завершающий перевод строки сохраняются. У minified-файла нет отступов для сохранения, поэтому первая реальная массовая правка форматирует его двумя пробелами; этот одноразовый diff виден в preview.

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

• Вкладка Tokens: Обзор
• JSON-формат: JSON-формат токенов
• Моды: Переключатель модов
• Экспорт: Экспорт Variables и Styles