Tworzenie szablonów za pomocą znaczników bloków
Gdy projekt zawiera już kilka bloków, szablony zaczynają zależeć od siebie. Blok
funkcji chce wyświetlić trzy karty. Strona docelowa potrzebuje sekcji z
przyciskiem wewnątrz. Możesz wywołać bs_render_block() dla każdego bloku, ale
szablon pełen wywołań PHP z zagnieżdżonymi tablicami trudno czytać i jeszcze trudniej
zagnieżdżać.
Znaczniki bloków pozwalają umieścić blok tam, gdzie ma pojawić się jego wynik, jako znacznik HTML:
<bs:acme-card title="Fast" text="Rendered on the server." />
Ten sam znacznik oznacza dwie różne rzeczy w zależności od miejsca użycia. W szablonie bloku lub treści wpisu zostaje zastąpiony wyrenderowanym HTML bloku. Na stronie, wzorcu lub w źródle szablonu witryny staje się rzeczywistym blokiem WordPress, który pojawia się w edytorze. W tym przewodniku utworzymy kilka bloków, połączymy je na oba sposoby, dodamy prefiks projektu dla krótszych nazw, a następnie pokażemy, jak przywrócić skrótom przenośną postać.
Bloki
Wystarczą trzy niewielkie bloki. Karta z dwoma polami:
{
"$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>
Sekcja, która obejmuje dowolną umieszczoną w niej zawartość, z polem heading
zadeklarowanym tak samo jak pole karty:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
Oraz przycisk w drugiej przestrzeni nazw, acme-ui/button, z polami label i href:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
Znaczniki w szablonie bloku
Szablony bloków automatycznie renderują znaczniki. Nie trzeba nic konfigurować. Blok funkcji może bezpośrednio wyświetlić dwie karty i separator rdzenia:
<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>
Wyrenderowanie acme/features daje:
<!--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>
Każdy blok Blockstudio w wyniku jest poprzedzony komentarzem <!--blockstudio/namespace/slug-->. Bufor strony usuwa go z odpowiedzi; w przypadku wyniku pomijającego bufor użyj bs_strip_render_markers(). Obie składnie są równoważne. <bs:acme-card> koduje nazwę bloku w znaczniku, a <block name="acme/card"> przekazuje ją jako atrybut. Każdy inny atrybut staje się wartością pola, więc title trafia do szablonu karty jako $a['title']. Działają też bloki podstawowe, renderowane za pomocą WordPress i wbudowanych rendererów bloków.
Znaczniki otwierające i zamykające oraz zawartość wewnętrzna
Znacznik otwierający i zamykający przekazuje elementy potomne do bloku. W bloku Blockstudio
wypełniają one <InnerBlocks />, a zagnieżdżone znaczniki są renderowane jako pierwsze:
<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>
Jak nazwa znacznika staje się nazwą bloku
Nazwa znacznika <bs:> nie zawiera ukośnika, więc Blockstudio go wyszukuje. Po kolei
zastępuje każdy łącznik ukośnikiem, od lewej do prawej, i wybiera pierwszego zarejestrowanego kandydata.
<bs:acme-card> zostaje rozpoznane jako acme/card za pierwszym razem.
<bs:acme-ui-button> sprawdza acme/ui-button, nie znajduje niczego, a następnie rozpoznaje
acme-ui/button. Przestrzenie nazw zawierające łączniki działają więc bez
konfiguracji, o ile oba warianty nie są jednocześnie zarejestrowane.
Krótsze nazwy z prefiksami
<bs:acme-ui-button> jest precyzyjne, ale długie. Prefiks projektu przypisuje krótki prefiks znacznika
do jednej lub kilku przestrzeni nazw. Skonfiguruj go w blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
Możesz też zarejestrować tę samą mapę z poziomu PHP:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
Teraz <acme-card> zostaje rozpoznane jako acme/card, a <ui-button> jako
acme-ui/button. Jeśli prefiks zawiera kilka przestrzeni nazw, są one sprawdzane
po kolei, a pierwszeństwo ma pierwszy znaleziony blok. Dzięki temu blok projektu może przesłonić
blok biblioteki o tym samym uproszczonym identyfikatorze.
Prefiksy można też łączyć. <acme-ui-button> najpierw sprawdza acme/ui-button. Tego
bloku nie ma, a pozostała część znacznika, ui-button, jest sama w sobie
zarejestrowanym znacznikiem prefiksu, więc rozpoznawanie przechodzi do acme-ui/button. Dopasowanie
bezpośrednie ma zawsze pierwszeństwo przed zagnieżdżonym.
<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>
Renderuje dokładnie to samo HTML co przedstawiona wyżej wersja kanoniczna.
Prefiksy podlegają kilku zasadom:
- Prefiks składa się z małych liter i cyfr, zaczyna się od litery i nie zawiera łączników.
- Znacznik z prefiksem, który nie wskazuje zarejestrowanego bloku, pozostaje w wyniku
bez zmian.
<acme-missing title="x" />zachowuje więc pierwotną postać. - Dokładne aliasy z filtra
blockstudio/block_tags/tag_aliasesmają pierwszeństwo przed prefiksami. Alias przypisuje jeden znacznik z łącznikiem do jednego bloku, na przykład$aliases['acme-cta'] = 'acme-ui/button';sprawia, że<acme-cta>renderuje przycisk.
Znaczniki z prefiksami i aliasami są renderowane w szablonach bloków razem ze znacznikami <bs:> i <block>
z Blockstudio 7.5.
Atrybuty
Atrybuty pasujące do identyfikatora pola stają się jego wartościami. Dwa prefiksy służą do czegoś innego:
- Atrybuty
data-*są kopiowane do elementu głównego wyrenderowanego bloku. - Atrybuty
html-*są kopiowane do elementu głównego z pominiętym prefiksem, więchtml-id="intro"staje sięid="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 ustawia atrybut, nie dopisuje do niego wartości, więc własne klasy acme-card wp-block-acme-card
bloku znikają. Jeśli wywołujący ma dodawać klasy
blokowi, zadeklaruj dla nich pole i połącz je w szablonie.
Każdy inny atrybut, który nie jest zadeklarowanym polem, zostaje pominięty. Zwykłe
class="wide" na <bs:acme-card> renderuje kartę bez tego atrybutu. Blockstudio 7.7
zgłasza takie atrybuty jako powiadomienie _doing_it_wrong(), gdy włączono WP_DEBUG.
Te same znaczniki w źródłach stron
W stronach opartych na plikach, wzorcach i szablonach witryny znaczniki nie są renderowane. Podczas przetwarzania źródła są zamieniane na bloki, więc pojawiają się w edytorze. Oto źródło strony:
<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>
Jest przetwarzane na następujący znacznik bloku (dla czytelności dodano podziały wierszy):
<!-- 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 -->
Wartości pól trafiają do blockstudio.attributes, gdzie bloki Blockstudio je przechowują, a akapit i oba
bloki wewnętrzne stają się blokami wewnętrznymi sekcji. Prefiksy i aliasy są tu rozpoznawane
na tych samych zasadach co w szablonach.
Znaczniki w treści wpisu
Zawartość wpisana w edytorze lub zapisana w widżetach nie jest domyślnie skanowana.
Włącz renderowanie na poziomie strony w blockstudio.json:
{
"blockTags": {
"enabled": true
}
}
Znaczniki w the_content i widget_text są wtedy renderowane z priorytetem 5. To samo
ustawienie rejestruje filtr renderujący znaczniki w dowolnym ciągu znaków:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
Ogranicz znaczniki, które mogą być renderowane, za pomocą wzorców allow i deny, obsługujących symbole wieloznaczne fnmatch(). Reguły te obowiązują we wszystkich składniach i obu trybach renderowania:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
Po wprowadzeniu tej reguły <acme-ui-button> i <bs:acme-ui-button> pozostają w wyniku
bez renderowania. deny ma pierwszeństwo przed allow. Filtry blockstudio/block_tags/allow i blockstudio/block_tags/deny zmieniają te same listy z poziomu PHP.
Analiza sprawdza zapis kanoniczny
Rozszerzenie PHPStan sprawdza znaczniki bloków w szablonach PHP, Twig i Blade. Błędnie zapisana nazwa pola lub bloku jest zgłaszana wraz z nazwą rozpoznanego bloku:
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
W 7.6 obejmuje to znaczniki <bs:> i <block>. Znacznik z prefiksem, taki jak
<acme-card txt="...">, nie jest sprawdzany. Wersja Blockstudio 7.7 rozszerza tę regułę na
znaczniki z prefiksami, źródła stron i mapowane elementy HTML. Podpowiedź zawiera
atrybuty globalne, które znacznik może przekazywać dalej.
Przywracanie skrótom zapisu kanonicznego
Znaczniki z prefiksami i aliasami ułatwiają pracę w projekcie. Są rozpoznawane tylko wtedy,
gdy wczytano filtry i ustawienia projektu, więc szablon skopiowany do innego
projektu, biblioteki bloków lub kontekstu agenta programistycznego traci swoje znaczenie.
<bs:namespace-slug> zapisuje prawdziwą nazwę bloku i działa wszędzie,
dlatego własne przykłady, komunikaty diagnostyczne i generowane dane wyjściowe Blockstudio używają
tej postaci.
Samodzielne polecenie zamienia skróty na zapis kanoniczny. Załóżmy, że źródła projektu nadal zawierają krótkie formy, w tym alias, znacznik bloku, który już nie istnieje, oraz przykład w fragmencie kodu:
<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>
Polecenie nie wczytuje WordPress, dlatego pobiera konfigurację projektu jako pliki JSON przechowywane poza skanowanym drzewem:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
Najpierw uruchom próbę bez wprowadzania zmian — jest to też tryb domyślny:
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.
Raport zawiera każde mapowanie, które zostałoby zastosowane, oraz każdy przypadek, którego polecenie nie rozstrzygnie:
{
"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" }
]
}
Raport został tu skrócony. Zawiera też konfigurację i hashe plików przed zmianami i po nich.
Znaczniki otwierający i zamykający sekcję są liczone jako dwa wystąpienia. acme-quote pasuje do prefiksu acme, ale nie wskazuje żadnego znanego bloku,
więc jest nieznany. acme-card wewnątrz <pre><code> to przykład, a nie znacznik,
dlatego wymaga ręcznego sprawdzenia i nigdy nie jest przepisywany; to samo dotyczy komentarzy
HTML i kodu w tekście.
Nie można zastosować zmian, dopóki pozostają nieznane, niejednoznaczne lub dynamiczne znaczniki:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
Polecenie kończy działanie z kodem 2. Popraw nieznany znacznik — w tym przykładzie usuń go — i uruchom polecenie z --apply zamiast --dry-run:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
Zmieniają się tylko nazwy znaczników. Atrybuty pozostają zachowane bajt w bajt:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
Ponowne uruchomienie próby na wyniku zgłasza 0 changed, 0 replacements. Prefiksy można pozostawić zarejestrowane, więc nic się nie zepsuje, gdy inne gałęzie nadal używają krótkiej formy.
Następne kroki
- Renderowanie: pełna składnia znaczników, własne renderery i parser.
- Ustawienia: każda opcja
blockTags. - Tworzenie stron opartych na plikach: źródła stron, w których znaczniki stają się edytowalnymi blokami.
- Migracja znaczników bloków: wszystkie opcje polecenia migracji.
- Sprawdzane szablony z PHPStan: uruchamianie analizy sprawdzającej znaczniki.