Собственные блоки и шаблоны

Выбор способа реализации

Если блок состоит из полей и шаблона вывода, опишите его в JSON. Редактор построит форму автоматически — это декларативный блок.

Для своего узла Lexical, React-компонента или сложной логики создайте JavaScript-расширение типа native и подключите через Runtime SDK.

Если блок выводит записи инфоблока, каталога или внешнего API, используйте провайдер данных. Его серверный код читает записи и проверяет доступ к ним.

Декларативный блок: сообщение

Этот пример описывает заголовок, основной текст и флажок показа текста:

JSON

{
  "descriptorVersion": 1,
  "extensionId": "project.notice",
  "blocks": [{
    "type": "notice", "label": "Сообщение", "schemaVersion": 1,
    "schema": {"schemaVersion": 1, "fields": {
      "title": {"type": "string", "default": "Сообщение", "maxLength": 120},
      "showText": {"type": "boolean", "default": true},
      "text": {"type": "string", "default": "", "maxLength": 2048}
    }},
    "template": {"tag": "aside", "children": [
      {"tag": "h2", "children": [{"field": "title"}]},
      {"if": "showText", "then": {"tag": "p", "children": [{"field": "text"}]}}
    ]}
  }]
}

Подключите файл через assets.descriptor в манифесте пакета с kind: "declarative". Значение id в манифесте должно совпадать с extensionId. Сборка и размещение описаны в Runtime SDK.

Поля поддерживают типы string, number и boolean, значения по умолчанию, перечисления, ограничения min, max и maxLength. Передавайте значения нужного типа: например, логическое true, а не строку "true".

Запись {field: "text"} подставляет экранированный текст. Шаблон не выполняет JavaScript и не вставляет необработанный HTML. При showText: false условие if убирает абзац из вывода, сохраняя текст в данных блока.

У декларативного контейнера можно описать именованные области для дочерних блоков — slots. Редактор управляет их деревом. Узлы этих областей должны оставаться внутри соответствующего контейнера.

JavaScript-блок с собственной формой

В готовом примере откройте src/native.mjs. В нём есть класс узла, импорт и экспорт JSON, exportDOM(), вставка, форма параметров, команды агента и копирование шаблонов.

Для своего пакета замените идентификатор расширения и имена типов узлов во всех связанных объявлениях. React и Lexical берите из host. Внутренние модули ядра не импортируйте: они не входят в API расширений.

В JavaScript-примере форма открывается во вкладке «Правка → Параметры». У декларативного блока она открывается прямо в документе. В обоих случаях форма работает в редакторе, отдельная PHP-форма для неё не нужна.

Шаблоны

Для шаблонов из поддерживаемых блоков используйте AgentBlockSpec. Шаблон с расширениями описывается объектом RuntimeTemplateDocument: schemaVersion: 1, extensionDigest и children.

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

Копирование JavaScript-узлов

Зарегистрируйте для своего типа templateCodecs с методом clone. Он должен синхронно копировать JSON узла. Собственные идентификаторы и ссылки на них заменяйте через функцию remapId, которую передаёт редактор.

Редактор сам обрабатывает идентификаторы блоков и дочерние узлы. Метод clone класса Lexical копирует узел внутри текущей сессии. Для вставки шаблона нужен отдельный templateCodecs.clone.

Проверка вставки

Вставьте один шаблон дважды. У блоков должны быть разные идентификаторы. Внутренние ссылки первой копии должны вести на её блоки, второй — на блоки второй копии.

Если схема несовместима, набор расширений другой или правила копирования нет, редактор отклоняет вставку целиком.

Обновление шаблонов и документов описано в разделе проверки и отката.