Pāriet uz saturu

Atribūtu renderēšana

Veidņu failos visiem atribūtiem var piekļūt, izmantojot mainīgos $attributes vai $a un attiecīgo lauka 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>

Atribūtu rakstīšana programmatiski

Redaktorā saglabātās vērtības tiek ievietotas blockstudio.attributes. Jebkurš process, kas raksta bloku ārpus redaktora, piemēram, REST API, WP-CLI, satura migrācija vai MCP serveris, nosaka bloku, izmantojot atribūtus, ko Blockstudio reģistrē WP_Block_Type, un raksta tos augšējā līmenī. Renderējas abas struktūras:

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

No augšējā līmeņa tiek nolasīti tikai bloka deklarētie ID, tāpēc WordPress atribūti, piemēram, anchor, className, lock, metadata un style, netiek izmantoti kā lauku vērtības. Ja viens un tas pats ID ir norādīts abās vietās, priekšroka tiek dota ligzdotajai vērtībai.

Atribūtu nolasīšana programmā

Kodam, kas darbojas ārpus veidnes, piemēram, strukturētajiem datiem vietnē save_post, eksportam, meklēšanas indeksēšanai vai render_block filtram, bieži ir vajadzīgas saglabāta bloka vērtības tā, kā tās redzamas veidnē. bs_block_values() atgriež šīs vērtības, nerenderējot bloku. Izsauciet to pēc bloka reģistrēšanas (init vai vēlāk), nododot pilnu attrs masīvu no 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'] ?? '');
}

Rezultāts ir veidnes $a masīvs, kurā atslēgas ir lauku ID:

  • Tiek lietotas lauku noklusējuma vērtības, un atkārtotājam ar min ir sākotnējās rindas.
  • Augšējā līmeņa vērtības tiek apvienotas ar blockstudio.attributes, un ligzdotajai vērtībai ir priekšroka. Tiek nolasīti tikai augšējā līmenī deklarētie ID, un WordPress izmet augšējā līmeņa vērtību, kas neatbilst lauka reģistrētajam tipam, piemēram, atlasē izmantotu virkni, gluži tāpat kā renderēšanas laikā.
  • Tiek iekļauti atbilstoši paplašinājumi kopā ar to noklusējuma vērtībām. Pamatbloka vai trešās puses bloka paplašinājumā tiek nolasīts tikai blockstudio.attributes, gluži tāpat kā renderēšanas laikā.
  • Tiek lietoti atgriešanas formāti, tāpēc atlase ar returnFormat, kura vērtība ir label, atgriež etiķeti, bet failu lauks — pielikuma datus.
  • Atspējotie un tukšie lauki tiek false, tāpat kā veidnē.

null nozīmē, ka bloku vai paplašinājumu nepārvalda Blockstudio. Blockstudio bloks bez laukiem atgriež [].

Funkcija izpilda to pašu transformāciju, ko renderēšana, tāpēc tai ir tādas pašas blaknes: failu lauki vaicā pielikumus, bloka lauks, kas neatgriež data, renderē norādīto bloku, un katrai vērtībai tiek izpildīts filtrs blockstudio/blocks/attributes/render. Funkcija nerenderē paša bloka veidni un neatrisina innerBlocks; apstaigājiet tos paši. Koda lauks saglabā ģenerētu %selector% ID, kas katrā izsaukumā atšķiras.

Vērtību atrisināšanai tiek izmantots pašreizējais WordPress konteksts. Renderēšanai paredzētie metadati, piemēram, bloku skaitītāji un innerBlocks, netiek izveidoti; atribūtu renderēšanas filtri saņem bloka nosaukumu, nevis pilnībā renderēta bloka metadatus.

Nav iespējams iegūt saglabātās vērtības bez transformācijas. Nolasiet attrs masīvu tieši vai izmantojiet bs_validate_block()pārbaudīt tās.

Tukšas vērtības

Ja lauks ir tukšs vai nav atlasīta neviena opcija, atribūtu vērtības atgriež 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 %}

Sarežģīti tipi

Faili

Pēc noklusējuma (ja nav returnFormat vai ir "returnFormat": "object") failu lauks atgriež masīvu ar pielikuma datiem. Ja norādīts "multiple": true, tas atgriež šo masīvu sarakstu. Ja faila pielikums vairs nepastāv, atgrieztā vērtība ir false.

Atslēga Apraksts
ID Pielikuma ID.
title Pielikuma nosaukums.
alt Alternatīvais teksts. Ja tas ir tukšs, tiek izmantots pielikuma nosaukums.
caption Paraksts.
description Apraksts.
href Pielikuma lapas pastāvīgā saite.
url Faila URL. Ja izmantota izmēra nolaižamā izvēlne ("size": true), atlasītā izmēra URL.
sizes Katram reģistrētajam attēla izmēram atbilstošais URL un tā izmēri; skatiet tālāk.

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 ir ieraksts katram reģistrētajam attēla izmēram un arī full: URL zem izmēra nosaukuma, bet izmēri — zem <size>-width un <size>-height. Ja pielikumam nav ģenerēts izmērs WordPress, tiek izmantots sākotnējais fails ar tā izmēriem. Ja WordPress nevar atrast attēlu vai priekšskatījumu, sizes atslēgas nav. Piemēram, PDF failam bez ģenerēta priekšskatījuma nav sizes, bet PDF failam ar priekšskatījuma metadatiem var būt attēlu izmēri. sizes ir null, ja nav reģistrētu attēlu izmēru vai ja filtrs files/sizes tiek atspējots ar . Šis filtrs var arī saīsināt karti, tāpēc pirms izmēru nolasīšanas pārbaudiet, vai attiecīgais izmērs ir pieejams, kā parādīts iepriekš minētajos piemēros.

Objektam nav atslēgu width, height, mime, type vai size. Izmērus nolasiet no sizes vai izmantojiet ID kopā ar tādām funkcijām kā wp_get_attachment_image() un get_post_mime_type().

Atgriešanas formāti

returnFormat maina lauka atgriezto vērtību:

returnFormat Vērtība
"object" (pēc noklusējuma) Iepriekš aprakstītais masīvs.
"id" Pielikuma ID saglabātajā formātā vai ID saraksts, ja izmantots "multiple": true.
"url" URL kā virkne vai URL saraksts, ja izmantots "multiple": true. Attēliem tiek izmantots ar returnSize iestatītais izmērs (pēc noklusējuma full), bet citiem failiem — to faila URL.

Saites lauks atgriež objektu ar atslēgām URL un atribūtiem:

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

Ikonas lauks atgriež objektu ar atslēgām set, subSet un icon. Izmantojiet palīgfunkcijas bs_render_icon() un bs_icon(), lai izvadītu 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() tieši izvada SVG. bs_icon() atgriež to kā virkni.

Atribūti

Atribūtu lauka tips atgriež {attribute, value} pāru masīvu, ko var renderēt kā HTML atribūtus. Izmantojiet bs_render_data_attributes(), lai tos izvadītu:

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() tieši izvada atribūtus. bs_data_attributes() atgriež virkni.

Grupa

Grupu lauki pievieno pakārtoto atribūtu ID priekšā grupas nosaukumu. Izmantojiet bs_get_group(), lai izgūtu grupas laukus tīrā masīvā:

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>

Tas noņem grupas prefiksu no atribūtu atslēgām. Piemēram, $a['settings_title'] kļūst par $group['title'].

Palīgfunkcija darbojas arī tad, ja grupa iegūta no atkārtoti izmantota pielāgota lauka:

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>

Atkārtotājs

Pārlūkojiet atkārtotāja vienumus ciklā:

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

Lauku paraugu rokasgrāmata