目标：把数组变成查询循环
Meta Box 的 Checkbox List 字段让用户在一组选项里勾选任意多个，存进数据库的值是一个数组。想在 Bricks 里把它逐项列出来，最直接的办法是复制 Meta Box 生成的代码塞进 Code 元素——但这样就没法用 Basic Text 等元素做样式了。
这篇演示的是更通用的能力：注册一个自定义查询类型，让查询循环逐项遍历任意 PHP 数组。数组里的每个值变成一个循环项，循环项里可以用任意 Bricks 元素 + 自定义动态标签来渲染。学会这套模式，Checkbox List、Select 多选、甚至自己拼的数组，都能在查询循环里输出。
Step 1：建 CPT 与 Checkbox List 字段
- 建 CPT
project（项目，如无现成的）。 - Meta Box 字段组挂到该 CPT，加一个 Checkbox List 字段，ID 设为
services_provided，选项填几个服务名（如 Web Design / SEO / Content）。 - 给项目文章勾选一些服务值。
Step 2：注册自定义查询类型
把下面代码加到子主题 functions.php 或代码片段插件：
// 1. 注册查询类型，让它出现在查询类型下拉列表里
add_filter( 'bricks/query/register_types', function( $query_types ) {
$query_types['bl_mb_checkbox_list'] = [
'name' => 'BL MB Checkbox List',
'supports' => [ 'field' ],
];
return $query_types;
} );
// 2. 告诉 Bricks 这个查询类型怎么产生结果
add_filter( 'bricks/query/run', function( $results, $query, $query_type ) {
if ( $query_type !== 'bl_mb_checkbox_list' || ! function_exists( 'rwmb_meta' ) ) {
return $results;
}
$object_id = isset( $query['object_id'] ) ? $query['object_id'] : get_the_ID();
$values = (array) rwmb_meta( 'services_provided', [ 'object_type' => 'post' ], $object_id );
$results = [];
foreach ( $values as $i => $value ) {
$results[] = (object) [
'ID' => $i + 1, // 每个循环项需要一个唯一 ID
'name' => $value,
];
}
return $results;
}, 10, 3 );两个钩子的分工：
bricks/query/register_types：注册类型本身，让 “BL MB Checkbox List” 出现在构建器查询类型下拉里，supports => [ 'field' ]表示该类型支持绑定字段；bricks/query/run：真正生成结果。$query['object_id']是查询上下文（当前文章）ID，rwmb_meta( 'services_provided', ... )拿到勾选值数组，然后把每个值包装成一个带 ID 的对象作为循环项返回。
Step 3：配套自定义动态标签
查询循环有了循环项，还得让元素能读出循环项的数据。循环项是 (object)[ 'ID' => ..., 'name' => ... ] 这样的对象，通过自定义动态标签读取：
// 3. 注册动态标签，输出当前循环项的 name 属性
add_filter( 'bricks/dynamic_data/tags', function( $tags ) {
$tags['bl_checkbox_value'] = [
'label' => 'BL Checkbox Value',
'render' => 'bl_render_checkbox_value',
];
return $tags;
} );
function bl_render_checkbox_value( $tag, $post, $context, $name ) {
// 查询循环里 $post 就是当前循环项对象
if ( is_object( $post ) && isset( $post->name ) ) {
return $post->name;
}
return '';
}然后回到构建器：
- 在需要的位置放一个 Block，启用查询循环，查询类型选 BL MB Checkbox List；
- 循环项里放一个 Basic Text，插入动态数据
{bl_checkbox_value}； - 想在每项前面加圆点、勾选图标，就在 Basic Text 旁边加图标元素，或者给循环项套列表样式。
保存后前端逐项列出该文章勾选的所有服务。换一篇勾选不同的文章，列表自动跟随。
顺便说一句：如果只是要快速输出“值列表”而不在意逐项样式，复制 Meta Box 在字段说明里生成的 PHP 代码（foreach 循环）放进 Code 元素也一样能出结果——那是更快的路线。本篇的价值在于把“数组变循环”的机制讲透：数组来自哪里不重要，只要能在 PHP 里拿到数组，就能用同样的三件套把它变成带样式的查询循环。另外注意 supports => [ 'field' ] 只是声明“该类型可以绑定字段”，真正决定结果内容的还是 bricks/query/run 里的逻辑，绑定字段与否并不影响取值（我们直接按固定字段 ID 读），留着它主要是为了查询面板里能正常显示和保存配置。
小结：这套“注册类型 → 生成结果 → 动态标签渲染”的三件套，本质是把任何 PHP 数组变成查询循环的通用模板。Checkbox List 只是第一个例子——把 rwmb_meta 换成 get_field 就能循环 ACF 的多选值，换成 wp_get_post_terms 就能循环分类术语，换成任何自建数组都行。记住两个关键点：循环项必须是带唯一 ID 的对象；渲染时用自定义动态标签读循环项属性，配合 is_object 判断兜底。这是 Bricks 自定义查询类型最核心的入门模式。