Към съдържанието

Извеждане на атрибути

В шаблонните файлове достъпвате всички атрибути чрез променливите $attributes или $a и съответния ID на полето.

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"}}} /-->' );

От най-горното ниво се четат само ID-тата, декларирани от блока, затова собствените атрибути на WordPress, като anchor, className, lock, metadata и style, никога не се приемат за стойности на полета. Когато един и същ ID се среща и на двете места, предимство има вложената стойност.

Програмно четене на атрибути

Кодът, който се изпълнява извън шаблона, например за структурирани данни в 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() връща низа.

Група

Полетата от група добавят името на групата като префикс към ID-тата на дъщерните атрибути. Използвайте 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 %}

Наръчник с примери за полета