Типы значений маршрутов
Значение, которое уходит по маршруту layout.scope из выхода одного
компонента во вход другого, всегда имеет тип из закрытого перечня. У каждого
типа есть схема и проверка. Проверка возвращает неизменяемую копию значения
или отклоняет его с TypeError; приведения одного типа к другому нет.
Маршрут допустим, только когда тип выхода и тип входа совпадают
(иначе — route_type_mismatch).
Имя типа
Имя типа не несёт версии: record-ids, record-removed,
collection-changed. Прежняя метка с версией (record-ids.v1) называет тот
же тип и читается до 2026-12-01 везде, где встречается тип: в манифесте
портов, описании фрагмента, маршруте, static sfPorts и последствиях в ответе
порта. Срок удаления метки записан в журнале изменений
(Журнал изменений,
запись value-types-without-version). Маршрут сравнивает типы по имени без
версии, поэтому выход record-ids питает вход record-ids.v1 и наоборот.
Правила задаёт комплект Composition Routing 1.1.0.
Манифест sf-table и выходы <sf-page-host>, встроенные во Framework,
объявлены прежними метками; маршрут к ним и от них принимает любую из двух
форм. Ключи SF.Composition.VALUE_TYPES — тоже прежние метки.
Общие правила
- Перечень один для кода, схемы манифеста портов
(
distr/core/contracts/composition-port-manifest.v1.schema.json) и схемы описания фрагмента 1.2.0 (distr/core/contracts/interface-fragment.v1.schema.json); обе схемы принимают тип в любой из двух форм. В браузере перечень лежит вSF.Composition.VALUE_TYPES: у каждого типа естьsummary,schemaиcheck(value). - Значение в JSON занимает не больше 64 КиБ; большее отклоняется целиком.
- Значения-объекты закрыты: ключ, которого тип не называет, отклоняется, а не пропускается дальше. Отсутствие обязательного ключа — тоже отказ.
- Идентификатор записи — непустая строка до 256 символов без управляющих символов или целое число в безопасном диапазоне JavaScript. Ревизия — такая же строка до 128 символов или такое же целое число.
- Имя коллекции — непустая строка до 128 символов без управляющих символов.
- Короткое слово-метка (
reason,keyсчётчика) — строчная латинская буква, затем до 127 символов из строчных букв, цифр, точки, подчёркивания, двоеточия и дефиса:created,requests.new.
Значения внутри составного компонента
Эти типы связывают части одного сценария, например выбор строк в одной таблице с контекстом другой.
| Тип | Значение | Отклоняется |
|---|---|---|
record-ids |
упорядоченный список уникальных идентификаторов записей, до 1000; пустой список — «ничего не выбрано» | не массив, больше 1000 элементов, неверный идентификатор, повтор |
record-id |
один идентификатор записи или null — «ничего» |
неверный идентификатор |
text |
простой текст до 2000 символов; никогда не разметка и не язык запросов | не строка, длиннее 2000 |
boolean |
строгое true или false |
любое другое значение, включая 0, 1 и "true" |
Значения страницы
Эти типы ходят между фрагментами интерфейса одной страницы. Каждый
говорит, что и где изменилось, но не несёт сами данные: фрагмент,
получивший record-changed, перечитывает запись через свой порт хоста со
своими правами.
| Тип | Форма значения | Что сообщает |
|---|---|---|
record-changed |
{collection, id, revision, fields?} |
запись коллекции изменилась и получила ревизию revision; fields — необязательный список ключей изменившихся полей, до 256, без повторов |
record-removed |
{collection, id} |
запись удалена из коллекции |
collection-changed |
{collection, reason} |
в коллекции изменилось то, ради чего список стоит перечитать; reason — слово-метка: created, imported, reordered, settings |
files-moved |
{ids, from, to} |
файлы перемещены: ids — от 1 до 1000 уникальных идентификаторов, from и to — папки, null означает корень |
counter |
{key, value} |
изменился именованный счётчик: key — слово-метка (notifications, requests.new), value — целое число от нуля |
navigation |
{url, region} |
перейти по адресу этого же сайта в именованной области: url — путь, region — имя области |
preference-changed |
{key} |
человек изменил настройку вида; key — ключ SF.Preferences (sf-table/<ключ>, sf-table/*, sf-admin-menu/main); само значение настройки не передаётся |
Правила отказа:
record-changedотклоняется безrevision, с лишним ключом (например,values), с пустой коллекцией и с повтором вfields.record-removedотклоняется безidи сid: null.collection-changedотклоняется безreasonи сreason, который не слово-метка (Created!).files-movedотклоняется с пустымids, с повтором вidsи с папкой, которая не идентификатор и неnull.counterотклоняется с отрицательным или дробнымvalueи сkeyв верхнем регистре.navigationпринимает только путь, который начинается с одной косой черты, длиной до 2048 символов. Адрес другого сайта (https://…), адрес без схемы (//…) иjavascript:отклоняются. Имя области — строчная латинская буква, затем до 31 строчной буквы, цифры или дефиса.preference-changedотклоняется с пустым ключом, с пробелом в ключе и с лишним ключомvalue. Ключ — до 256 символов.
Проверка значения
SF.Composition.checkPortValue(type, value) проверяет значение так же, как
sf-composition-scope перед доставкой: возвращает замороженную копию или выбрасывает
TypeError. Тот же вызов есть в модуле distr/core/js/composition/index.mjs
для серверной стороны.
const moved = SF.Composition.checkPortValue('files-moved', {
ids: [41, 42],
from: null,
to: 'f-2'
});
Object.isFrozen(moved); // true
try {
SF.Composition.checkPortValue('navigation', {url: '//other.example/', region: 'content'});
} catch (error) {
error instanceof TypeError; // true: адрес другого сайта
}
Компонент отправляет значение событием sf-port-output с
detail: {port, value}, а получает методом sfPortInput(port, value, meta).
Порты и их типы элемент объявляет в static sfPorts = {outputs, inputs}.
sf-composition-scope проверяет значение по типу выхода; неверное значение
не доставляется, а маршрут переходит в состояние ошибки.
Смотрите также
- Связь компонентов без кода проекта — маршруты
layout.scope. - Фрагменты интерфейса — описание фрагмента, его выходы и входы.
- Фрагмент интерфейса (
simai.interface-fragment) — требования стандарта. - Диагностика — коды ошибок проверки документа.