跳转到正文

以编程方式渲染

随着 Gutenberg 成为为客户创建易于编辑网站的主要工具,将网站所需的所有区域都创建为区块是合理的。这种方法适用于大多数用户,但高级用户和特定用例可能需要在编辑器之外使用这些现有区块。

Blockstudio 提供两种以编程方式渲染区块的方法:

  • PHP 函数:使用 bs_render_block 和 bs_block 从 PHP 代码渲染
  • HTML 标签:<bs:block-name> 标签会在页面任意位置替换为区块输出

支持所有 Blockstudio 专属功能,例如内联样式、脚本和作用域样式。

通过这些渲染路径也可以使用 岛屿。使用 bs_render_block()、bs_block() 或区块标签渲染的动态岛屿,会返回与从文章内容渲染的区块相同的占位符标记;响应中存在此标记时,前端运行时也会注入。

结构化组合与完整文档

对于长期运行的工具、预览、导出和组件库,请使用带版本的 Blockstudio\Render API。它接受单个声明或有序列表,并在不输出内容的情况下进行渲染:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

规范化后的标准声明包含四个键:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data、inner、innerBlocks、root、layers 和 example 是输入时的便捷选项,规范化后会移除。嵌套声明会通过同一 Blockstudio 流程递归渲染。

Render::document() 返回 schemaVersion、html、body、blocks、assets、warnings 和 errors。assets 值用于分隔 head、footer、styles、scripts、modules、interactivity、ui 和 tailwind。区块列表和资源会包含所选模板引用的依赖项,但会排除无关资源和仅供编辑器使用的资源。

完整文档可以设置 bodyClasses/bodyAttributes,还可以选择使用 contentElement、contentClasses 和 contentAttributes 包装渲染后的正文。包装器仅限使用安全的元素名称;返回的 body 仍是未经包装的渲染内容。 head 和 footer 选项会在相应位置附加可信文档标记,并包含在返回的资源闭包中。

要围绕已渲染的 HTML 组装文档,请提供已知的根区块名称:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

使用 Render::content()处理序列化的 WordPress区块内容。在一次请求中渲染多个独立文档的使用方应在文档之间调用 Blockstudio\Batch_Render::reset();Canvas::documents()会自动完成这项操作。

在页面之外渲染

Blockstudio 会在其渲染的每个区块前插入一个 <!--blockstudio/namespace/slug--> 注释。在前端页面上,缓冲区会读取这些注释以确定页面中有哪些区块,加载它们的资源,并在发送响应前移除这些注释。

未经过该缓冲区的输出会保留这些注释。这适用于 REST 响应、信息源、AJAX 处理程序,以及在 do_blocks()、Render::content() 或 bs_render_block() 之后存储或发送到其他位置的 HTML。使用 bs_strip_render_markers() 将其移除:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

该函数会移除已注册 Blockstudio 区块的注释,并保持其他内容不变,包括其他 HTML 注释。它匹配页面缓冲区移除的相同标记。请在注册区块后调用(init 或更晚)。

不要剥除仍会输出到经过缓冲的前端页面中的标记。页面需要这些注释来确定要加载哪些区块资源,而 Blockstudio 会在最后自行移除它们。

移除注释不会添加资源。区块 CSS 和 JavaScript 文件仅由页面缓冲区注入。如果使用方也需要这些文件,请使用 bs_block_assets() 或 Render::document()。

检查区块

在注册区块后(init 或更晚)使用 bs_block_fields(),即可获取解析后的字段定义,而无需读取内部注册表:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

返回值是已注册的字段定义数组,其中包括属性筛选器、展开后的自定义字段、覆盖项,以及嵌套的组、选项卡和重复器。没有字段的 Blockstudio 区块会返回 []。结果是副本:修改它不会更改已注册的区块。

这些是定义,不是已保存的值。若要验证已保存的标记,请使用bs_validate_block(),而不是维护单独的字段遍历器。若要描述区块接受的值,请使用bs_block_schema()。WordPress拥有的属性仍单独处理。

扩展添加的字段不属于 bs_block_fields()。使用 bs_block_extension_fields() 获取这些字段。它根据区块名称匹配扩展,因此也适用于核心区块和第三方区块:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

返回值会按扩展注册顺序列出所有匹配扩展的字段定义,结构与 bs_block_fields() 相同。没有匹配扩展的区块会返回 []。扩展值保存在与区块自身字段值相同的 attrs.blockstudio.attributes 对象中,因此所有 ID 共用一个命名空间。如果两个扩展定义了相同的 ID,则会返回两个定义,并编辑同一个值;渲染时,后注册的扩展定义生效。

要读取已保存区块的值(即模板接收到的值),请使用 bs_block_values()。

使用 bs_block_assets() 检查该区块发现的 CSS 和 JavaScript。如需完整的预览文档(包括嵌套区块和共享的运行时依赖项),请按上文所述使用 Render::document()。

验证已存储的值

在注册区块后(init 或更晚)使用 bs_validate_block(),即可在保存程序生成或导入的区块属性前对其进行检查:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

传入完整的 attrs 数组,而不只是 blockstudio.attributes。Blockstudio 渲染也接受顶层的已声明字段;如果同时提供嵌套值,则以嵌套值为准。核心区块和第三方区块的扩展只读取 blockstudio.attributes。空的 Blockstudio 区块属于受管理区块,返回 [],而不是 null。

验证是显式且只读的。它不会渲染模板、更改值、保存文章、查询媒体或运行填充回调。它不会在保存、页面同步或渲染过程中自动运行。它不是净化器、授权检查,也不会检查附件是否存在。

每条检查结果都包含以下稳定键:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

在工具中请使用 code,不要使用翻译后的 message。source 是 block 或 extension。路径使用存储键以及从零开始的重复器行索引或选项索引,且不带前导斜杠。键中的字面 ~ 和 / 会分别转义为 ~0 和 ~1。顶层分组会为其子项添加前缀(cta_title);匿名分组和选项卡不会增加层级。构建器不支持在另一个分组或重复器内带 ID 的分组,因此不接受其键。消息字段没有存储值。文件字段允许使用其 <id>__size 伴随项。 在 Blockstudio 区块的根级,账务记录键以及转发给渲染元素的全局 HTML 属性不属于未知字段。这并不允许在重复器行中使用任意键,也不允许扩展核心区块。

代码 含义 expected
unknown_field 没有保留的字段声明此存储键。 已知存储键。
unknown_option 选项不在已知选项中。 允许的选项值。
wrong_type 存储结构不受此字段支持。 预期的存储类别或类型。
too_few_rows, too_many_rows 已存在的重复器超出其 min 或 max。 行数范围。
definition_conflict 同一键的适用定义要求不同的存储结构。 每个定义的来源和字段类型。
shadowed_value 嵌套值覆盖了不同的顶层字段值。 优先采用的嵌套值。
extension_top_level 模板可以读取顶层值,但扩展绑定无法读取。 其在 blockstudio/attributes 下的必需路径。
unknown_attribute Blockstudio 区块的顶层键不会被渲染路径读取,因此会被丢弃。 已注册的属性名称、扩展字段和 blockstudio。
missing_container attributes、disabled、name 或 editor 存储在顶层,而 blockstudio 缺失。 其在 blockstudio 下的必需路径。
invalid_container blockstudio 或 blockstudio.attributes 不是对象。 object。

unknown_field 查找消息会列出同一层级中编辑距离不超过三次的最接近存储键;未知设置遵循以下规则: This storage key is not declared by the block or its extensions. Did you mean "title"? expected 仍会列出每个已知键。 匹配时不区分大小写,且只考虑该容器中的存储键。 消息会经过翻译;集成应使用 code、path 和 expected,而不是解析消息文本。

Blockstudio 区块的顶层键如果既不是已注册属性(其字段,以及属性 WordPress 为 supports、lock 和 metadata 添加的属性),也不是匹配扩展中的字段、blockstudio、账务记录键或转发的 HTML 属性,就会在模板运行前被丢弃。例如,字段 ID 拼写错误,或存储的 values 对象没有 blockstudio 包装器,这类键会产生一条检查结果,因为区块渲染时不会包含该值。仅携带扩展字段的区块不会检查顶层键。

接受的结构遵循渲染方式:多选项和复选框可包含列表、单个选项对象或导入的标量值(包括数字零)。数字字段接受数字字符串。文件可包含附件 ID、ID 对象、列表或字符串引用。链接和图标值必须是对象;自定义字段类型使用其注册的属性类型。 attributes 字段包含一组键值对,每对都有非空的 attribute 名称和标量 value;可选元数据(如 data.media)会予以保留。

WordPress 会在渲染前验证已注册的顶层属性,因此可能拒绝 blockstudio.attributes 内部接受的结构。例如,"a" 的 radio 值在嵌套对象中有效,但在顶层会被丢弃,因为其注册类型是 object。此类值会产生 wrong_type。 请使用嵌套对象,以匹配编辑器写入的存储结构。

缺失字段不是必填项。空的嵌套值(null、false、''、 [])和已禁用字段不会产生值错误。即使重复器明确为空,也仍会根据 min 进行检查;缺失或已禁用的重复器则不会检查。 如果 WordPress 丢弃了某个空的顶层值并恢复了非空默认值,就会报告该值。嵌套对象中的相同值则可以将其清空。 即使键没有已保存的值,也会报告定义冲突。

静态选项和注册时已解析的填充选项会接受检查,但不会再次调用填充函数。远程 fetch 选项以及包含 {attributes.*} 的填充参数会跳过检查。颜色和渐变值可以是自定义值,除非设置了 disableCustomColors 或 disableCustomGradients。 此检查针对存储值,不检查 default、fallback 或编辑器验证规则。

匹配的扩展字段会包含在其针对的每个区块中。在根级的区块及其扩展中,后续定义优先,和渲染时一样。区块自身的字段与扩展字段是同一键的独立定义,两者都会生效。在重复器行中,渲染器会读取每个来源中 ID 匹配的第一个字段,因此该字段的选项和范围会生效。为便于诊断冲突,重复定义会予以保留:即使后续的重复定义在渲染时不会读取,不兼容的存储结构仍会产生 definition_conflict。

此函数检查单个区块。验证文档时请遍历 innerBlocks;同步模式和其他引用不会自动展开。命令wp bs blocks validate会遍历一个或多个文章中的区块,并报告其区块路径。

带有自定义渲染时解析器的网站可以调整检查结果,而无需更改存储的数据:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

始终返回检查结果列表;返回 [] 即表示接受该区块。此筛选器仅对受管理的区块运行,不会对 null 结果运行。

描述已存储的值

区块注册后(init或更高版本),使用bs_block_schema()描述区块存储的值,例如,在工具或 AI 集成中生成区块标记,或在REST路由中检查输入:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

结果是已保存到attrs.blockstudio.attributes中的对象的JSON Schema。它涵盖区块字段和匹配扩展的字段,并包含验证所用的存储键:顶层组会为其子项添加前缀,匿名组和选项卡不会增加层级,文件字段会添加其<id>__size配套字段。重复字段是行对象列表,其minItems和maxItems取自min和max。additionalProperties在字段存储根目录和重复字段行中均为false。链接和自定义对象等对象值字段可以携带自己的元数据。没有字段的区块没有properties,因此只有空对象符合要求。

每个字段都以bs_validate_block()接受的规范形式描述:

字段 Schema
text、textarea、richtext、wysiwyg、code、date、datetime、unit、classes、html-tag、block 字符串。
number、range 数字,范围由min和max提供的minimum和maximum限定。
toggle 布尔值。
select、radio、checkbox 选项值;对于checkbox和multiple,也可以是选项值列表,并带有enum。
color、gradient 字符串;当设置了disableCustomColors或disableCustomGradients时,还包含enum。
token 字符串列表。
files 非负整数附件 ID,或带有multiple的 ID 列表。
link 包含url、title和opensInNewTab的对象;url为必填项。
icon 包含set、subSet和icon的对象;set和icon为必填项。
attributes 对象列表,每个对象都包含非空的attribute和标量value。
repeater 行对象列表。
自定义字段类型 其注册的属性类型。

enum列出了验证会检查的选项:静态选项,以及注册时已解析的填充选项。远程fetch选项和包含{attributes.*}的填充参数没有enum。如果某个键对应不同存储形状的定义,则会将其排除,因为验证会报告存储在该键下的每个值。当区块字段和扩展字段使用同一个键时,enum会列出两者都接受的值。共享的重复字段会合并其子字段,并采用两种定义中更严格的行数限制。在重复字段行中,每个来源里与 ID 匹配的第一个字段生效,与渲染时相同。显式命名为<id>__size的字段优先于自动添加的文件大小配套字段。

当封闭字段没有可用选项,或两个适用的选项集没有交集时,其规范值在单选情况下为null,在多选情况下为空列表。空选项列表不会使字段变为不受限制。远程选项和依赖属性的选项仍保持开放。

字段的label会变为title,其help会变为description,而default会作为注释保留。Schema 自身的title是区块标题。字段从不设为必填项,条件逻辑也不属于 Schema。

约束仅使用rest_validate_value_from_schema()会检查的关键字,因此该 Schema 可直接用作REST路由或能力的输入 Schema:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

架构按每个字段描述一种表单;验证也接受导入的形状,例如选项对象、数字字符串和 ID 对象。它不会取代 bs_validate_block():定义冲突属于配置问题,即使省略冲突键,仍可能产生发现结果。验证筛选器也可以施加特定于站点的规则。使用 bs_validate_block() 检查已存储的内容。使用自定义渲染时解析器的站点可以通过 blockstudio/blocks/attributes/schema 筛选器调整架构。

PHP 函数

不带数据

最简单的用法是,该函数接受一个值,即要在页面上渲染的区块 ID。

PHP
bs_render_block('blockstudio/cta');

带数据

要使用自定义数据渲染区块,第一个参数需要传入数组,而不是单个值。data 键中的值会传递给区块模板中的 $attributes 和 $a 变量。

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

嵌套

在区块模板中结合使用 bs_block 函数和强大的 $content 变量,即可将区块嵌套在彼此之中。

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

按钮区块会渲染在区块模板中 $content 变量所在的位置。

使用 bs_render_block() 或 bs_block() 渲染的嵌入式区块始终会输出前端解析后的 HTML,即使父区块当前正在渲染编辑器预览也是如此。嵌入式区块返回之前,会先解析 <RichText /> 和 <InnerBlocks /> 等模板伪组件。

多个插槽

只需将 $content 变量设为关联数组,并在 bs_block 函数中调用相应的键,即可创建多个内容插槽。

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

区块标签

使用 HTML 标签语法嵌入任意区块。支持两种格式:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

两种写法都会渲染同一个区块。<bs:> 语法会将连字符转换为命名空间分隔符(acme-hero 会变成 acme/hero)。系统会从左到右尝试连字符,首个已注册的候选项优先,因此包含连字符的命名空间也能解析:<bs:acme-ui-button> 会依次尝试 acme/ui-button,然后是 acme-ui/button。<block> 语法则将完整区块名称作为 name 属性传入。

Blockstudio 区块和核心 WordPress 区块都可以使用。Blockstudio 区块会经过完整管线(模板、Tailwind、资源)进行渲染。核心区块则通过 WordPress 的区块渲染系统,使用内置的 区块渲染器 进行渲染。

工作原理

区块标签所在位置不同,行为也会有所不同:

在区块模板和文章内容中,标签会在运行时替换为已渲染的 HTML。输出是所引用区块的最终标记,直接嵌入页面。这些位置不会在编辑器中生成 WordPress 区块。它们纯粹是一种渲染机制。

在 页面、样板和站点模板 中,文件源同步或向 WordPress 注册之前,标签会转换为原生 WordPress 区块。因此,这些区块会显示在编辑器中,可以在目标环境支持编辑的情况下进行编辑,并经历 WordPress 完整的区块生命周期。标签语法是在模板文件中定义区块内容的简写形式。

这一区别很重要:模板中的区块标签会生成输出,而页面、样板和站点模板中的区块标签会生成原生区块。

在区块模板中

区块标签会自动在 Twig 和 PHP 模板中渲染,无需任何设置。这包括 <bs:> 和 <block> 语法,以及任何已注册的 前缀 和别名标签,因此模板可以直接输出这些标签,而无需调用 bs_render_block()。输出会 HTML 直接嵌入区块的模板输出中:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

在文章内容中

页面级渲染(文章内容、组件区域)默认关闭:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

也可以通过筛选器启用:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

语法

自闭合标签:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

带内部内容的成对标签:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

可以自由组合。两种语法都可以相互嵌套:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

前缀简写

区块标签还可以使用项目专属的前缀简写。为一个或多个命名空间注册前缀后,Blockstudio 会按照命名空间顺序,将 <prefix-slug> 解析为首个已注册的区块:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

根据上面的示例,<theme-card> 会解析为 theme-components/card;如果 theme-components/button 未注册,<theme-button> 会回退到 bsui/button;<theme-ui-feature-matrix> 则会解析为 theme-components/ui-feature-matrix。

前缀也可以组合使用。如果带前缀的标签无法直接解析,而剩余的 slug 本身是一个已注册的前缀标签,系统就会递归解析,因此品牌前缀可以叠加在命名空间前缀之上:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input> 没有对应的 theme-components/ui-input 区块,因此会继续尝试 ui 前缀并解析为 bsui/input。直接匹配始终优先于嵌套解析,允许和拒绝规则则应用于最终解析出的区块。

你也可以在 blockstudio.json 中配置前缀:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

前缀必须由小写字母或数字组成,以字母开头,且不能包含连字符。blockstudio/block_tags/tag_aliases 中的显式别名优先于前缀解析。无法识别的带前缀标签会保持原样。

前缀和别名标签仍可作为便捷的编写方式。规范且可移植的写法始终是 <bs:namespace-slug>,因为它记录了真实的区块名称,不依赖项目筛选器:

HTML
<bs:theme-components-card />
<bs:bsui-input />

Blockstudio 示例、生成的诊断信息和程序化输出都会使用这种规范写法。想要移除旧式简写形式的项目,可以使用独立的、默认先试运行的规范标签迁移,无需启动 WordPress。

核心区块

任何已注册 渲染器 的区块都可以使用:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

也可以使用 <block> 语法:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

允许列表和拒绝列表

控制哪些区块可以通过标签渲染:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allow 仅允许匹配的模式。deny 会排除匹配的模式,且优先级更高。两者都支持通过 fnmatch() 使用 * 通配符。这些规则适用于两种语法,以及模板级和页面级渲染。

筛选器:blockstudio/block_tags/allow 和 blockstudio/block_tags/deny。

HTML 直通

以 data- 为前缀的属性会传递到已渲染区块的根元素。以 html- 为前缀的属性也会传递过去,但会去掉前缀。两种语法都适用。直通属性会替换根元素已有的值,而不是与之合并,因此 html-class 会替换区块自身的类。

Blockstudio 区块还会将未声明为字段的全局属性放到根元素上:id、style、role、title、lang、dir、hidden、tabindex,以及所有 aria-* 属性。已声明的字段始终优先,因此带有 title 字段的区块会改为接收 $a['title'] 中的值。转发的样式会经过 safecss_filter_attr();筛选器 WordPress 会应用于文章内容中的样式属性,并将其追加到模板已有的样式中。

属性值会经过 HTML 处理,因此解析标签时实体只会解码一次:title="Tom &amp; Jerry" 在模板中会变成 Tom & Jerry,输出时再进行转义。带引号的值可以包含 >,例如 Tailwind 变体和动画选择器;这适用于自闭合标签和成对标签。

区块未声明的任何其他属性,包括 class,都不会传递给 HTML。启用 WP_DEBUG 后,Blockstudio 会通过 _doing_it_wrong() 在每次请求中报告每个此类属性一次。为其声明字段,或将其写成 data-、aria- 或 html- 属性。

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

自定义渲染器

注册自定义区块渲染器,以支持其他区块类型。渲染器接收一个属性数组和一个内部内容字符串,并返回一个 WordPress 区块数组:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

对于需要将内部内容解析为子区块的容器区块,可在同一筛选器中添加第二个条目:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/builders 同时适用于区块标签和通过 blockstudio/parser/element_mapping 选择的自定义区块。如果某个项目区块映射到元素,需要将内部文本移入 Blockstudio 字段或构建自定义区块数组,则应使用此钩子。

blockstudio/block_tags/renderers 和 blockstudio/parser/renderers 接收相同的注册表和回调结构。为保持兼容性和支持最终的解析器级覆盖,它们仍然可用。筛选器按以下顺序运行:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

后续筛选器可以替换由前面的筛选器注册的渲染器。

程序化用法

将标签渲染应用于来自 PHP 的任意字符串:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

组件

区块标签与 组件 配合使用效果很好。组件是仅通过程序化方式渲染、不会出现在编辑器中的区块。

HTML
<bs:mytheme-card title="My Card" description="Card content." />

解析器

区块标签由轻量级字符串扫描器处理,该扫描器取代了 DOMDocument。解析器支持 <bs:> 和 <block> 语法、通过深度跟踪处理同名标签嵌套、带引号的属性值,以及递归容器区块。它专为此用例设计,基准测试速度快于 DOMDocument 和 WordPress 的 WP_HTML_Tag_Processor,并避开了 DOMDocument 已知的问题,包括命名空间前缀被剥除和属性名称被转为小写。

对于 页面、样板和站点模板,同一解析器还会处理原始 HTML 元素(<p>、<div>、<h1> 等),并将它们映射到相应的 WordPress 核心区块。

如果元素映射将 <p> 指向一个已注册的非核心 Blockstudio 区块,且该区块声明了 content richtext 属性,内部 HTML 会自动传入该 content 属性,包括在区块级别映射为元素的 code 和 img 等行内标签。唯一子元素是图像的段落会变成映射到 <img> 的区块。嵌套的区块标签或区块级 HTML 仍会回退到常规内部区块解析。<block name="core/shortcode"> 会将其短代码文本保留为区块内容。