填充选项
与其提供 Posts、Users 或 Terms 等不同字段类型,不如使用 Blockstudio,直接从 block.json 模块化地填充数据。此功能适用于 select、radio、checkbox、color 和 gradient 字段类型。
可以通过四种方式填充数据:
- 查询 – 返回文章、用户或术语查询的结果
- 获取 – 返回外部来源的结果
- 函数 – 返回自定义函数的结果
- 自定义 – 返回自定义数据集的结果
查询
选择查询模式时,可以填充 Posts、Users 或 Terms。
{
"$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 函数:
参数
可以使用 arguments 属性传入自定义参数:
{
"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 自定义响应:
{
"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 选项启用动态搜索:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"fetch": true,
"arguments": {
"post_type": "posts",
"numberposts": "20"
}
}
}
]
}
}
这会启用 stylisedUi,并在初始加载时获取前 20 篇文章。在选择字段中输入内容即可使用 s 参数搜索文章。
函数
使用自定义函数填充选项:
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types"
}
}
]
}
}
参数
将参数作为数组传入(内部使用 call_user_func_array):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
返回格式
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"],
"returnFormat": {
"value": "name",
"label": "label"
}
}
}
]
}
}
混合选项
将静态选项与填充的数据组合使用:
{
"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 筛选器创建可重复使用的数据集。该筛选器接收一个参数,即按名称作为键的所有自定义数据集组成的数组。将数据集添加到一个键下并返回该数组:
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['customData'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
然后在区块中引用该键:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
外部数据
从外部来源获取数据:
{
"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.*} 语法引用其他区块属性。被引用的属性发生变化时,字段会自动重新获取选项。
{
"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} 选项,或两者组成的数组。标量值会用其自身作为标签,除非它与已声明的静态选项匹配。选项对象会保留其提供的标签;匹配的静态选项优先。服务器不会运行填充回调来查找这些默认值。