跳转到正文

筛选属性

Blockstudio 提供了两种筛选区块属性的方法。

属性定义

blockstudio/blocks/attributes 会筛选每个字段定义,而 Blockstudio 会构建并注册区块。可用它调整编辑器控件、默认值、条件和选项,并修改渲染期间用于验证值的定义。

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'my-theme/code-block' &&
    ($attribute['id'] ?? '') === 'lineNumbers'
  ) {
    $attribute['default'] = true;
    $attribute['conditions'] = [
      [
        [
          'id' => 'language',
          'operator' => '==',
          'value' => 'css'
        ]
      ]
    ];
  }

  return $attribute;
}, 10, 2);

上面的代码将 lineNumbers 的默认值设为 true,并在 language 未设为 css 时隐藏该字段。

每次调用回调时都会收到一个字段定义,其中包括嵌套的组字段和重复器字段。它在区块注册期间运行,而非每次前端渲染时运行。

经过筛选的选项定义也会用于渲染属性映射。例如,添加到 select、radio 或 checkbox 字段的选项,可在编辑器中使用,并且当 Blockstudio 为模板解析已保存的值时仍然有效:

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  if (
    ($block['name'] ?? '') === 'bsui/button' &&
    ($attribute['id'] ?? '') === 'variant'
  ) {
    $attribute['options'][] = [
      'label' => 'Brand',
      'value' => 'brand',
    ];
  }

  return $attribute;
}, 10, 2);

渲染值

blockstudio/blocks/attributes/render 会在字段的解析值传递给区块模板之前立即对其进行筛选。它会为每个字段运行一次,因此回调会接收该值、字段键和区块数据。

PHP
add_filter('blockstudio/blocks/attributes/render', function($value, $key, $block) {
  if (($block['name'] ?? '') === 'my-theme/code-block' && 'lineNumbers' === $key) {
    return true;
  }
  return $value;
}, 10, 3);

上面的示例会覆盖编辑器中为 lineNumbers 保存的任何值。注册回调时应接受三个参数(即 add_filter 的最后一个参数),否则 WordPress 只会传递该值。

  • $value:字段的解析值,其格式与模板接收的 $a[$key] 相同。返回模板应获取的值。
  • $key:字段的键,与 $a 中使用的键相同。在重复器行内,这是该行中字段的 ID。
  • $block:模板以 $block 或 $b 形式接收的区块数据数组,其中包含 id、name、postId、postType、index、indexTotal、context 和岛屿标志。对于应用于非 Blockstudio 区块的 扩展,$block 仅包含 blockstudio 条目(attributes 和 disabled),且没有 name。

该筛选器也会对非 Blockstudio 字段的属性运行,例如 className 和 anchor,以及文件字段的 <id>__size 配套字段,因此更改值之前请先比较 $key。返回值只会替换 $key 的值;筛选器无法向 $a 添加新键。

更改字段配置时使用定义筛选器;为某个请求计算或覆盖模板值时使用渲染筛选器。

通过 使用bs_block_values()读取值,而不是进行渲染时,此筛选器在 $block 中只会收到区块名称。此辅助函数不会创建渲染计数器和其他仅用于渲染的元数据。