使用区块标签组合模板
当项目中有几个区块后,模板之间就会开始相互依赖。一个功能区块想要输出三张卡片;一个落地页想要包含带按钮的版块。你可以为每个区块调用bs_render_block(),但塞满PHP调用和嵌套数组的模板很难阅读,也更难继续嵌套。
区块标签可以让你在输出内容所在的位置编写区块,形式为 HTML 标签:
<bs:acme-card title="Fast" text="Rendered on the server." />
同一个标签会根据书写位置表示不同的含义。在区块模板或文章内容中,它会替换为该区块渲染后的HTML。在页面、样式或 Site Template 源文件中,它会变成编辑器中显示的真实WordPress区块。本指南将创建几个区块,演示两种组合方式,为较短名称添加项目前缀,然后说明如何将这些简写迁移回可移植的拼写。
区块
只需三个小区块。先看一个带两个字段的卡片:
{
"$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>
一个版块,用来包裹放置在其中的任何内容,并声明一个heading字段,其方式与卡片字段相同:
<section useBlockProps class="acme-section">
<h2><?php echo esc_html( $a['heading'] ); ?></h2>
<InnerBlocks />
</section>
另一个命名空间acme-ui/button中的按钮,带有label和href字段:
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>
区块模板中的标签
区块模板会自动渲染标签,无需设置。功能区块可以直接输出两张卡片和一个核心分隔符:
<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>
渲染acme/features会生成:
<!--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>
输出中的每个 Blockstudio 区块前面都有一条 <!--blockstudio/namespace/slug--> 注释。页面缓冲区会从响应中移除这条注释;对于跳过缓冲区的输出,请使用 bs_strip_render_markers()。
这两种语法等效。<bs:acme-card> 会将区块名称编码在标签中,而 <block name="acme/card"> 则将其作为属性传递。其他所有属性都会成为字段值,因此 title 会以 $a['title'] 的形式传递给卡片模板。核心区块也适用,会通过 WordPress 和内置区块渲染器进行渲染。
成对标签和内部内容
成对标签会将其子级传递给区块。对于Blockstudio区块,它们会填入<InnerBlocks />,其中嵌套的标签会先被渲染:
<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>
标签名称如何转换为区块名称
<bs:>标签名称中没有斜杠,因此Blockstudio会查找匹配项。它从左到右依次将每个连字符替换为斜杠,并使用第一个已注册的候选项。<bs:acme-card>第一次尝试就会解析为acme/card。<bs:acme-ui-button>会尝试acme/ui-button,找不到匹配项后,再解析为acme-ui/button。因此,只要两个候选项不同时存在,包含连字符的命名空间无需任何配置即可使用。
使用前缀缩短名称
<bs:acme-ui-button>准确但很长。项目前缀可以将短标签前缀映射到一个或多个命名空间。请在blockstudio.json中配置:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"blockTags": {
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
}
}
}
也可以通过PHP注册相同的映射:
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
$prefixes['acme'] = array( 'acme' );
$prefixes['ui'] = array( 'acme-ui' );
return $prefixes;
} );
现在,<acme-card>会解析为acme/card,<ui-button>会解析为acme-ui/button。如果一个前缀列出多个命名空间,系统会按顺序尝试,并采用第一个已注册的区块,因此项目区块可以覆盖具有相同 slug 的库区块。
前缀也可以组合。<acme-ui-button>会先尝试acme/ui-button。该区块不存在,而标签的其余部分ui-button本身也是一个已注册的前缀标签,因此解析会继续尝试acme-ui/button。直接匹配始终优先于嵌套匹配。
<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>
这会渲染出与上方规范版本完全相同的HTML。
前缀有几条规则:
- 前缀只能包含小写字母和数字,必须以字母开头,且不能包含连字符。
- 带前缀的标签如果无法解析到已注册的区块,就会原样保留在输出中,因此
<acme-missing title="x" />会保持原样。 blockstudio/block_tags/tag_aliases过滤器中的精确别名优先于前缀。别名会将一个带连字符的标签映射到一个区块,例如,$aliases['acme-cta'] = 'acme-ui/button';会让<acme-cta>渲染出按钮。
前缀标签和别名标签会与来自 Blockstudio 7.5 的 <bs:> 和 <block> 标签一起在区块模板中渲染。
属性
与字段 ID 匹配的属性会成为字段值。两个前缀有其他用途:
data-*属性会复制到渲染后区块的根元素上。html-*属性会去掉前缀后复制到根元素上,因此html-id="intro"会变为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会设置属性,而不是追加属性:区块自身的acme-card wp-block-acme-card类会消失。如果调用方需要为区块添加类,请为其声明一个字段,并在模板中合并该字段的值。
任何其他未声明为字段的属性都会被丢弃。在<bs:acme-card>上使用普通的class="wide"会渲染卡片,但不包含该属性。启用WP_DEBUG时,Blockstudio 7.7 会通过_doing_it_wrong()提示报告这类属性。
页面源文件中使用相同的标签
在基于文件的页面、样式和 Site Template 中,标签不会被渲染。解析源文件时,它们会转换为区块,因此会显示在编辑器中。以下页面源文件:
<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>
会解析为以下区块标记(为便于阅读添加了换行):
<!-- 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 -->
字段值会存储在blockstudio.attributes下,这是Blockstudio区块保存字段值的位置;段落和两个内部区块则会成为该版块的内部区块。前缀和别名在此处的解析方式与模板中完全相同。
文章内容中的标签
默认情况下,编辑器中编写或存储在小工具中的内容不会经过扫描。在blockstudio.json中启用页面级渲染:
{
"blockTags": {
"enabled": true
}
}
随后,the_content和widget_text中的标签会按优先级5渲染。同一开关还会注册一个过滤器,用于渲染任意字符串中的标签:
$html = apply_filters( 'blockstudio/block_tags/render', $content );
使用allow和deny模式限制可渲染的标签;它们接受fnmatch()通配符,并应用于所有语法和两种渲染模式:
{
"blockTags": {
"enabled": true,
"deny": ["acme-ui/*"]
}
}
应用该规则后,<acme-ui-button>和<bs:acme-ui-button>会原样保留在输出中,不进行渲染。deny优先于allow。blockstudio/block_tags/allow和blockstudio/block_tags/deny过滤器会从PHP更改相同的列表。
分析检查规范拼写
PHPStan扩展会验证PHP、Twig和Blade模板中的区块标签。字段或区块名称拼写错误时,报告中会显示它解析到的区块:
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
在 7.6 中,这会检查<bs:>和<block>标签。像<acme-card txt="...">这样的前缀标签不会经过检查。Blockstudio 7.7 将规则扩展到前缀标签、页面源文件和映射的HTML元素,并会在提示中列出标签可以转发的全局属性。
将简写迁移为规范拼写
前缀标签和别名标签是为项目提供便利的写法。它们只有在加载了项目过滤器和设置的地方才能解析,因此复制到其他项目或区块库中的模板,以及编码代理上下文中的模板,都会失去原有含义。<bs:namespace-slug>记录真实的区块名称并能在任何地方解析,这就是为什么Blockstudio自己的示例、诊断信息和生成的输出都使用它。
一个独立命令可以将简写改写为规范拼写。假设某个项目的源文件仍使用简写,其中包括一个别名、一个已不存在区块的标签,以及代码示例中的一个示例:
<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>
该命令不会加载WordPress,因此会将项目配置作为JSON文件传入;这些文件保存在扫描目录之外:
{ "acme": ["acme"], "ui": ["acme-ui"] }
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
{ "acme-cta": "acme-ui/button" }
先运行试运行;它也是默认模式:
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.
报告会列出将要应用的每个映射,以及不会尝试猜测的情况:
{
"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" }
]
}
此处展示的是精简后的报告。报告还会记录配置和每个文件修改前后的哈希值。版块的开始标签和结束标签会计为两次出现。acme-quote匹配acme前缀,但没有指定已知区块,因此属于未知标签。<pre><code>中的acme-card是示例而不是标记,因此会报告供人工检查,绝不会改写;HTML注释和行内代码也同样如此。
仍有未知、含糊或动态标签时,系统会拒绝应用更改:
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.
命令会以2退出。修复未知标签(此处通过移除它),然后使用--apply而不是--dry-run运行:
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.
只有标签名称会改变。属性会逐字节保留:
<bs:acme-section heading="Why Acme">
<bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>
再次对结果运行试运行后,会报告0 changed, 0 replacements。之后可以继续注册这些前缀,因此其他分支仍使用简写时也不会出问题。
后续步骤
- 渲染:完整的标签语法、自定义渲染器和解析器。
- 设置:每个
blockTags选项。 - 构建基于文件的页面:将标签转换为可编辑区块的页面源文件。
- 区块标签迁移:迁移命令的所有选项。
- 已检查的模板与 PHPStan:运行用于验证标签的分析。