Przejdź do treści

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

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

Twig

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:

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

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

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'] ?? '');
}

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 min zawiera 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 returnFormat ustawionym na label zwraca 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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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

Pole łącza zwraca obiekt zawierający klucz URL i atrybuty:

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 %}

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

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

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:

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>

Pole powtarzalne

Iteruj po elementach pola powtarzalnego:

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 %}

Przepisy na wzorce pól