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
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
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:
// 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():
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
minir 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 irlabel, 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 if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
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 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 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. |
Saite
Saites lauks atgriež objektu ar atslēgām URL un atribūtiem:
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
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 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() 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
<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() 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 $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>
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:
{
"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>
Atkārtotājs
Pārlūkojiet atkārtotāja vienumus ciklā:
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 %}