Рендеринг атрибутов
В файлах шаблонов ко всем атрибутам можно обращаться через переменные $attributes или $a и соответствующий идентификатор поля.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Программная запись атрибутов
Редактор сохраняет значения внутри blockstudio.attributes. При записи блока вне редактора, например через REST API, WP-CLI, при переносе содержимого или через MCP-сервер, приложение получает блок из атрибутов, зарегистрированных Blockstudio в WP_Block_Type, и записывает их на верхний уровень. Оба формата корректно отображаются:
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
Читаются только идентификаторы, объявленные блоком на верхнем уровне, поэтому собственные атрибуты WordPress, такие как anchor, className, lock, metadata и style, никогда не используются как значения полей. Если один и тот же идентификатор указан в обоих местах, приоритет имеет вложенное значение.
Программное чтение атрибутов
Коду, работающему вне шаблона, например для структурированных данных в save_post, экспорта, поисковой индексации или фильтра render_block, часто нужны значения сохраненного блока в том виде, в каком их видит шаблон. bs_block_values() возвращает их без отрисовки блока. Вызовите ее после регистрации блока (начиная с init) и передайте полный массив attrs из parse_blocks():
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
Результат — массив $a шаблона с ключами по идентификаторам полей:
- Применяются значения по умолчанию для полей, а повторитель с
minсодержит начальные строки. - Верхнеуровневые значения объединяются с
blockstudio.attributes, причем вложенное значение имеет приоритет. Читаются только объявленные идентификаторы с верхнего уровня, а WordPress отбрасывает верхнеуровневое значение, не соответствующее зарегистрированному типу поля, например строку для списка выбора, точно так же, как при отрисовке. - Включаются поля совпадающих расширений вместе с их значениями по умолчанию. Расширение основного или стороннего блока читает только
blockstudio.attributes, как и при отрисовке. - Применяются форматы возврата: список выбора с
returnFormat, равнымlabel, возвращает подпись, а поле файлов — данные вложения. - Отключенные и пустые поля
false, как и в шаблоне.
null означает, что блоком или расширением не управляет Blockstudio. Для блока Blockstudio без полей возвращается [].
Функция выполняет то же преобразование, что и при отрисовке, поэтому имеет те же побочные эффекты: поля файлов запрашивают вложения, поле блока, не возвращающее data, отрисовывает указанный блок, а фильтр blockstudio/blocks/attributes/render запускается для каждого значения. Собственный шаблон блока не отрисовывается, а innerBlocks не разрешаются — обработайте их самостоятельно. Поле кода сохраняет сгенерированный идентификатор %selector%, который отличается при каждом вызове.
Разрешение выполняется в текущем контексте WordPress. Метаданные, создаваемые только при отрисовке, например счетчики блоков и innerBlocks, не создаются; фильтры отрисовки атрибутов получают имя блока, а не метаданные полностью отрисованного блока.
Для чтения сохраненных значений без преобразования отдельного параметра нет. Читайте напрямую массив attrs или используйте bs_validate_block()проверить.
Пустые значения
Если поле пустое или не выбран ни один параметр, значения атрибутов возвращают false.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Сложные типы
Файлы
По умолчанию (без returnFormat или при "returnFormat": "object") поле файлов возвращает массив с данными вложения. При "multiple": true оно возвращает список таких массивов. Если вложение для файла больше не существует, файл false.
| Ключ | Описание |
|---|---|
ID |
Идентификатор вложения. |
title |
Название вложения. |
alt |
Альтернативный текст. Если он пуст, используется название вложения. |
caption |
Подпись. |
description |
Описание. |
href |
Постоянная ссылка на страницу вложения. |
url |
URL файла. При выборе размера в списке ("size": true) — URL выбранного размера. |
sizes |
URL и размеры каждого зарегистрированного размера изображения; см. ниже. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizes содержит запись для каждого зарегистрированного размера изображения, а также full: URL под названием размера, а размеры — под <size>-width и <size>-height. Если для вложения не создан размер WordPress, возвращается исходный файл с его размерами. Если WordPress не может разрешить изображение или предварительный просмотр, ключ sizes отсутствует. Например, у PDF без созданного предварительного просмотра нет sizes, но у PDF с метаданными предварительного просмотра могут быть размеры изображений. Значение sizes равно null, если размеры изображений не зарегистрированы или фильтр отключаетfiles/sizes их . Этот фильтр также может сократить карту, поэтому перед чтением размеров проверьте, что нужный размер существует, как показано в примерах выше.
Объект не содержит ключей width, height, mime, type или size. Читайте размеры из sizes или используйте ID с такими функциями, как wp_get_attachment_image() и get_post_mime_type().
Форматы возврата
returnFormat изменяет возвращаемое полем значение:
returnFormat |
Значение |
|---|---|
"object" (по умолчанию) |
Описанный выше массив. |
"id" |
Идентификатор вложения в сохраненном виде или список идентификаторов при "multiple": true. |
"url" |
URL в виде строки или список URL при "multiple": true. Для изображений используется размер, заданный через returnSize (по умолчанию full), для остальных файлов — их URL. |
Ссылка
Поле ссылки возвращает объект с ключом URL и атрибутами:
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
Значок
Поле значка возвращает объект с ключами set, subSet и icon. Используйте вспомогательные функции bs_render_icon() и bs_icon() для вывода SVG:
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon() выводит SVG напрямую. bs_icon() возвращает его в виде строки.
Атрибуты
Тип поля атрибутов возвращает массив пар {attribute, value} для отображения в виде атрибутов HTML. Используйте bs_render_data_attributes() для их вывода:
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes() выводит атрибуты напрямую. bs_data_attributes() возвращает строку.
Группа
В групповых полях к идентификаторам дочерних атрибутов добавляется префикс с именем группы. Используйте bs_get_group(), чтобы получить массив полей группы без префиксов:
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
Такой способ удаляет префикс группы из ключей атрибутов. Например, $a['settings_title'] становится $group['title'].
Вспомогательная функция работает и с группами из повторно используемых пользовательских полей:
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
Повторитель
Переберите элементы повторителя:
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}