Skip to content

Контракт данных представлений

Данные хранятся одновременно в двух формах. 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) хост отклоняет до вызова.

Mentioned In ​