渲染属性
在模板文件中,可以使用 $attributes 或 $a 变量和相应字段的 ID 访问所有属性。
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
以编程方式写入属性
编辑器会将已保存的值嵌套在 blockstudio.attributes 下。在编辑器之外写入区块的任何程序,例如 REST API、WP-CLI、内容迁移或 MCP 服务器,都会从 WP_Block_Type 上由 Blockstudio 注册的属性中识别区块,并在顶层写入这些属性。两种结构都能渲染:
// 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"}}} /-->' );
只会读取区块在顶层声明的 ID,因此不会将 WordPress 自身的属性(如 anchor、className、lock、metadata 和 style)用作字段值。如果同一 ID 同时出现在两个位置,则以嵌套值为准。
以编程方式读取属性
在模板之外运行的代码(例如 save_post 上的结构化数据、导出、搜索索引或 render_block 过滤器)通常需要像模板中那样读取已保存区块的值。bs_block_values() 可在不渲染区块的情况下返回这些值。在区块注册后(init 或更晚)调用它,并传入来自 parse_blocks() 的完整 attrs 数组:
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'] ?? '');
}
结果是模板中的 $a 数组,按字段 ID 为键:
- 字段默认值会生效,带有
min的重复器会包含初始行。 - 顶层值会与
blockstudio.attributes合并,嵌套值优先。只会读取顶层中已声明的 ID;WordPress 会丢弃与字段注册类型不匹配的顶层值,例如选择字段的字符串,这与渲染时完全一致。 - 匹配的 扩展 字段及其默认值也会包含在内。核心区块或第三方区块的扩展只读取
blockstudio.attributes,与渲染时一致。 - 会应用返回格式,因此,
returnFormat为label的选择字段会返回标签,文件字段则会返回附件数据。 - 与模板中一样,禁用和空字段会被
false。
null 表示该区块或扩展都不由 Blockstudio 管理。没有字段的 Blockstudio 区块会返回 []。
该函数会运行与渲染相同的转换,因此副作用也相同:文件字段会查询附件,不返回 data 的区块字段会渲染被引用的区块,而 blockstudio/blocks/attributes/render 过滤器会针对每个值运行。它不会渲染区块自身的模板,也不会解析 innerBlocks;请自行遍历它们。代码字段会保留一个自动生成的 %selector% ID,该 ID 在不同调用之间会发生变化。
解析使用当前的 WordPress 上下文。不会创建仅用于渲染的元数据(例如区块计数器和 innerBlocks);属性渲染过滤器接收的是区块名称,而不是完全渲染后的区块元数据。
没有可在不执行转换的情况下获取存储值的选项。要读取这些值,请直接读取 attrs 数组,或使用 bs_validate_block()检查它们。
空值
字段为空或未选择任何选项时,属性值会返回 false。
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
复杂类型
文件
默认情况下(没有 returnFormat,或使用 "returnFormat": "object"),文件字段会返回一个包含附件数据的数组。使用 "multiple": true 时,则会返回这些数组组成的列表。附件已不存在的文件会是 false。
| 键 | 描述 |
|---|---|
ID |
附件 ID。 |
title |
附件标题。 |
alt |
替代文本。为空时会使用附件标题。 |
caption |
说明文字。 |
description |
描述。 |
href |
附件页面的永久链接。 |
url |
文件的 URL。使用尺寸下拉菜单("size": true)时,为所选尺寸的 URL。 |
sizes |
每种已注册图像尺寸的 URL 和尺寸,见下文。 |
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 中每个已注册的图像尺寸都有一个条目,此外还有 full:尺寸名称下的 URL,以及 <size>-width 和 <size>-height 下的尺寸。对于附件,如果尚未生成某个尺寸 WordPress,则会解析为原始文件及其尺寸。如果 WordPress 无法解析图像或预览,则不会包含 sizes 键。例如,没有生成预览的 PDF 不会有 sizes,但带有预览元数据的 PDF 可以有图像尺寸。没有注册任何图像尺寸,或 files/sizes筛选器禁用图像尺寸时,sizes 为 null。该筛选器也可能缩短映射,因此在读取尺寸之前,请先确认该尺寸存在,如上面的示例所示。
该对象没有 width、height、mime、type 或 size 键。请从 sizes 读取尺寸,或将 ID 与 wp_get_attachment_image()、get_post_mime_type() 等函数搭配使用。
返回格式
returnFormat 会更改字段的返回值:
returnFormat |
值 |
|---|---|
"object"(默认) |
上文所述的数组。 |
"id" |
按存储形式返回附件 ID;使用 "multiple": true 时返回 ID 列表。 |
"url" |
将 URL 作为字符串返回;使用 "multiple": true 时返回 URL 列表。图像使用 returnSize 设置的尺寸(默认 full),其他文件使用其文件 URL。 |
链接
链接字段返回一个包含 URL 和属性的对象:
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 %}
图标
图标字段返回一个对象,包含 set、subSet 和 icon 键。使用辅助函数 bs_render_icon() 和 bs_icon() 输出 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() 直接输出 SVG。bs_icon() 将其作为字符串返回。
属性
属性字段类型会返回一个 {attribute, value} 键值对数组,用于渲染为 HTML 属性。使用 bs_render_data_attributes() 输出它们:
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() 直接输出这些属性。bs_data_attributes() 返回字符串。
组
组字段会在其子属性 ID 前加上组名作为前缀。使用 bs_get_group() 将组字段提取为整洁的数组:
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>
这会从属性键中移除组前缀。例如,$a['settings_title'] 会变为 $group['title']。
该辅助函数也适用于来自复用自定义字段的组:
{
"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>
重复器
遍历重复器项目:
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 %}