扩展
扩展功能允许你使用基于简单 .json 的 API,为 WordPress 安装中的任何已注册区块添加扩展功能。它与 block.json 配置类似,适用于核心区块、第三方区块以及使用 Blockstudio 制作的区块。
所有 字段类型都可以添加到任何区块,数据会保存到区块属性中。扩展还支持属性的完整功能集,例如筛选、禁用、条件逻辑和填充选项。
扩展类型
扩展后的值有多种灵活的用途:
- class:使用属性值为区块添加类
- style:使用属性值为区块添加内联样式
- attributes:直接在区块上设置任意属性值
- data attributes:使用扩展值设置特定的数据属性
设置
假设以下场景:你想为每个核心区块添加一个自定义类名 select 字段。只需将这个 .json 文件添加到区块文件夹中的任意位置,它就会自动注册为扩展。
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"priority": 10,
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Custom color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
这会为每个核心区块添加一个 customColor 字段,让你可以设置区块文本的颜色。
文件名
由于没有渲染模板,扩展不需要对应的 index 文件,因此也不必命名为 block.json。这样一来,所有扩展都可以方便地存放在同一个文件夹中。多个文件可以扩展同一批区块,例如两个文件都带有 "name": "core/*";每个文件都会注册自己的字段。
架构
Blockstudio 为扩展配置提供自定义的 JSON 架构:
名称
配置对象的 name 属性用于指定要扩展哪些区块。根据需要,有三种选项:
- blockName:单个区块名称,e.g。
core/paragraph - [blockNameA, blockNameB]:区块名称数组,e.g。
["core/paragraph", "core/heading"] - core/*:用于扩展某一类型所有区块的通配符
以星号结尾的名称表示前缀通配符,不仅限于 core/*。以下扩展适用于名称以 my-plugin/ 开头的所有区块,
包括使用 Blockstudio 创建的区块:
{
"name": "my-plugin/*",
"blockstudio": {
"extend": true,
"attributes": []
}
}
排除区块
使用顶层 exclude 数组,跳过原本会匹配 name 的区块:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"exclude": ["core/button", "core/image"],
"blockstudio": {
"extend": true,
"attributes": []
}
}
排除项与 name 一样,支持精确名称匹配和末尾带 * 的前缀匹配。
排除项优先于单个名称、名称列表和通配符。被排除的区块不会获得扩展的编辑器字段、前端属性或资源。其他匹配的扩展不受影响。省略 exclude 或使用空数组即可保持现有行为。
Blockstudio 键
与自定义区块中使用 block.json 时一样,配置对象中必须包含 blockstudio 属性,并将 extend 设为 true。
位置
默认情况下,扩展会在区块检查器中自己的选项卡内渲染。若要将扩展移到其他位置,可以使用 group 属性:
- settings:默认位置
- styles:样式选项卡
- advanced:高级选项卡
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"group": "styles",
"attributes": []
}
}
优先级
priority 属性用于定义扩展的渲染顺序。优先级较高的扩展会较晚渲染。可以像设置示例中那样在文件顶层设置,也可以在 extend 中设置:
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": { "priority": 10 },
"attributes": []
}
}
如果两者都已设置,则以 blockstudio.extend.priority 为准。
属性
有关属性工作方式的更多信息,请参阅属性部分。
关于扩展中的属性,你只需了解 set 属性。它用于将属性的值应用到某一种扩展类型。
{
"$schema": "https://blockstudio.dev/schema/extend",
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor}"
}
]
}
]
}
}
获取值
在花括号内使用点号表示法可以获取属性值。
当属性返回的不是单个值时,也可以获取嵌套值;例如,对于带有选项的字段类型,将返回格式设为 both 时。
{
"attributes": [
{
"id": "customColor",
"type": "select",
"label": "Heading color",
"options": [
{
"value": "#f00",
"label": "Red"
},
{
"value": "#00f",
"label": "Blue"
}
],
"returnFormat": "both",
"set": [
{
"attribute": "style",
"value": "color: {attributes.customColor.value}"
},
{
"attribute": "data-color",
"value": "{attributes.customColor.label}"
}
]
}
]
}
上面的示例会根据值将 style 属性设为 color: #f00 或 color: #00f,并将 data-color 属性设为 Red 或 Blue。
目前,set 定义中只能使用当前属性的值。未来可能会支持使用其他属性的值。
数组
使用数组时,set 属性会应用于数组中的每一项。
每个项目都会添加自己的类或样式声明。其他任何属性都只保存单个值,因此每个项目都会覆盖它,最终以最后一个项目为准。将 join 设为 true,即可改为写入所有项目的结果,并以空格分隔且不含空值或重复值,这样 [data-langs~="en"] 这样的选择器就能匹配每个选定项目。join 对 class 和 style 没有影响,对返回单个值的字段也没有影响。
{
"id": "langs",
"type": "checkbox",
"label": "Languages",
"options": [
{
"value": "en",
"label": "English"
},
{
"value": "de",
"label": "German"
}
],
"set": [
{
"attribute": "data-langs",
"value": "{attributes.langs}",
"join": true
}
]
}
同时选择这两个选项会渲染 data-langs="en de"。不选择 join 时,会渲染 data-langs="de"。
Attributes 字段
使用 attributes 字段时,无需设置 set 属性,因为该字段会自动将值映射到属性名称和值。
检查扩展字段
bs_block_extension_fields('core/paragraph') 会返回与某个区块匹配的所有扩展的字段定义。有关返回值及其与 bs_block_fields() 的关系,请参阅 检查区块。