Типы полей и кастомные рендереры для форм редактирования и создания блоков
В конфигурации типа блока задаёте массив fields — BlockBuilder строит форму создания и редактирования и сохраняет значения в props.
Ошибки показываются в футере модалки и обновляются при изменении полей после неуспешного сохранения. Для своей формы без BlockBuilderComponent — ReactiveFormValidationTracker в разделе «Утилиты». У кастомного рендерера setError вызывается только при смене текста ошибки.
Встроенные контролы для fields. Описание параметров — в разделе Параметры полей ниже.
textЗаголовки и короткие строки
textareaДлинный текст, описания, контент
emailКонтактный email с проверкой формата
urlСсылка с проверкой формата
numberРазмеры, счётчики, числовые настройки
selectВыбор из фиксированного списка options
checkboxВключено / выключено, видимость, флаги
radioОдин вариант из options, все опции видны сразу
colorЦвет фона, текста, акцентов (HEX)
imageКартинка блока с preview и загрузкой на сервер
fileДокументы и архивы — список файлов, без preview
file-importКнопка импорта: данные из файла попадают в другие поля формы
block-anchorСсылка на блок страницы (#id) или внешний URL
matrix-tableТаблица с заголовками, HTML и картинками в ячейках
customПроизвольный UI — свой рендерер по rendererId
api-selectСправочники с бэкенда: поиск и подгрузка страниц
Каждый объект в массиве fields описывает одно поле формы. При сохранении блока значения попадают в block.props под ключом field (кроме полей с persist: false).
fieldобязательныйИмя свойства в props блока. По нему читаете значение в render-компоненте (props.title, props.cards). Должно быть уникальным в рамках типа блока.
labelобязательныйПодпись поля в форме редактирования. На сохранённые данные не влияет.
typeобязательныйКакой контрол показать и как хранить значение. От типа зависят допустимые параметры: для select нужен options, для image — fileUploadConfig и т.д. Список типов — в разделе Стандартные типы полей.
defaultValueопциональныйЗначение сразу после создания нового блока. Без него — пустая строка, 0, false или [] в зависимости от типа. Для repeater — массив элементов; для select с multiple — массив value.
placeholderопциональныйСерая подсказка в пустом поле ввода. Работает для text, textarea, email, url.
optionsselect, radioСтатический список вариантов. value пишется в props, label видит пользователь. disabled: true — опция отображается, но недоступна для выбора.
multipleselect, image, fileНесколько значений вместо одного: в select — массив value, в image/file — несколько загрузок. У Поле - выбор из API (api-select) множественный режим задаётся в apiSelectConfig.multiple, не здесь.
optionsFromselectОпции строятся из значения другого поля — для зависимых списков (страна → город) без ручного дублирования options. source — имя поля-источника, when — условие, map(item, index, sourceArray, context?) — преобразование в options; context содержит formData, itemData (текущий item repeater), ownerItemData (родительский item). exclude: { from: 'ownerRepeaterItem', field: 'id' } — исключить значение из options (удобно в nested repeater). Статический options остаётся fallback.
rulesопциональныйПроверки перед сохранением. Ошибки показываются в футере модалки. У каждого правила опциональный message — иначе используется текст по умолчанию.
required — поле не пустоеminLength / maxLength — длина строки (value — число)min / max — диапазон для numberpattern — регулярное выражение (value — строка regex)email / url — формат адресаcustom — validator: (value) => booleandependsOnопциональныйПоле видно только когда другое поле совпадает с условием. Скрытые поля не валидируются и не мешают сохранению. Подробнее — Поле - условное отображение (dependsOn).
persistопциональный, по умолчанию truefalse — поле участвует в форме, но не попадает в block.props при save. Нужно для служебных UI: кнопка импорта, переключатели настройки формы. У file-import persist выключен по умолчанию. Работает и внутри repeater.
Дополнительные объекты — только когда стандартных параметров недостаточно:
spacingConfig / spacingOptionsОтступы блока (padding/margin) по брекпоинтам. spacingOptions на уровне конфига типа блока добавляет поле автоматически; spacingConfig — при ручном type: "spacing". См. Поле - отступы (spacing).
repeaterConfigСтруктура массива однотипных элементов: вложенные fields, лимиты min/max, подписи кнопок. См. Поле - повторитель (repeater).
fileUploadConfigPOST файла на ваш сервер (uploadUrl, responseMapper) вместо хранения base64 в props. Для Поле - изображение (image) и Поле - файл (file).
fileImportConfigЗагрузка файла как действие: ответ API сливается в другие поля формы через merge (append/replace, dedupe). Само поле в props не сохраняется.
blockAnchorConfigВыбор якоря #block-id или произвольного URL в форме. Скролл и клик — в вашем компоненте блока. См. Поле - якорь (block-anchor).
matrixTableConfigНастройки редактора таблицы (подписи вкладок, лимит размера картинок в ячейках). См. Поле - таблица (matrix-table).
apiSelectConfigURL API, параметры поиска/пагинации, маппинг ответа. См. Поле - выбор из API (api-select).
customFieldConfigrendererId — id зарегистрированного рендерера; options — произвольные настройки, доступные в context.options. См. Кастомные рендереры полей.
multiple в props — одно value из optionsmultiple: true — массив value; defaultValue тоже массив (или [])Отступы блока по брекпоинтам. Удобнее подключать через spacingOptions в конфиге типа блока, чем полем spacing в fields.
Явное поле type: "spacing" в fields игнорируется, если задано spacingOptions. Отступы в UI: margin на обёртку блока, padding — CSS-переменные --spacing-padding-* в вашем компоненте.
Массив однотипных элементов — карточки, слайды, строки списка. Вложенные репитеры поддерживаются (maxNestingDepth, по умолчанию 2). Элементы сворачиваются в accordion: chevron и клик по заголовку toggles (aria-expanded).
repeaterConfig.fields — любые типы кроме spacing. min без явного значения: 1 при required, иначе 0. countLabelVariants — склонение счётчика («1 элемент», «2 элемента»). defaultExpandFirstOnly (default true) — при открытии формы развёрнут только первый item; false — все развёрнуты, как раньше.
Загрузка с preview. В props — URL строкой или объект src, width, height, size после серверной загрузки. Base64 только для разработки; в продакшене — fileUploadConfig.uploadUrl.
Важно: при uploadUrl ответ сервера для image должен содержать src с URL. Другой формат API — responseMapper в fileUploadConfig. Поле - файл (file)
Загрузка документов и произвольных файлов. Список имён в форме, без превью как у image. В props — URL строкой или массив URL при multiple: true.
Выбор блока страницы (#block-id) или произвольного URL. Скролл и поведение ссылки — в вашем компоненте блока; форма только сохраняет значение.
Целевой блок должен иметь data-block-id (BlockBuilder выставляет при рендере):
Редактор таблицы: колонки и строки, типы ячеек (default, HTML, image). Вкладки «Структура» и «Строки» поддерживают collapse (chevron / клик по заголовку). В props — { tableHead, tableBody }.
Поиск и пагинация по внешнему API. «Загрузить ещё» — при hasMore: true в ответе.
Ожидаемый формат ответа:
Другой формат — responseMapper или dataPath. Множественный выбор — apiSelectConfig.multiple.
Поле показывается, если другое поле совпадает с условием. Скрытые поля не валидируются.
dependsOn.field ссылается на поле того же элемента репитера.
Поле type: "custom" — когда стандартных типов из раздела Стандартные типы полей недостаточно: свой виджет, интеграция библиотеки, сложный интерактив. Это не отдельный тип блока и не замена компонента блока на канвасе — только UI поля в модалке create/edit.
select, repeater, matrix-table — часто хватает без customICustomFieldRenderer (уникальный id)fields — type: "custom" и customFieldConfig.rendererIdformScope.setField — изменить другое поле формы (например, сбросить зависимое). В repeater доступны formScope.repeater.updateItemField и live-ссылка на item. setError на результате вызывается фреймворком при смене текста ошибки — не дублируйте лишние перерисовки.
Core / свой UI:
Vue / React — отдельный реестр, проп customFieldRendererRegistry у BlockBuilderComponent:
Важно: регистрируйте рендереры до первого открытия формы. При внешних библиотеках храните инстанс локально в render(), не в свойстве класса; инициализируйте синхронно — без setTimeout. Регистрация
customFieldConfigrendererId — совпадает с ICustomFieldRenderer.idoptions — произвольный объект, доступен в context.optionsAPI реестра: registerCustomFieldRenderer, registerCustomFieldRenderers, getCustomFieldRenderer, hasCustomFieldRenderer, unregisterCustomFieldRenderer, getAllCustomFieldRenderers — см. /docs/core/methods. В repeater храните DOM/инстанс виджета локально в render(), в destroy снимайте слушатели. Живые примеры — examples/vue3, examples/api-usage.