跳转到正文

扩展

扩展功能允许你使用基于简单 .json 的 API,为 WordPress 安装中的任何已注册区块添加扩展功能。它与 block.json 配置类似,适用于核心区块、第三方区块以及使用 Blockstudio 制作的区块。

所有 字段类型都可以添加到任何区块,数据会保存到区块属性中。扩展还支持属性的完整功能集,例如筛选、禁用、条件逻辑和填充选项。

扩展类型

扩展后的值有多种灵活的用途:

  • class:使用属性值为区块添加类
  • style:使用属性值为区块添加内联样式
  • attributes:直接在区块上设置任意属性值
  • data attributes:使用扩展值设置特定的数据属性

设置

假设以下场景:你想为每个核心区块添加一个自定义类名 select 字段。只需将这个 .json 文件添加到区块文件夹中的任意位置,它就会自动注册为扩展。

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 创建的区块:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

排除区块

使用顶层 exclude 数组,跳过原本会匹配 name 的区块:

JSON
{
  "$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:高级选项卡
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

优先级

priority 属性用于定义扩展的渲染顺序。优先级较高的扩展会较晚渲染。可以像设置示例中那样在文件顶层设置,也可以在 extend 中设置:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

如果两者都已设置,则以 blockstudio.extend.priority 为准。

属性

有关属性工作方式的更多信息,请参阅属性部分。

关于扩展中的属性,你只需了解 set 属性。它用于将属性的值应用到某一种扩展类型。

JSON
{
  "$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 时。

JSON
{
  "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 没有影响,对返回单个值的字段也没有影响。

JSON
{
  "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() 的关系,请参阅 检查区块。