跳转到正文

填充选项

与其提供 Posts、Users 或 Terms 等不同字段类型,不如使用 Blockstudio,直接从 block.json 模块化地填充数据。此功能适用于 select、radio、checkbox、color 和 gradient 字段类型。

可以通过四种方式填充数据:

  • 查询 – 返回文章、用户或术语查询的结果
  • 获取 – 返回外部来源的结果
  • 函数 – 返回自定义函数的结果
  • 自定义 – 返回自定义数据集的结果

查询

选择查询模式时,可以填充 Posts、Users 或 Terms。

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/native",
  "title": "Native Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts"
        }
      }
    ]
  }
}

可用的查询类型在内部使用这些 WordPress 函数:

查询 函数
posts get_posts
users get_users
terms get_terms

参数

可以使用 arguments 属性传入自定义参数:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "jobs",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

返回格式

默认情况下,Blockstudio 返回:

查询 值 标签
posts 文章对象 post_title
users 用户对象 display_name
terms 术语对象 name

使用 returnFormat 自定义响应:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          },
          "returnFormat": {
            "value": "id",
            "label": "post_name"
          }
        }
      }
    ]
  }
}

获取模式

使用 fetch 选项启用动态搜索:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

这会启用 stylisedUi,并在初始加载时获取前 20 篇文章。在选择字段中输入内容即可使用 s 参数搜索文章。

函数

使用自定义函数填充选项:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

参数

将参数作为数组传入(内部使用 call_user_func_array):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

返回格式

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

混合选项

将静态选项与填充的数据组合使用:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "users",
        "type": "radio",
        "label": "Users",
        "options": [
          {
            "value": "administrators",
            "label": "Administrators"
          },
          {
            "value": "editors",
            "label": "Editors"
          }
        ],
        "populate": {
          "type": "query",
          "query": "users",
          "position": "before"
        }
      }
    ]
  }
}

position 选项(before 或 after)用于控制填充的选项相对于静态选项的显示位置。

警告

使用 fetch 模式时,不支持混合选项和填充数据。

自定义数据

使用 blockstudio/blocks/attributes/populate 筛选器创建可重复使用的数据集。该筛选器接收一个参数,即按名称作为键的所有自定义数据集组成的数组。将数据集添加到一个键下并返回该数组:

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

然后在区块中引用该键:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

外部数据

从外部来源获取数据:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "select",
        "type": "select",
        "label": "Select",
        "multiple": true,
        "populate": {
          "type": "fetch",
          "arguments": {
            "urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
          },
          "returnFormat": {
            "value": "id",
            "label": "title.rendered"
          }
        }
      }
    ]
  }
}

搜索词会附加到 urlSearch。

动态参数

填充参数可以使用 {attributes.*} 语法引用其他区块属性。被引用的属性发生变化时,字段会自动重新获取选项。

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post Type",
        "options": [
          { "label": "Pages", "value": "page" },
          { "label": "Posts", "value": "post" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Select Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": {
            "post_type": "{attributes.post_type.value}",
            "numberposts": 10
          }
        }
      }
    ]
  }
}

这适用于所有填充类型(query、function、custom)。填充配置中任何包含 {attributes.*} 的值,都会在查询运行前,在客户端使用当前属性值解析。

引用使用编辑器中存储的值。对于选择项,请使用 {attributes.post_type.value} 获取其值,或使用 {attributes.post_type.label} 获取其标签;returnFormat 控制的是模板值,而不是编辑器中存储的数据结构。

嵌套参数会在解析时保留原有结构,不会被序列化为模板字符串。仅由一个占位符组成的参数会保留其引用值的类型,包括数字、布尔值、数组和对象。嵌入其他文本中的占位符会生成字符串。找不到引用时会原样保留,多行值或带引号的值也会完整传递。 函数回调会保留其位置参数列表。编辑器只会为 query 填充器添加 WordPress 搜索参数,不会为函数调用添加。

渲染依赖选择项

注册区块时不会加载依赖选项,因为每个区块实例的参数可能不同。渲染时会使用已保存的选择项,不会因选项列表为空而将其丢弃。前端不会再次执行填充回调。

字段的 returnFormat 仍然适用:

returnFormat 单选 多选
value(默认) 已保存的值,例如 "a" 已保存值的数组,例如 ["a", "b"]
label 已保存的标签 已保存标签的数组
both 已保存的 {value, label} 选项 已保存选项的数组

对于由查询填充的选项,除非 populate.returnFormat.value 为 "id",值仍会解析为对应的 WordPress 文章、用户或分类法术语对象。标签取自已保存的选项。如果导入的选项没有标签,则使用其值作为标签。在 options 中声明的匹配静态选项优先于已保存的选项,因此会使用其当前标签。

空选项仍为 false(或字段配置的 fallback)。这不会改变普通静态选项的验证:已保存的值如果不再位于静态选项列表中,仍会返回 false。

动态选择字段也会在选项延迟提供期间保留 default 和 fallback 选项。多选字段可使用标量值、{value, label} 选项,或两者组成的数组。标量值会用其自身作为标签,除非它与已声明的静态选项匹配。选项对象会保留其提供的标签;匹配的静态选项优先。服务器不会运行填充回调来查找这些默认值。