Renderowanie atrybutów
W plikach szablonów dostęp do wszystkich atrybutów można uzyskać za pomocą zmiennych $attributes lub $a oraz odpowiedniego identyfikatora pola.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
Programowe zapisywanie atrybutów
Edytor zapisuje wartości w zagnieżdżonej tablicy blockstudio.attributes. Każdy mechanizm zapisujący blok poza edytorem, taki jak REST API, WP-CLI, migracja treści lub serwer MCP, odczytuje atrybuty zarejestrowane przez Blockstudio w WP_Block_Type i zapisuje je na najwyższym poziomie. Oba formaty są renderowane:
// 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"}}} /-->' );
Odczytywane są tylko identyfikatory zadeklarowane przez blok, więc własne atrybuty WordPress, takie jak anchor, className, lock, metadata i style, nigdy nie są przyjmowane jako wartości pól. Jeśli ten sam identyfikator pojawia się w obu miejscach, pierwszeństwo ma wartość zagnieżdżona.
Programowy odczyt atrybutów
Kod uruchamiany poza szablonem, na przykład dane strukturalne w save_post, eksport, indeksowanie wyszukiwania lub filtr render_block, często potrzebuje wartości zapisanych w bloku w takiej postaci, w jakiej widzi je szablon. bs_block_values() zwraca je bez renderowania bloku. Wywołaj tę funkcję po zarejestrowaniu bloku (init lub później), przekazując kompletną tablicę attrs z 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'] ?? '');
}
Wynikiem jest tablica $a szablonu, z kluczami będącymi identyfikatorami pól:
- Obowiązują wartości domyślne pól, a powtarzalne pole z
minzawiera początkowe wiersze. - Wartości z najwyższego poziomu są łączone z
blockstudio.attributes, a pierwszeństwo ma wartość zagnieżdżona. Odczytywane są tylko zadeklarowane identyfikatory z najwyższego poziomu, a WordPress pomija wartość z najwyższego poziomu, która nie pasuje do zarejestrowanego typu pola, na przykład ciąg znaków w polu wyboru, tak samo jak podczas renderowania. - Uwzględniane są pola pasujących rozszerzeń wraz z ich wartościami domyślnymi. Rozszerzenie bloku wbudowanego lub zewnętrznego odczytuje wyłącznie
blockstudio.attributes, tak jak podczas renderowania. - Stosowane są formaty zwracanych danych, więc pole wyboru z
returnFormatustawionym nalabelzwraca etykietę, a pole plików — dane załącznika. - Wyłączone i puste pola są
false, tak jak w szablonie.
null oznacza, że blok ani rozszerzenie nie są zarządzane przez Blockstudio. Blok Blockstudio bez pól zwraca [].
Funkcja wykonuje tę samą transformację co renderowanie, ma więc takie same skutki uboczne: pola plików odpytują o załączniki, pole bloku, które nie zwraca data, renderuje wskazany blok, a filtr blockstudio/blocks/attributes/render jest uruchamiany dla każdej wartości. Funkcja nie renderuje własnego szablonu bloku ani nie rozwiązuje innerBlocks; przejdź po nich samodzielnie. Pole kodu zachowuje wygenerowany identyfikator %selector%, który różni się między wywołaniami.
Rozwiązywanie odbywa się w bieżącym kontekście WordPress. Metadane dostępne tylko podczas renderowania, takie jak liczniki bloków i innerBlocks, nie są tworzone; filtry renderowania atrybutów otrzymują nazwę bloku, a nie metadane w pełni wyrenderowanego bloku.
Nie ma opcji odczytu zapisanych wartości bez transformacji. Odczytaj bezpośrednio tablicę attrs lub użyj sprawdzania bs_validate_block().
Puste wartości
Jeśli pole jest puste lub nie wybrano żadnej opcji, wartość atrybutu to false.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
Typy złożone
Pliki
Domyślnie (bez returnFormat lub z "returnFormat": "object") pole plików zwraca tablicę z danymi załącznika. Z "multiple": true zwraca listę takich tablic. Plik, którego załącznik już nie istnieje, jest false.
| Klucz | Opis |
|---|---|
ID |
Identyfikator załącznika. |
title |
Tytuł załącznika. |
alt |
Tekst alternatywny. Jeśli jest pusty, używany jest tytuł załącznika. |
caption |
Podpis. |
description |
Opis. |
href |
Bezpośredni odnośnik do strony załącznika. |
url |
URL pliku. W przypadku listy rozwijanej rozmiaru ("size": true) — URL wybranego rozmiaru. |
sizes |
URL i wymiary każdego zarejestrowanego rozmiaru obrazu, patrz poniżej. |
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 zawiera jeden wpis dla każdego zarejestrowanego rozmiaru obrazu oraz full: URL pod nazwą rozmiaru, a wymiary pod <size>-width i <size>-height. Jeśli załącznik nie ma wygenerowanego rozmiaru WordPress, zwracany jest oryginalny plik wraz z jego wymiarami. Jeśli WordPress nie może rozwiązać obrazu ani podglądu, brakuje klucza sizes. Na przykład PDF bez wygenerowanego podglądu nie ma sizes, ale PDF z metadanymi podglądu może mieć rozmiary obrazu. sizes ma wartość null, gdy nie zarejestrowano żadnych rozmiarów obrazu albo gdy filtr zmienia rozmiary files/sizes. Ten filtr może również skrócić mapę, dlatego przed odczytaniem wymiarów sprawdź, czy dany rozmiar istnieje, tak jak w powyższych przykładach.
Obiekt nie ma kluczy width, height, mime, type ani size. Odczytaj wymiary z sizes lub użyj ID z funkcjami takimi jak wp_get_attachment_image() i get_post_mime_type().
Formaty zwracanych danych
returnFormat zmienia wartość zwracaną przez pole:
returnFormat |
Wartość |
|---|---|
"object" (domyślnie) |
Opisana powyżej tablica. |
"id" |
Identyfikator załącznika w zapisanej postaci lub lista identyfikatorów z "multiple": true. |
"url" |
URL jako ciąg znaków lub lista adresów URL z "multiple": true. Obrazy używają rozmiaru ustawionego przez returnSize (domyślnie full), pozostałe pliki — własnego URL pliku. |
Łącze
Pole łącza zwraca obiekt zawierający klucz URL i atrybuty:
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 %}
Ikona
Pole ikony zwraca obiekt z kluczami set, subSet i icon. Użyj funkcji pomocniczych bs_render_icon() i bs_icon(), aby wyświetlić 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() bezpośrednio wypisuje SVG. bs_icon() zwraca je jako ciąg.
Atrybuty
Typ pola atrybutów zwraca tablicę par {attribute, value} do renderowania jako atrybuty HTML. Użyj bs_render_data_attributes(), aby je wyświetlić:
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() bezpośrednio wypisuje atrybuty. bs_data_attributes() zwraca ciąg.
Grupa
Identyfikatory atrybutów podrzędnych w polach grupy otrzymują prefiks z nazwą grupy. Użyj bs_get_group(), aby wyodrębnić pola grupy do przejrzystej tablicy:
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>
Usuwa to prefiks grupy z kluczy atrybutów. Na przykład $a['settings_title'] zmienia się w $group['title'].
Ta funkcja pomocnicza działa również, gdy grupa pochodzi z ponownie użytego pola niestandardowego:
{
"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>
Pole powtarzalne
Iteruj po elementach pola powtarzalnego:
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 %}