筛选属性
Blockstudio 提供了两种筛选区块属性的方法。
属性定义
blockstudio/blocks/attributes 会筛选每个字段定义,而 Blockstudio 会构建并注册区块。可用它调整编辑器控件、默认值、条件和选项,并修改渲染期间用于验证值的定义。
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 为模板解析已保存的值时仍然有效:
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 会在字段的解析值传递给区块模板之前立即对其进行筛选。它会为每个字段运行一次,因此回调会接收该值、字段键和区块数据。
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 中只会收到区块名称。此辅助函数不会创建渲染计数器和其他仅用于渲染的元数据。