Appearance
Контракт данных представлений
Данные хранятся одновременно в двух формах. preset — живая конфигурация: фильтры, обе оси и вид по умолчанию. groups, columns и items — зафиксированный результат генерации, который правят вручную. source выбирает, что показывать: сохранённые элементы или превью из пресета, а layout — список или таблицу; смена layout ничего не переносит.
Контракт общий для builder и портала — сохранённое представление открывается одинаково в обоих приложениях.
Структура представления
ts
/**
* Объект прав доступа для компонента-фасада LibMenuFolderView.
* Определяет, какие интерактивные действия разрешены в представлении.
*/
export interface MenuFolderViewPermissions {
/** Разрешить приём внешнего перетаскивания (D&D из дерева). */
canDropExternal?: boolean;
/** Разрешить ручную перестановку строк (осей). */
canReorderRows?: boolean;
/** Разрешить ручную перестановку столбцов (осей). */
canReorderColumns?: boolean;
/** Режим только для чтения: скрывает элементы управления и блокирует правки. */
readonly?: boolean;
}
/**
* @description Текущая версия схемы `MenuFolderView`. Любое несовместимое
* изменение структуры требует увеличения значения и шага в `migrateMenuFolderView`.
*/
export const MENU_FOLDER_VIEW_VERSION = 1;
export interface MenuFolderView extends MenuFolderViewStructure {
/** Версия схемы; свежесозданные представления получают текущую. */
version: typeof MENU_FOLDER_VIEW_VERSION;
/** Раскладка: `list` или `table`. Структуру не меняет. */
layout: MenuFolderViewDisplayMode;
/** Что показывать: сохранённые `items` или превью из `preset`. */
source: MenuFolderViewSource;
/** Live-конфигурация: фильтры, обе оси и вид по умолчанию. */
preset: TableViewPreset;
}Preset: живая конфигурация
preset — живая конфигурация представления. Описывает, из каких объектов и каких полей собирать таблицу. Состоит из двух одинаковых по структуре осей rows/columns и вида ячейки по умолчанию.
Каждая ось — это набор "признаков" объекта. Для каждой оси через фильтр отбираются объекты. Таблица строится на пересечении "признаков". Объекты, полученные после фильтрации имеют множество "признаков". valuePath - путь до "признака" объекта. При наличии этого поля ось таблицы принимает все возможные значения этого "признака". Есть возомжность использовать для построения осей только их уникальные значения. Если у объекта одновременно встречается оба "признака" - строковый и столцевой, то этот объект отображается на пересечении строки и столбца. Если таких объектов несколько, в пересечение попадает первый из тех, что прошли оба фильтра.
ts
export interface TableViewAxisPreset {
/** Пресет {@link_doc object-filter}: отбирает объекты, участвующие в оси. */
filter: TableViewObjectFilterPreset;
/** Путь к полю объекта, значение которого становится ключом и подписью элемента оси (например `name`, `objectType`). */
valuePath: string;
/** Если `true` — одинаковые значения по `valuePath` схлопываются в один элемент оси; `false` оставляет каждое значение отдельным элементом. */
unique: boolean;
/**
* @description
* Словарь ручных подписей для значений оси. Ключом остаётся исходное
* значение, полученное по `valuePath`, потому что именно оно участвует в
* поиске пересечений таблицы и в повторной генерации. Значение
* словаря влияет только на отображаемый label строки, столбца или элемента
* списка.
*/
labelOverrides: Record<string, string>;
}
export interface TableViewPreset {
/** Конфигурация оси строк: фильтр, путь значения и подписи. */
rows: TableViewAxisPreset;
/** Конфигурация оси столбцов: фильтр, путь значения и подписи. В режиме `list` скрывается, но сохраняется. */
columns: TableViewAxisPreset;
/** Вид по умолчанию: получают новые элементы, добавленные в свободное место, и генерация. */
defaultCellView: TableViewCellView;
}Элементы: группы, столбцы и объекты на своих местах
Представление хранит оси и элементы. groups — строки таблицы и группы карточек списка, columns — столбцы, items — объекты на своих местах: у элемента есть группа (или «без группы»), столбец, рендерер и, при необходимости, выбранная визуализация объекта. Идентификаторы непрозрачны: их нельзя разбирать, различаются только равенством.
ts
/** Ось таблицы: строка — это группа. */
export type TableViewAxis = "row" | "column";
export interface TableViewAxisItem {
/** Стабильный идентификатор элемента оси; элементы ссылаются на него. */
id: string;
/** Исходное значение по `valuePath` пресета оси; у созданных вручную отсутствует. */
value?: string;
/** Отображаемый текст — значение, ручная подпись из `labelOverrides` или введённое имя. */
label: string;
}
export interface MenuFolderViewItem {
/** Идентификатор элемента; не связан с объектом, поэтому один объект может быть в нескольких элементах. */
id: string;
/** id объекта портала. */
objectId: string;
/** id выбранной визуализации объекта; `null` — основная. */
displayId: string | null;
/** Рендерер, которым рисуется элемент. */
rendererId: TableViewCellRendererId;
/** id группы; `null` — «без группы». */
groupId: string | null;
/** id столбца; `null` встречается только в чужих данных. */
columnId: string | null;
}
export interface MenuFolderViewStructure {
/** Группы списка и строки таблицы, в порядке отображения. «Без группы» сюда не входит. */
groups: TableViewAxisItem[];
/** Столбцы таблицы; в списке у каждой карточки свой. */
columns: TableViewAxisItem[];
/** Объекты на своих местах, в порядке карточек. */
items: MenuFolderViewItem[];
}
/** Место элемента: группа, столбец (`null` в списке) и карточка, перед которой он встаёт. */
export interface FolderViewPlace {
groupId: string | null;
columnId: string | null;
beforeItemId: string | null;
}Формат 0: прежнее представление со snapshot
Формат 0 — прежнее представление со snapshot. Библиотека читает его только для миграции в текущий формат; новые данные в нём не записываются.
ts
export interface TableViewCell {
/** id строки, на пересечении которой стоит ячейка. */
rowId: string;
/** id столбца, на пересечении которого стоит ячейка. */
columnId: string;
/** id объекта портала в ячейке или `null`, если ячейка пуста. */
objectId: string | null;
/** Сохранённый вид ячейки (рендерер); если не задан — берётся `defaultCellView`. */
view?: TableViewCellView;
}
export interface TableViewSnapshot {
/** Зафиксированные строки оси на момент генерации. */
rows: TableViewAxisItem[];
/** Зафиксированные столбцы оси на момент генерации. */
columns: TableViewAxisItem[];
/** Зафиксированные ячейки — пересечения строк и столбцов. */
cells: TableViewCell[];
/** ISO-метка времени генерации. */
generatedAt: string;
}
export interface MenuFolderTableView {
version: number;
preset: TableViewPreset;
snapshot: TableViewSnapshot | null;
displaySource: "preset" | "snapshot";
displayMode: MenuFolderViewDisplayMode;
}Перенос формата 0 в текущий
Приводит сохранённое представление к текущему формату. Чистая и полная функция: не бросает на любом JSON-объекте, не меняет вход, равные данные дают равный результат вместе с идентификаторами. Представление текущей версии возвращается той же ссылкой. Остальное читается как формат 0: раскладка не влияет на результат, ни одна ячейка с объектом не теряется, повторные ячейки одного пересечения получают собственные столбцы. Неподдерживаемую версию (isSupportedMenuFolderViewVersion) хост отклоняет до вызова.