Bricks 自定义查询类型：循环输出 Meta Box Checkbox List 值

目标：把数组变成查询循环

Meta Box 的 Checkbox List 字段让用户在一组选项里勾选任意多个，存进数据库的值是一个数组。想在 Bricks 里把它逐项列出来，最直接的办法是复制 Meta Box 生成的代码塞进 Code 元素——但这样就没法用 Basic Text 等元素做样式了。

这篇演示的是更通用的能力：注册一个自定义查询类型，让查询循环逐项遍历任意 PHP 数组。数组里的每个值变成一个循环项，循环项里可以用任意 Bricks 元素 + 自定义动态标签来渲染。学会这套模式，Checkbox List、Select 多选、甚至自己拼的数组，都能在查询循环里输出。

Step 1：建 CPT 与 Checkbox List 字段

1. 建 CPT project（项目，如无现成的）。

2. Meta Box 字段组挂到该 CPT，加一个 Checkbox List 字段，ID 设为 services_provided，选项填几个服务名（如 Web Design / SEO / Content）。

3. 给项目文章勾选一些服务值。

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 的对象作为循环项返回。

相关阅读：

• Bricks 自定义查询类型：输出 Meta Box 可克隆字段

• Bricks 内容切换器：纯 CSS 方案（radio + :has 实现标签切换）

• Bricks 用 ACF Checkbox 字段渲染自定义 SVG 图标列表

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 '';
}

然后回到构建器：

1. 在需要的位置放一个 Block，启用查询循环，查询类型选 BL MB Checkbox List；

2. 循环项里放一个 Basic Text，插入动态数据 {bl_checkbox_value}；

3. 想在每项前面加圆点、勾选图标，就在 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 自定义查询类型最核心的入门模式。

适用场景与方案对比

这篇的本质是「把任意 PHP 数组变成查询循环」的通用模板，Checkbox List 只是第一个例子。选型时有条经验：只想快速输出一串值、不在乎逐项样式，直接复制 Meta Box 给的 foreach 代码塞进 Code 元素最快；要的是每项能用 Basic Text、图标、条件样式自由排，才值得注册查询类型。把 rwmb_meta 换成 get_field 就能循环 ACF 多选值，换成 wp_get_post_terms 就能循环分类术语——数组从哪来不重要，拿到数组就能套同一套三件套。

常见问题（FAQ）

Q：一定要注册自定义查询类型吗？ A：不一定。只想快速输出值列表，用 Meta Box 字段说明里生成的 foreach 代码放进 Code 元素更快；要带样式逐项渲染才用查询循环。

Q：Checkbox List 和 Select 多选能共用这套吗？ A：能，两者存的都是数组，换一下字段 ID 即可复用同一个查询类型。

Q：循环项必须要有 ID 吗？ A：是，查询系统靠 ID 区分循环项；没有就自己在代码里造一个唯一 ID。

Q：ACF 字段能用同样方法吗？ A：能，把 rwmb_meta 换成 get_field 即可，其余结构一样。

延伸阅读

• 想要现成外贸独立站模板与建站实战？看 铲子铺 chanzipu 的外贸建站教程（同用 Bricks，从零搭出能收询盘的站）
• 相关阅读：Bricks Query Loop Api Data

站长

Ray Chan

WordPress Developer & Bricks Specialist

WordPress developer with 10+ years of client builds. Switched to Bricks in 2023 — now builds fast WordPress sites and migrates legacy Elementor/Divi projects.

获取报价 →浏览全部教程