Программная отрисовка
Поскольку Gutenberg становится главным инструментом для создания легко редактируемых сайтов для клиентов, разумно представить все необходимые разделы сайта в виде блоков. Такой подход подойдет большинству пользователей, однако опытным пользователям и для отдельных задач может понадобиться использовать существующие блоки за пределами редактора.
Blockstudio предлагает два способа программной отрисовки блоков:
- Функции PHP:
bs_render_blockиbs_blockдля вывода из кода PHP - Теги HTML: теги
<bs:block-name>, которые заменяются выводом блока в любом месте страницы
Поддерживаются все возможности Blockstudio, включая встроенные стили, скрипты и локальные стили.
Острова также работают с этими способами отрисовки. Динамический остров, выведенный с помощью bs_render_block(), bs_block() или тега блока, возвращает тот же маркер-заполнитель, что и блок из содержимого записи. Если маркер есть в ответе, внедряется среда выполнения внешнего интерфейса.
Структурированные композиции и полные документы
Для долгосрочных инструментов, предварительного просмотра, экспорта и галерей компонентов используйте версионируемую Blockstudio\Render API. Она принимает одно объявление или упорядоченный список и выполняет отрисовку без вывода через echo:
use Blockstudio\Render;
$composition = [
'root' => 'theme/card',
'example' => [
'data' => [
'heading' => 'Example card',
],
'layers' => [
[
'name' => 'theme/button',
'data' => [
'label' => 'Continue',
],
],
],
],
];
$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
'title' => 'Component preview',
'contentElement' => 'main',
'contentClasses' => ['component-preview'],
]);
В каноническом нормализованном объявлении четыре ключа:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers и example — это вспомогательные входные данные, которые удаляются при нормализации. Вложенные объявления отрисовываются рекурсивно через тот же конвейер Blockstudio.
Render::document() возвращает schemaVersion, html, body, blocks, assets, warnings и errors. Значение assets отделяет head, footer, styles, scripts, modules, interactivity, ui и tailwind. Список блоков и ресурсы включают зависимости, на которые ссылаются выбранные шаблоны, но исключают несвязанные ресурсы и ресурсы только для редактора.
Для полных документов можно задать bodyClasses/bodyAttributes и, при необходимости, обернуть отрисованное тело тегами contentElement, contentClasses и contentAttributes. Допустимо использовать только безопасное имя элемента; возвращаемое значение body остается не обернутым отрисованным содержимым. Параметры head и footer добавляют доверенную разметку документа в соответствующие позиции и включаются в итоговый набор ресурсов.
Чтобы собрать документ вокруг уже отрисованного HTML, укажите известные имена корневых блоков:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
Используйте Render::content() для сериализованного содержимого блока WordPress. Если за один запрос нужно отобразить несколько независимых документов, вызывайте Blockstudio\Batch_Render::reset() между ними; Canvas::documents() делает это автоматически.
Рендеринг вне страницы
Blockstudio добавляет комментарий <!--blockstudio/namespace/slug--> перед каждым блоком, который он выводит. На странице фронтенда буфер считывает эти комментарии, чтобы определить присутствующие блоки, загружает их ресурсы и удаляет комментарии перед отправкой ответа.
В выводе, который не проходит через этот буфер, комментарии сохраняются. Это касается ответов REST, лент, обработчиков AJAX, а также HTML, которые вы сохраняете или отправляете куда-либо ещё после do_blocks(), Render::content() или bs_render_block(). Чтобы удалить их, используйте
bs_strip_render_markers():
$html = bs_strip_render_markers(do_blocks($post->post_content));
Функция удаляет комментарии зарегистрированных блоков Blockstudio и оставляет всё остальное без изменений, включая другие комментарии HTML. Она распознаёт те же маркеры, что удаляет буфер страницы. Вызывайте её после регистрации блоков (начиная с init).
Не удаляйте разметку, которая всё ещё выводится на странице фронтенда через буфер. Странице нужны комментарии, чтобы определить, какие ресурсы блоков загружать, а Blockstudio удалит их в конце самостоятельно.
Удаление комментариев не добавляет ресурсы. Файлы блоков CSS и JavaScript внедряются только буфером страницы. Если они также нужны потребителю, используйте bs_block_assets() или
Render::document().
Просмотр блоков
Используйте bs_block_fields() после регистрации блоков (начиная с init), чтобы получить итоговые определения полей, не обращаясь к внутренним реестрам:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
Возвращается массив зарегистрированных определений полей, включая фильтры атрибутов, развёрнутые пользовательские поля, переопределения, а также вложенные группы, вкладки и повторители. Для блока Blockstudio без полей возвращается []. Результат представляет собой копию: его изменение не меняет зарегистрированный блок.
Это определения, а не сохраненные значения. Для проверки сохраненной разметки используйте bs_validate_block() вместо поддержки отдельного обходчика полей. Чтобы описать допустимые для блока значения, используйте bs_block_schema(). Атрибуты, принадлежащие WordPress, остаются отдельными.
Поля, добавленные расширениями, не входят в bs_block_fields(). Чтобы получить их, используйте bs_block_extension_fields(). Функция сопоставляет расширения по имени блока, поэтому работает также с основными блоками и блоками сторонних разработчиков:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
Возвращаемое значение содержит определения полей каждого подходящего расширения в порядке регистрации расширений и имеет ту же структуру, что и bs_block_fields(). Если ни одно расширение не соответствует блоку, возвращается []. Значения расширений сохраняются в том же объекте attrs.blockstudio.attributes, что и значения собственных полей блока, поэтому все идентификаторы используют общее пространство имён. Если два расширения задают один и тот же идентификатор, возвращаются оба определения, и оба изменяют одно значение; при рендеринге применяется определение расширения, зарегистрированного позже.
Чтобы прочитать значения сохранённого блока в том виде, в котором их получает его шаблон, используйте bs_block_values().
Используйте bs_block_assets(), чтобы просмотреть обнаруженные у блока CSS и JavaScript. Чтобы получить полный документ предпросмотра, включая вложенные блоки и общие зависимости среды выполнения, используйте Render::document(), как описано выше.
Проверка сохранённых значений
Используйте bs_validate_block() после регистрации блока (начиная с init), чтобы проверить программно созданные или импортированные атрибуты блока перед их сохранением:
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);
if ($findings === null) {
// No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
// No stored-value problems were found.
} else {
// Review the findings before saving.
}
Передайте полный массив attrs, а не только blockstudio.attributes. Блок Blockstudio при рендеринге принимает также объявленные поля на верхнем уровне, а если переданы оба варианта, приоритет имеют вложенные значения. Расширения основных блоков и блоков сторонних разработчиков считывают только blockstudio.attributes. Пустой блок Blockstudio считается управляемым, и для него возвращается [], а не null.
Проверка выполняется явно и только для чтения. Она не рендерит шаблоны, не меняет значения, не сохраняет записи, не запрашивает медиафайлы и не запускает функции заполнения. Она не выполняется автоматически при сохранении, синхронизации страниц или рендеринге. Это не санитайзер, не проверка авторизации и не проверка существования вложения.
Каждый результат проверки содержит следующие стабильные ключи:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
В инструментах используйте code, а не переведённое message. source — это block или
extension. В путях используются ключи хранения и начинающиеся с нуля индексы
строк повторителя или элементов выбора; начального слеша нет. Символы ~ и / в ключе экранируются как ~0 и
~1. Группа верхнего уровня добавляет префикс к дочерним элементам (cta_title); анонимные группы
и вкладки не добавляют уровень. Конструктор не поддерживает группы с ID внутри другой группы или повторителя,
поэтому их ключи не принимаются. Поля сообщений не имеют сохранённого значения. Поле файлов допускает связанное с ним поле <id>__size.
В корне блока Blockstudio ключи служебных данных и глобальные атрибуты HTML,
передаваемые отрисованному элементу, не считаются неизвестными полями. Это
не разрешает произвольные ключи в строках повторителя или расширение базовых блоков.
| Код | Значение | expected |
|---|---|---|
unknown_field |
Ни одно сохранённое поле не объявляет этот ключ хранения. | Известные ключи хранения. |
unknown_option |
Выбранного значения нет среди известных вариантов. | Допустимые значения вариантов. |
wrong_type |
Сохранённая структура не поддерживается этим полем. | Ожидаемое семейство или тип хранимых данных. |
too_few_rows, too_many_rows |
Имеющийся повторитель выходит за пределы min или max. |
Ограничение числа строк. |
definition_conflict |
Применимые определения одного ключа требуют разных структур хранения. | Источник и тип поля каждого определения. |
shadowed_value |
Вложенное значение переопределяет другое значение поля верхнего уровня. | Победившее вложенное значение. |
extension_top_level |
Шаблон может читать значение верхнего уровня, но привязки расширения — нет. | Необходимый путь в blockstudio/attributes. |
unknown_attribute |
Ключ верхнего уровня блока Blockstudio не читается при отрисовке и отбрасывается. | Зарегистрированные имена атрибутов, поля расширений и blockstudio. |
missing_container |
attributes, disabled, name или editor хранится на верхнем уровне, а blockstudio отсутствует. |
Необходимый путь в blockstudio. |
invalid_container |
blockstudio или blockstudio.attributes не является объектом. |
object. |
В сообщении о результате проверки unknown_field указывается ближайший ключ хранилища того же уровня, если расстояние до него не превышает трех правок; это правило используется для неизвестных параметров: This storage key is not declared by the block or its extensions. Did you mean "title"?
expected по-прежнему перечисляет все известные ключи.
При сопоставлении регистр не учитывается, и рассматриваются только ключи хранилища из этого контейнера. Сообщения переведены; интеграциям следует использовать code, path и expected, а не разбирать текст сообщения.
Ключ верхнего уровня блока Blockstudio, который не является ни зарегистрированным атрибутом
(его полем, атрибутами, которые WordPress добавляет для supports, lock и
metadata), ни полем соответствующего расширения, ни blockstudio, ни
служебным ключом или передаваемым атрибутом HTML, отбрасывается до запуска шаблона.
Например, такой ключ может быть опечаткой в ID поля или объектом values, сохранённым
без обёртки blockstudio; тогда появляется сообщение, поскольку блок
отрисовывается без этого значения. Для блоков, содержащих только поля расширений, ключи верхнего уровня
не проверяются.
Допустимые структуры соответствуют отрисовке: множественный выбор и флажки могут
содержать список, объект одного варианта или импортированное скалярное значение, включая числовой ноль. Для чисел допустимы строки с числовыми значениями. Поля файлов могут содержать ID вложений, объекты с ID, списки или строковые ссылки. Значения ссылок и значков должны быть объектами; для пользовательских типов полей используется зарегистрированный тип атрибута.
Поле attributes содержит список пар с непустым именем attribute
и скалярным значением value; необязательные метаданные, например data.media, сохраняются.
WordPress проверяет зарегистрированные атрибуты верхнего уровня перед отрисовкой, поэтому
может отклонить структуру, допустимую внутри blockstudio.attributes. Например,
значение radio "a" работает во вложенном объекте, но на верхнем уровне отбрасывается,
поскольку его зарегистрированный тип — object. Такое значение вызывает wrong_type.
Используйте вложенный объект для той же структуры хранения, которую записывает редактор.
Отсутствующие поля не являются обязательными. Пустые вложенные значения (null, false, '',
[]) и отключённые поля не вызывают ошибок значений. Явно пустой
повторитель всё равно проверяется на соответствие min; отсутствующий или отключённый повторитель — нет.
Пустое значение верхнего уровня указывается в отчёте, если WordPress отбрасывает его и восстанавливает
непустое значение по умолчанию. Такое же значение во вложенном объекте может очистить его.
Конфликты определений указываются, даже если ключ не содержит сохранённого значения.
Статические варианты и варианты populate, разрешённые при регистрации, проверяются
без повторного вызова populate. Удалённые варианты fetch и аргументы populate,
содержащие {attributes.*}, пропускаются. Цветовые значения и градиенты
могут быть пользовательскими, если не заданы disableCustomColors или disableCustomGradients.
Проверяются сохранённые значения, а не default, fallback или правила проверки редактора.
Поля соответствующих расширений включаются для каждого блока, на который они нацелены. В корне
блока или его расширений при отрисовке побеждают более поздние определения.
Собственное поле блока и поле расширения остаются отдельными определениями
одного ключа, и применяются оба. В строках повторителя отрисовщик берёт
первое поле с совпадающим ID в каждом источнике, поэтому применяются его варианты и ограничения.
Повторные определения сохраняются для диагностики конфликтов:
несовместимые структуры хранения вызывают definition_conflict, даже если
при отрисовке более позднее повторное определение не используется.
Функция проверяет один блок. При проверке документа обходите innerBlocks;
синхронизированные паттерны и другие ссылки автоматически не раскрываются. Команда
wp bs blocks validate обходит блоки одной или нескольких записей и указывает пути блоков.
Сайты с пользовательским разрешением значений при отрисовке могут адаптировать результаты, не меняя сохранённые данные:
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
if ($name !== 'my-theme/card') {
return $findings;
}
return array_values(array_filter($findings, function($finding) {
return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
}));
}, 10, 3);
Всегда возвращайте список результатов; возврат [] принимает блок. Этот
фильтр выполняется только для управляемых блоков, но не для результата null.
Описание сохраненных значений
Используйте bs_block_schema() после регистрации блока (init или позже), чтобы описать сохраняемые блоком значения, например, для генерации разметки блока в инструменте или интеграции с ИИ либо для проверки входных данных в маршруте REST:
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
Результат — это схема JSON объекта, сохраненного в attrs.blockstudio.attributes. Она охватывает поля блока и поля подходящих расширений, а также ключи хранилища, используемые при проверке: дочерним элементам группы верхнего уровня добавляется ее префикс, анонимные группы и вкладки не добавляют уровень, а поле файлов добавляет сопутствующее поле <id>__size. Повторители — это списки объектов строк с minItems и maxItems из min и max. additionalProperties имеет тип false в корне хранилища полей и в строках повторителя. Поля со значениями-объектами, например ссылки и пользовательские объекты, могут содержать собственные метаданные. У блока без полей нет properties, поэтому совпадением считается только пустой объект.
Каждое поле описывается в каноническом формате, который принимает bs_validate_block():
| Поле | Схема |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
Строка. |
number, range |
Число с minimum и maximum из min и max. |
toggle |
Логическое значение. |
select, radio, checkbox |
Значение параметра или список значений параметров для checkbox и multiple с enum. |
color, gradient |
Строка с enum, если задано disableCustomColors или disableCustomGradients. |
token |
Список строк. |
files |
Неотрицательный целочисленный идентификатор вложения или список идентификаторов с multiple. |
link |
Объект с url, title и opensInNewTab; требуется url. |
icon |
Объект с set, subSet и icon; требуются set и icon. |
attributes |
Список объектов с непустым attribute и скалярным value. |
repeater |
Список объектов строк. |
| Пользовательские типы полей | Зарегистрированный тип атрибута. |
enum перечисляет параметры, проверяемые при валидации: статические параметры и параметры заполнения, разрешенные при регистрации. У удаленных параметров fetch и аргументов заполнения, содержащих {attributes.*}, нет enum. Ключ, для которого определены разные формы хранения, пропускается, поскольку при проверке учитываются все сохраненные под ним значения. Если поле блока и поле расширения используют общий ключ, enum перечисляет значения, допустимые для обоих. Для общих повторителей объединяются дочерние поля и применяются более строгие ограничения на строки из обоих определений. В строках повторителя, как и при рендеринге, применяется первое поле с подходящим идентификатором из каждого источника. Явно заданное поле с именем <id>__size имеет приоритет над автоматически добавляемым сопутствующим полем размера файла.
Если для закрытого поля нет доступных вариантов или два подходящих набора параметров не имеют общих вариантов, каноническим значением будет null для одиночного выбора или пустой список для множественного выбора. Пустой список вариантов не превращает поле в поле без ограничений. Варианты из удаленных источников и зависящие от атрибутов остаются открытыми.
label поля становится title, его help становится description, а default сохраняется как аннотация. Собственное title схемы — это заголовок блока. Обязательных полей нет, условная логика не входит в схему.
Ограничения используют только ключевые слова, которые проверяет rest_validate_value_from_schema(), поэтому схему можно напрямую использовать в качестве входной схемы маршрута REST или возможности:
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
Схема описывает по одной форме на поле; при проверке также принимаются импортированные структуры, например объекты параметров, числовые строки и объекты ID. Она не заменяет bs_validate_block(): конфликты определений являются проблемами конфигурации и могут вызывать замечания, даже если конфликтующий ключ пропущен. Фильтры проверки также могут задавать правила для конкретного сайта. Используйте bs_validate_block() для проверки сохраненного содержимого. Сайты с пользовательским обработчиком во время рендеринга могут адаптировать схему с помощью фильтра blockstudio/blocks/attributes/schema.
Функции PHP
Без данных
В простейшем случае функция принимает одно значение — ID блока, который нужно отобразить на странице.
bs_render_block('blockstudio/cta');
С данными
Чтобы отобразить блок с пользовательскими данными, вместо одного значения в первом параметре нужно передать массив. Значение ключа data будет передано в переменную $attributes и $a внутри шаблона блока.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
Вложенность
Блоки можно вкладывать друг в друга с помощью функции bs_block в сочетании с мощной переменной $content в шаблонах блоков.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => bs_block([
'id' => 'blockstudio/button',
'data' => [
'text' => 'Button Text',
]
])
]);
Блок кнопки будет отображен вместо переменной $content в шаблоне блока.
Встроенные блоки, отрисованные с помощью bs_render_block() или bs_block(), всегда выводят HTML, подготовленный для фронтенда, даже если родительский блок в данный момент отображается в режиме предварительного просмотра редактора. Псевдокомпоненты шаблона, такие как <RichText /> и <InnerBlocks />, обрабатываются до возврата встроенного блока.
Несколько слотов
Также можно создать несколько слотов содержимого: для этого достаточно сделать переменную $content ассоциативным массивом и вызвать соответствующие ключи в функции bs_block.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => [
'beforeContent' => bs_block([
'id' => 'blockstudio/badge',
'data' => ['text' => 'Before Content']
]),
'afterContent' => bs_block([
'id' => 'blockstudio/button',
'data' => ['text' => 'Button Text']
])
]
]);
Теги блоков
Встраивайте любые блоки с помощью синтаксиса тегов HTML. Поддерживаются два формата:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
Оба варианта отображают один и тот же блок. Синтаксис <bs:> преобразует дефис в разделитель пространства имен (acme-hero превращается в acme/hero). Дефисы проверяются слева направо, и используется первый зарегистрированный вариант, поэтому разрешаются и пространства имен с дефисами: <bs:acme-ui-button> проверяет acme/ui-button, затем acme-ui/button. В синтаксисе <block> полное имя блока указывается в атрибуте name.
Работают и блоки Blockstudio, и стандартные блоки WordPress. Блоки Blockstudio проходят полный конвейер (шаблоны, Tailwind, ресурсы). Стандартные блоки отображаются системой рендеринга блоков WordPress с помощью встроенных рендереров блоков.
Как это работает
Поведение тегов блоков зависит от того, где они используются:
В шаблонах блоков и содержимом записей теги при обработке заменяются отрисованными блоками HTML. Результат — готовая разметка указанного блока, встроенная непосредственно в страницу. В редакторе для таких блоков нет WordPress. Они служат только механизмом отображения.
В Страницах, паттернах и шаблонах сайта теги преобразуются в стандартные блоки WordPress до синхронизации исходного кода файла или его регистрации в WordPress. Это означает, что блоки появляются в редакторе, их можно редактировать, если целевая среда поддерживает редактирование, и они проходят полный жизненный цикл блоков WordPress. Синтаксис тегов — это краткая запись для определения содержимого блоков в файлах шаблонов.
Это различие важно: теги блоков в шаблонах формируют результат, а теги в страницах, паттернах и шаблонах сайта создают стандартные блоки.
В шаблонах блоков
Теги блоков автоматически обрабатываются в шаблонах Twig и PHP. Настраивать ничего не нужно. Это относится к синтаксису <bs:> и <block>, а также к любым зарегистрированным тегам префикса и псевдонимам, поэтому шаблон может выводить их напрямую, не вызывая bs_render_block(). Результат отображается HTML и встраивается непосредственно в вывод шаблона блока:
<div class="my-page">
<bs:mytheme-card title="Featured" />
<block name="core/separator" />
<bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
<block name="core/heading" level="2">Also WordPress</block>
<theme-card title="Prefix shorthand" />
</div>
В содержимом записей
Обработка на уровне страницы (содержимое записей, области виджетов) включается отдельно:
{
"blockTags": {
"enabled": true
}
}
Или с помощью фильтра:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
Синтаксис
Теги без закрывающего тега:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
Парные теги с внутренним содержимым:
<bs:mytheme-section layout="wide">
<p>Content inside the block.</p>
</bs:mytheme-section>
<block name="core/group">
<block name="core/paragraph">Inside a group.</block>
</block>
Свободно сочетайте варианты. Оба синтаксиса можно вкладывать друг в друга:
<bs:mytheme-section>
<block name="core/heading" level="2">Title</block>
<bs:mytheme-card title="Features" />
<block name="core/paragraph">Description text.</block>
</bs:mytheme-section>
Краткие записи с префиксами
Для тегов блоков также можно использовать краткие записи с префиксами проекта. Зарегистрируйте префикс с одним или несколькими пространствами имен, и Blockstudio разрешит <prefix-slug> в первый зарегистрированный блок в указанном порядке пространств имен:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
В примере выше <theme-card> разрешается в theme-components/card, <theme-button> использует bsui/button, если theme-components/button не зарегистрирован, а <theme-ui-feature-matrix> разрешается в theme-components/ui-feature-matrix.
Префиксы также можно комбинировать. Если тег с префиксом не разрешается напрямую, а оставшаяся часть имени сама является зарегистрированным тегом с префиксом, разрешение продолжается рекурсивно. Так префикс бренда может надстраиваться над префиксом пространства имен:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
У <theme-ui-input> нет блока theme-components/ui-input, поэтому поиск продолжается с префиксом ui и разрешается в bsui/input. Прямые совпадения всегда имеют приоритет перед вложенным разрешением; правила разрешения и запрета применяются к итоговому блоку.
Префиксы также можно настроить в blockstudio.json:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
Префиксы должны состоять из строчных букв или цифр, начинаться с буквы и не содержать дефисов. Явные псевдонимы из blockstudio/block_tags/tag_aliases имеют приоритет над разрешением префиксов. Неизвестные теги с префиксами остаются без изменений.
Теги с префиксами и псевдонимами по-прежнему доступны для удобства при создании контента. Каноническая и переносимая запись — это всегда <bs:namespace-slug>, поскольку она указывает настоящее имя блока и не зависит от фильтров проекта:
<bs:theme-components-card />
<bs:bsui-input />
В примерах Blockstudio, диагностических сообщениях и программном выводе используется эта каноническая запись. Если проекту нужно отказаться от старого краткого синтаксиса, можно использовать отдельную миграцию тегов на канонический синтаксис с предварительным пробным запуском, не загружая WordPress.
Стандартные блоки
Можно использовать любой блок с зарегистрированным рендерером:
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
<bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>
Или с синтаксисом <block>:
<block name="core/group">
<block name="core/columns">
<block name="core/column">
<block name="core/paragraph">Left column</block>
</block>
<block name="core/column">
<block name="core/paragraph">Right column</block>
</block>
</block>
</block>
Списки разрешенных и запрещенных блоков
Управляйте тем, какие блоки можно отображать с помощью тегов:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow разрешает только соответствующие шаблоны. deny исключает соответствующие шаблоны и имеет приоритет. Оба параметра поддерживают подстановочные знаки * с помощью fnmatch(). Правила применяются к обоим синтаксисам и к обработке на уровне шаблона и страницы.
Фильтры: blockstudio/block_tags/allow и blockstudio/block_tags/deny.
Передача атрибутов HTML без изменений
Атрибуты с префиксом data- передаются корневому элементу отрисованного блока. Атрибуты с префиксом html- также передаются, но сам префикс удаляется. Работает с обоими синтаксисами. Переданный атрибут заменяет существующее значение корневого элемента, а не объединяется с ним, поэтому html-class заменяет собственные классы блока.
Блок Blockstudio также помещает на свой корневой элемент глобальные атрибуты, которые не объявлены в нем как поля: id, style, role, title, lang, dir, hidden, tabindex и все атрибуты aria-*. Объявленное поле всегда имеет приоритет, поэтому блок с полем title получает значение из $a['title']. Переданные стили обрабатываются через safecss_filter_attr(), к атрибутам стилей в содержимом записей применяется фильтр WordPress, а сами стили добавляются к стилям, уже заданным в шаблоне.
Значения атрибутов представлены в форме HTML, поэтому сущности декодируются один раз при разборе тега: title="Tom & Jerry" попадает в шаблон как Tom & Jerry и повторно экранируется при выводе. В заключенных в кавычки значениях могут быть >, как в вариантах Tailwind и селекторах анимации, причем как в тегах без закрывающего тега, так и в парных.
Любые другие атрибуты, не объявленные блоком, включая class, не передаются в HTML. Если включен WP_DEBUG, Blockstudio сообщает о каждом таком атрибуте один раз за запрос через _doing_it_wrong(). Объявите для него поле или укажите его как атрибут data-, aria- или html-.
<bs:mytheme-card
title="My Card"
html-class="featured-card"
html-id="main-card"
data-analytics="card-click"
/>
<block name="core/paragraph" html-class="highlight" data-section="intro">
Highlighted paragraph.
</block>
Пользовательские рендереры
Зарегистрируйте пользовательские рендереры для дополнительных типов блоков. Рендереры принимают массив атрибутов и строку внутреннего содержимого, а возвращают массив блока WordPress:
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
$builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
$html = '<div class="my-block">' . $inner_content . '</div>';
return [
'blockName' => 'myplugin/custom-block',
'attrs' => $attrs,
'innerBlocks' => [],
'innerHTML' => $html,
'innerContent' => [$html],
];
};
return $builders;
}, 10, 2);
Для контейнерных блоков, которым нужно разобрать внутреннее содержимое на дочерние блоки, добавьте вторую запись в тот же фильтр:
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
$content = ['<div class="my-wrapper">'];
foreach ($inner_blocks as $block) {
$content[] = null;
}
$content[] = '</div>';
return [
'blockName' => 'myplugin/wrapper',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '<div class="my-wrapper"></div>',
'innerContent' => $content,
];
};
blockstudio/block_tags/builders применяется и к тегам блоков, и к пользовательским блокам, выбранным через blockstudio/parser/element_mapping. Этот хук подходит для проектов с сопоставлением элементов блокам, которым нужно перенести внутренний текст в поле Blockstudio или создать массив пользовательского блока.
blockstudio/block_tags/renderers и blockstudio/parser/renderers получают один и тот же реестр и callback той же формы. Они остаются доступными для совместимости и итоговых переопределений на уровне парсера. Фильтры выполняются в таком порядке:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
Более поздний фильтр может заменить рендерер, зарегистрированный ранее.
Программное использование
Примените обработку тегов к любой строке из PHP:
$html = apply_filters('blockstudio/block_tags/render', $content);
Компоненты
Теги блоков хорошо сочетаются с Компонентами. Компоненты — это блоки, которые отображаются только программно и никогда не появляются в редакторе.
<bs:mytheme-card title="My Card" description="Card content." />
Парсер
Теги блоков обрабатывает легковесный сканер строк, заменяющий DOMDocument. Парсер поддерживает синтаксис <bs:> и <block>, вложенные теги с одинаковыми именами с отслеживанием уровня вложенности, заключенные в кавычки значения атрибутов и рекурсивные блоки-контейнеры. Он создан специально для этого случая и работает быстрее, чем DOMDocument и WordPress WP_HTML_Tag_Processor. Кроме того, он позволяет избежать известных проблем DOMDocument с удалением префиксов пространств имен и приведением имен атрибутов к нижнему регистру.
Для Страниц, паттернов и шаблонов сайта тот же парсер также обрабатывает исходные элементы HTML (<p>, <div>, <h1> и т. д.), сопоставляя их соответствующим стандартным блокам WordPress.
Если сопоставление элементов связывает <p> с зарегистрированным нестандартным блоком Blockstudio, в котором объявлен атрибут richtext content, внутреннее содержимое HTML автоматически передается в этот атрибут content, в том числе для встроенных тегов, например code и img, сопоставленных на уровне блока. Если единственный дочерний элемент абзаца — изображение, абзац становится блоком, на который указывает <img>. Вложенные теги блоков и элементы HTML на уровне блока по-прежнему обрабатываются обычным способом разбора внутренних блоков. <block name="core/shortcode"> сохраняет текст шорткода как содержимое блока.