Compunerea șabloanelor cu etichete de blocuri
După ce un proiect are câteva blocuri, șabloanele încep să aibă nevoie unele de altele. Un bloc de funcționalități vrea să afișeze trei carduri. O pagină de prezentare are nevoie de o secțiune cu un buton în interior. Puteți apela bs_render_block() pentru fiecare dintre ele, dar un șablon plin de apeluri PHP cu tablouri imbricate este greu de citit și și mai greu de imbricat.
Etichetele de bloc vă permit să scrieți un bloc acolo unde trebuie să apară rezultatul său, sub forma unei etichete HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
Aceeași etichetă înseamnă două lucruri diferite, în funcție de locul în care este scrisă. Într-un șablon de bloc sau în conținutul unei postări, este înlocuită cu HTML randat al blocului. Într-o pagină, un model sau sursa unui Site Template, devine un bloc WordPress real, care apare în editor. Acest ghid creează câteva blocuri, le compune în ambele moduri, adaugă un prefix de proiect pentru nume mai scurte, apoi arată cum se migrează aceste forme prescurtate la scrierea portabilă.
Blocurile
Sunt suficiente trei blocuri mici. Un card cu două câmpuri:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/card",
"title": "Card",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title", "default": "" },
{ "id": "text", "type": "textarea", "label": "Text", "default": "" }
]
}
}
<article useBlockProps class="acme-card">
<h3><?php echo esc_html( $a['title'] ); ?></h3>
<p><?php echo esc_html( $a['text'] ); ?></p>
</article>
O secțiune care încadrează orice conținut plasat în interiorul ei, cu un câmp heading declarat la fel ca cel al cardului:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Și un buton într-un al doilea spațiu de nume, acme-ui/button, cu câmpurile label și href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Etichete în interiorul unui șablon de bloc
Etichetele sunt randate automat în șabloanele de bloc. Nu este nevoie de nicio setare. Un bloc de funcționalități poate afișa direct două carduri și un separator de bază:
<div useBlockProps class="acme-features">
<bs:acme-card title="Fast" text="Rendered on the server." />
<block name="acme/card" title="Typed" text="Fields come from block.json." />
<block name="core/separator" />
</div>
Randarea lui acme/features produce:
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Typed</h3>
<p>Fields come from block.json.</p>
</article>
<hr class="wp-block-separator has-alpha-channel-opacity">
</div>
Fiecare bloc Blockstudio din rezultat este precedat de un comentariu <!--blockstudio/namespace/slug-->. Bufferul paginii îl elimină din răspuns; pentru rezultate care ocolesc bufferul, folosiți bs_strip_render_markers().
Cele două sintaxe sunt echivalente. <bs:acme-card> codifică numele blocului în etichetă, iar <block name="acme/card"> îl transmite ca atribut. Fiecare alt atribut devine o valoare de câmp, astfel că title ajunge în șablonul cardului ca $a['title']. Funcționează și blocurile de bază, randate prin WordPress cu randerele de bloc încorporate.
Etichete pereche și conținut interior
O etichetă pereche transmite blocului elementele copil. Pentru un bloc Blockstudio, acestea completează <InnerBlocks />, iar etichetele imbricate în interior sunt randate mai întâi:
<bs:acme-section heading="Why Acme">
<bs:acme-card title="Fast" text="Rendered on the server." />
<bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
<h2>Why Acme</h2>
<div>
<!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
<h3>Fast</h3>
<p>Rendered on the server.</p>
</article>
<!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>
</div>
</section>
Cum devine numele unei etichete numele unui bloc
Numele unei etichete <bs:> nu conține o bară oblică, așa că Blockstudio caută un nume. Înlocuiește pe rând fiecare cratimă cu o bară oblică, de la stânga la dreapta, și folosește primul candidat înregistrat. <bs:acme-card> se rezolvă la acme/card de la prima încercare. <bs:acme-ui-button> încearcă acme/ui-button, nu găsește nimic, apoi se rezolvă la acme-ui/button. Prin urmare, spațiile de nume care conțin cratime funcționează fără configurare, atât timp cât ambii candidați nu există în același timp.
Nume mai scurte cu prefixe
<bs:acme-ui-button> este precis, dar lung. Un prefix de proiect asociază un prefix scurt de etichetă cu unul sau mai multe spații de nume. Configurați-l în blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Sau înregistrați aceeași mapare din PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Acum, <acme-card> se rezolvă la acme/card, iar <ui-button> la acme-ui/button. Când un prefix enumeră mai multe spații de nume, acestea sunt încercate în ordine și câștigă primul bloc înregistrat, ceea ce permite unui bloc de proiect să aibă prioritate față de un bloc de bibliotecă cu aceeași denumire.
Prefixele se pot și compune. <acme-ui-button> încearcă mai întâi acme/ui-button. Blocul respectiv nu există, iar restul etichetei, ui-button, este el însuși o etichetă de prefix înregistrată, așa că rezolvarea continuă cu acme-ui/button. O potrivire directă are întotdeauna prioritate față de una imbricată.
<bs:acme-section heading="Why Acme">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
Acest lucru randează exact același HTML ca versiunea canonică de mai sus.
Prefixele respectă câteva reguli:
- Un prefix conține litere mici și cifre, începe cu o literă și nu conține cratime.
- O etichetă cu prefix care nu se rezolvă la niciun bloc înregistrat rămâne nemodificată în rezultat, așa că
<acme-missing title="x" />rămâne exact cum a fost scrisă. - Aliasurile exacte din filtrul
blockstudio/block_tags/tag_aliasesau prioritate față de prefixe. Un alias asociază o etichetă cu cratimă unui bloc; de exemplu,$aliases['acme-cta'] = 'acme-ui/button';face ca<acme-cta>să randeze butonul.
Etichetele cu prefix și aliasurile sunt randate în șabloanele de bloc alături de etichetele <bs:> și <block> din Blockstudio 7.5.
Atribute
Atributele care corespund unui ID de câmp devin valori de câmp. Două prefixe au alt rol:
- Atributele
data-*sunt copiate pe elementul rădăcină al blocului randat. - Atributele
html-*sunt copiate pe elementul rădăcină fără prefix, astfel încâthtml-id="intro"devineid="intro".
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
<article data-track="card" id="intro" class="featured">
<h3>Hi</h3>
<p>There</p>
</article>
html-class setează atributul, nu adaugă la valoarea sa: clasele acme-card wp-block-acme-card proprii ale blocului dispar. Dacă cel care apelează ar trebui să adauge clase blocului, declarați un câmp pentru ele și combinați-le în șablon.
Orice alt atribut care nu este un câmp declarat este eliminat. Un class="wide" simplu pe <bs:acme-card> randează cardul fără acel atribut. Blockstudio 7.7 raportează astfel de atribute printr-o notificare _doing_it_wrong() când WP_DEBUG este activat.
Aceleași etichete în sursele paginilor
În paginile bazate pe fișiere, în modele și în Site Templates, etichetele nu sunt randate. La analizarea sursei, ele sunt convertite în blocuri, astfel încât apar în editor. Această sursă de pagină:
<bs:acme-section heading="Why Acme">
<p>Everything below is a real block.</p>
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
se analizează în acest marcaj de bloc (cu întreruperi de rând adăugate pentru lizibilitate):
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->
Valorile câmpurilor ajung sub blockstudio.attributes, locul în care blocurile Blockstudio le păstrează, iar paragraful și ambele blocuri interioare devin blocuri interioare ale secțiunii. Prefixele și aliasurile sunt rezolvate aici la fel ca în șabloane.
Etichete în conținutul postărilor
Conținutul scris în editor sau stocat în widgeturi nu este scanat implicit. Activați randarea la nivel de pagină în blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Etichetele din the_content și widget_text sunt apoi randate cu prioritatea 5. Aceeași opțiune înregistrează un filtru pentru randarea etichetelor în orice șir:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Limitați etichetele care pot fi randate cu modelele allow și deny, care acceptă metacaractere fnmatch() și se aplică tuturor sintaxelor și ambelor moduri de randare:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Cu regula respectivă activă, <acme-ui-button> și <bs:acme-ui-button> rămân nerandate în rezultat. deny are prioritate față de allow. Filtrele blockstudio/block_tags/allow și blockstudio/block_tags/deny modifică aceleași liste din PHP.
Analiza verifică scrierea canonică
Extensia PHPStan validează etichetele de bloc în șabloanele PHP, Twig și Blade. Un nume de câmp sau de bloc scris greșit este raportat împreună cu blocul la care s-a rezolvat:
3 Block tag "acme/card" has unknown attribute "txt" in index.php
🪪 blockstudio.blockTag.attribute
4 Block tag references unknown block "acme/cards" in index.php
🪪 blockstudio.blockTag.unknown
În 7.6, aceasta acoperă etichetele <bs:> și <block>. O etichetă cu prefix, precum <acme-card txt="...">, nu este verificată. Blockstudio 7.7 extinde regula la etichetele cu prefix, sursele paginilor și elementele HTML mapate, iar indicația sa enumeră atributele globale pe care le poate transmite o etichetă.
Migrarea formelor prescurtate la scrierea canonică
Etichetele cu prefix și aliasurile sunt o facilitate pentru proiect. Ele sunt rezolvate doar acolo unde sunt încărcate filtrele și setările proiectului, așa că un șablon copiat într-un alt proiect, într-o bibliotecă de blocuri sau în contextul unui agent de programare își pierde semnificația. <bs:namespace-slug> înregistrează numele real al blocului și este rezolvat peste tot, motiv pentru care exemplele, diagnosticele și rezultatele generate proprii Blockstudio îl folosesc.
O comandă independentă rescrie formele prescurtate în acea scriere. Să luăm un proiect ale cărui surse încă folosesc forme scurte, inclusiv un alias, o etichetă pentru un bloc care nu mai există și un exemplu dintr-un fragment de cod:
<div useBlockProps class="acme-features">
<acme-card title="Fast" text="Rendered on the server." />
<acme-ui-button label="Get started" href="/start" />
</div>
<acme-section heading="Why Acme">
<acme-cta label="Talk to us" href="/contact" />
<acme-quote text="Missing block" />
</acme-section>
<pre><code><acme-card /> <acme-card title="Example" /></code></pre>
Comanda nu încarcă WordPress, așa că preia configurația proiectului ca fișiere JSON păstrate în afara arborelui scanat:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Începeți cu o simulare, care este și opțiunea implicită:
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
--root="$PWD" \
--prefix-map=/tmp/acme-tags/prefixes.json \
--known-blocks=/tmp/acme-tags/blocks.json \
--aliases=/tmp/acme-tags/aliases.json \
--report=/tmp/acme-tags/report.json \
--dry-run
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.
Raportul enumeră fiecare asociere pe care ar aplica-o și fiecare caz pentru care nu va ghici:
{
"mappings": [
{ "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
{ "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
{ "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
{ "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
],
"unknown": [
{ "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
],
"manual": [
{ "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
]
}
Raportul este prescurtat aici. El înregistrează și configurația, precum și valorile hash înainte și după, pentru fiecare fișier. Etichetele de deschidere și închidere ale secțiunii sunt numărate ca două apariții. acme-quote corespunde prefixului acme, dar nu denumește niciun bloc cunoscut, așa că este necunoscut. acme-card din <pre><code> este un exemplu, nu marcaj, deci este semnalat pentru verificare manuală și nu este rescris niciodată; la fel se întâmplă cu comentariile HTML și codul inline.
Aplicarea este refuzată cât timp rămân etichete necunoscute, ambigue sau dinamice:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Comanda se încheie cu 2. Corectați eticheta necunoscută, aici prin eliminarea ei, și rulați cu --apply în loc de --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Se schimbă doar numele etichetelor. Atributele sunt păstrate byte cu byte:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Dacă rulați din nou simularea asupra rezultatului, raportul indică 0 changed, 0 replacements. Prefixele pot rămâne înregistrate ulterior, astfel încât nimic nu se strică în ramurile care încă folosesc forma scurtă.
Pașii următori
- Randare: sintaxa completă a etichetelor, randatoare personalizate și analizatorul.
- Setări: fiecare opțiune
blockTags. - Crearea paginilor bazate pe fișiere: surse de pagină în care etichetele devin blocuri editabile.
- Migrarea etichetelor de bloc: toate opțiunile comenzii de migrare.
- Șabloane verificate cu PHPStan: rularea analizei care validează etichetele.