Порты хоста и намерения

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

Динамический составной компонент

Составной компонент, который работает с данными приложения (показывает записи, сохраняет настройки, просит выполнить действия), называется динамическим. Он соответствует стандарту simai.dynamic-composite-component.

Правила:

• Намерение, а не правка. Компонент сообщает, что попросил человек и каких записей это касается. Решение принимает и проверяет приложение.
• В намерении нет транспорта: ни адреса, ни запроса, ни токена.
• Каждое изменение несёт ревизию, которую браузер видел последней. Приложение сравнивает её и на конфликт отвечает текущей ревизией.
• Конфликт сохраняет черновик: несохранённый ввод человека не выбрасывается.
• Групповое изменение — всё или ничего.
• Ответы упорядочены: устаревший ответ отбрасывается.
• Настройки в слоях: значения пакета → общие → личные. Сброс — это запись, а не удаление.
• Адреса в свойствах — относительные пути; принятый путь сам по себе не даёт доступа.

Порт хоста

Порт хоста — объявленный и отдельно версионированный стык между компонентом и приложением (стандарт simai.composite-host-port). Порт описывает закрытыми схемами, какие данные компонент принимает, какие намерения поднимает и какие настройки хранит.

Правила:

• Ключ, которого нет в порте, отклоняется обеими сторонами. Поэтому порт объявляет каждый ключ, который компонент читает.
• Права приходят вместе с данными: по каждой записи и возможности.
• Ответ повторяет запрос, на который отвечает: фильтры, поиск, сортировку, окно.
• Порт описывает и сам ответ: конверт (answer) и данные ответа на каждое намерение (answer_data). Конверт у портов разный: представление данных кладёт данные в поле data рядом с answer, reason и message, представление свойств — прямо рядом с answer (record, revision, view, errors).
• Что компонент предлагает человеку, решают возможности, которые приложение объявило в capabilities: необъявленную возможность компонент не показывает.
• Младшая версия порта только добавляет; удаление и переименование — новая старшая версия.
• С каждой версией порта издаётся набор проверок. Приложение заявляет поддержку только после его прохождения.

Изданы три порта: порт представления данных (simai.dataview-port), порт представления свойств (simai.property-view-port) и порт навигации администратора (simai.admin-navigation-port). Они входят во Framework: каждая версия порта лежит в поставке ui в distr/core/contracts/ports/<порт>/<версия>/, текущие версии — в карте стандартов (см. Уровни стандартов). Через эти порты работают составные Smart-компоненты продуктов (см. Пакеты компонентов продуктов); сторону хоста реализует приложение.

Как компонент получает порт

Компонент, которому нужен порт, просит его событием sf-host-port-request. Пример показывает обработчик хоста:

document.addEventListener('sf-host-port-request', (event) => {
  const { component, context } = event.detail; // context: {owner, record, group}
  event.target.setHostPort(createPortFor(component, context));
});

Что важно заметить:

• запрос всплывает и отправляется один раз за подключение, пока порта нет;
• owner называет составной компонент, который встроил этот элемент; для списка на странице все три поля — null;
• хост отвечает сразу или позже вызовом setHostPort(port);
• элемент, перемещённый в DOM, спрашивает снова.

Порт хоста — это адаптер данных. Его не путают с портами маршрутизации композиции (sf-port-output), по которым между компонентами идут типизированные значения.

Дополнительные правила порта

• Возможность порта называет только данные, которые добавляет порт.
• Право, которое отличается у разных людей, приходит в ответе, а не в возможности.
• Правило, которым владеет хост, приходит по каждой записи (например, hiddenBy называет слой, который скрыл поле), а не повторяется в компоненте.
• Компонент не пишет в объект, которым ответил хост, — копирует его.
• Записи с ревизией отправляются последовательно: две быстрые правки против одной ревизии превращают вторую в конфликт.

Смотрите также

• Граница ответственности — граница ответственности.
• Составные компоненты — составные компоненты.
• Разделы манифеста — раздел contracts манифеста.
• Проверки — проверки порта.