跳转到正文

渲染属性

在模板文件中,可以使用 $attributes 或 $a 变量和相应字段的 ID 访问所有属性。

PHP

PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>

Twig

Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>

以编程方式写入属性

编辑器会将已保存的值嵌套在 blockstudio.attributes 下。在编辑器之外写入区块的任何程序,例如 REST API、WP-CLI、内容迁移或 MCP 服务器,都会从 WP_Block_Type 上由 Blockstudio 注册的属性中识别区块,并在顶层写入这些属性。两种结构都能渲染:

PHP
// 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 数组:

PHP
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
<?php if ($a['message']) : ?>
  <h1><?php echo $a['message']; ?></h1>
<?php endif; ?>

Twig

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
<?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

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
<?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

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
<?php if ($a['icon']) : ?>
  <div class="icon">
    <?php bs_render_icon($a['icon']); ?>
  </div>
<?php endif; ?>

Twig

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

PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
  Content
</div>

Twig

Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
  Content
</div>

bs_render_data_attributes() 直接输出这些属性。bs_data_attributes() 返回字符串。

组

组字段会在其子属性 ID 前加上组名作为前缀。使用 bs_get_group() 将组字段提取为整洁的数组:

PHP

PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>

Twig

Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>

这会从属性键中移除组前缀。例如,$a['settings_title'] 会变为 $group['title']。

该辅助函数也适用于来自复用自定义字段的组:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "attributes": [
        { "id": "kicker", "type": "text" },
        { "id": "title", "type": "text" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/section-header" }
    ]
  }
}
Twig
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>

重复器

遍历重复器项目:

PHP

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

Twig
{% for item in a.items %}
  <div class="item">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
  </div>
{% endfor %}

字段模式手册