Пресеты

Пресет — готовый набор значений, которым форма блока заполняется в один клик. В PageCraft их два вида, и это не синонимы: примеры живут внутри схемы блока и едут вместе с ним, пресеты сохраняет себе конкретный пользователь.

	Примеры (examples)	Пресеты
Где хранятся	в schema_content блока	отдельно, в привязке к блоку и пользователю
Кто видит	все, у кого есть блок	только автор пресета
Кто создаёт	автор блока, правкой схемы	любой пользователь из формы блока
Версионируются	да, вместе с ревизией	нет
Уезжают при экспорте/форке	да	нет
Проверяются против схемы	да, ключи верхнего уровня	нет
Доступны в публичном API V1	да (внутри schema_content)	нет

Примеры в схеме

Массив examples в корне схемы. Каждый элемент — объект из трёх свойств:

Свойство	Обязательно	Значение
title	да	название в выпадающем списке
description	нет	пояснение к примеру
data	да	значения полей

{
  "type": "object",
  "fields": {
    "title": { "type": "text", "label": "Заголовок" },
    "subtitle": { "type": "text", "label": "Подзаголовок" }
  },
  "examples": [
    {
      "title": "Промо-баннер",
      "description": "Вариант для акции",
      "data": { "title": "Скидки до 50%", "subtitle": "Только до конца недели" }
    }
  ]
}

Правила data:

• ключи должны существовать в fields — иначе схема не сохранится: schema_content.examples[0].data: поле "titel" не существует в схеме;
• проверяются только ключи верхнего уровня: содержимое вложенных object и элементов array этой проверкой не покрыто;
• заполнять все поля не обязательно — незаполненные возьмут значения по умолчанию.

Примеры — часть ревизии блока. Значит, добавление примера создаёт новую версию блока, попадает в экспортный schema.json и достаётся форку.

Совет

Примеры — это документация блока, которую нельзя проигнорировать. Один-два осмысленных примера объясняют назначение полей быстрее, чем текст в docs.

Пресеты пользователя

Пресет создаётся прямо из формы блока: заполнили значения → сохранили под именем. В отличие от примеров, пресет — личная заготовка: другой пользователь его не увидит, даже если блок глобальный.

Свойство	Значение
name	название, до 255 символов, обязательно
description	пояснение
data	произвольный объект значений, обязателен

Создавать пресеты можно к своим блокам и к глобальным. Пресеты доступны только у сохранённого блока: пока блок не создан, привязывать пресет не к чему.

Осторожно

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

API пресетов

Только внутренний контур (сессия браузера), в публичном V1 API пресетов нет.

Метод	Путь	Что делает
GET	/api/blocks/{blockId}/presets	список своих пресетов блока
POST	/api/blocks/{blockId}/presets	создать: { "name": "…", "description": "…", "data": { … } }
PUT	/api/blocks/{blockId}/presets/{id}	изменить любое из трёх полей
DELETE	/api/blocks/{blockId}/presets/{id}	удалить

Как применяется набор значений

Выбор примера или пресета не подменяет данные формы целиком: значения накладываются на значения по умолчанию, собранные из схемы. Поле, которого в наборе нет, получит default, а не пустоту; элементы массивов пересобираются с сохранением порядка.

Поэтому набор безопасно оставлять неполным — он описывает отличия от «пустого» состояния блока.

Если в форме уже есть изменения, редактор спросит подтверждение: применение заменит введённые значения.

Что выбрать

• Значения имеют смысл для всех, кто ставит этот блок — делайте examples в схеме. Они переживут форк и экспорт.
• Значения нужны вам и вашему проекту (свои тексты, свои цвета) — делайте пресет. Он не будет засорять схему и не создаст лишнюю версию блока.

---

Источники: backend/public/block-schema.json (examples), backend/src/Service/BlockSchemaValidator.php (validateExampleDataKeys), backend/src/Entity/BlockPreset.php, backend/src/Controller/BlockPreset/**, backend/src/Service/BlockPreset/**, front/src/components/BlockEditor/BlockPresetSelector.tsx, front/src/lib/schemaFormUtils.ts.