跳转到正文

自定义字段

自定义字段允许你定义可在多个区块中引用的可重复使用字段组。你可以把它们看作字段模板:定义一次,随处使用。

自定义字段不同于 自定义字段类型。使用 custom/{name} 来复用现有字段组。当主题或插件注册新的编辑器控件和值结构时,请使用带命名空间的自定义 字段类型,例如 acme/dimensions。

文件系统注册

在 blockstudio 目录的 fields/ 目录中创建一个 field.json 文件:

代码
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

PHP 筛选器注册

使用 blockstudio/fields 筛选器以编程方式注册自定义字段:

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

在 block.json 中使用

使用 custom/{name} 类型引用自定义字段:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

这会将自定义字段定义中定义的字段内联展开。展开后的字段使用原始 ID(heading、description、enabled)。

自定义字段也可以复用完整的组定义:

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

组的子项会存储为 section-header_kicker、section-header_title 等。在模板中,使用 bs_get_group() 将它们提取为整洁的组对象。

ID 结构

使用 idStructure 为字段 ID 添加前缀或进行转换。{id} 占位符会替换为原始字段 ID:

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

这会生成 ID 分别为 hero_heading、hero_description、hero_enabled 的字段。

覆盖设置

使用 overrides 按实例自定义单个字段。键为定义中的原始字段 ID:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

覆盖属性会合并到原始字段定义之上。id 覆盖会绕过 idStructure 模式。在上面的示例中,enabled 会变为 active,而不是 hero_enabled。

合并只进行一层:你覆盖的属性会整体替换原属性。options覆盖项是完整的选项列表,而不是追加内容;conditions和组的attributes也同样如此。之后仍会添加引用上的条件。

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

无论定义列出了多少选项,此区块都只提供 White 和 Grey。

条件

应用 idStructure 时,自定义字段定义中的条件会自动重写。条件性依赖同级字段的字段在展开后仍可正常工作。

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio 会将其展开为 title_font_enable、title_font_min、title_font_max,并将条件重写为引用 title_font_enable 而不是 enable。这些切换开关的工作方式与字段内联定义时完全相同。

引用级条件

在引用上添加 conditions,即可将条件应用于每个展开后的字段。这适用于将整个组隐藏在外部切换开关之后:

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

这些条件会与字段定义中已有的任何条件合并。条件 ID 也会通过 idStructure 重写。

多个自定义字段

你可以在同一区块中使用多个自定义字段,并与常规字段搭配:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

嵌套

自定义字段可用于组、选项卡和 Repeater 内部:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

其他发现路径

使用 blockstudio/fields/paths 筛选器添加用于字段发现的其他目录:

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

静态分析

blockstudio/phpstan 包在验证 PHP、Twig、Blade、区块标签和推断出的属性结构时,会展开由文件支持的 custom/* 引用。其展开遵循上文所述相同的嵌套、idStructure 和 overrides 规则。

对于分析项目之外的定义,请将库目录添加到 blockstudioScanRoots 的 phpstan.neon 中。仅通过 blockstudio/fields PHP 筛选器注册的字段只在运行时存在,无法进行静态推断。