Перейти к содержимому

Рендеринг атрибутов

В файлах шаблонов ко всем атрибутам можно обращаться через переменные $attributes или $a и соответствующий идентификатор поля.

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

Программная запись атрибутов

Редактор сохраняет значения внутри blockstudio.attributes. При записи блока вне редактора, например через REST API, WP-CLI, при переносе содержимого или через MCP-сервер, приложение получает блок из атрибутов, зарегистрированных Blockstudio в WP_Block_Type, и записывает их на верхний уровень. Оба формата корректно отображаются:

PHP
// 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():

PHP
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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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
<?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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

bs_render_data_attributes() выводит атрибуты напрямую. bs_data_attributes() возвращает строку.

Группа

В групповых полях к идентификаторам дочерних атрибутов добавляется префикс с именем группы. Используйте bs_get_group(), чтобы получить массив полей группы без префиксов:

PHP

PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>

Такой способ удаляет префикс группы из ключей атрибутов. Например, $a['settings_title'] становится $group['title'].

Вспомогательная функция работает и с группами из повторно используемых пользовательских полей:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

Повторитель

Переберите элементы повторителя:

PHP

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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

Кулинарная книга шаблонов полей