把任意自定义 WP_Query 循环接入 Bricks 查询循环

— 有时候我们需要用 Bricks 的查询循环功能做自定义文章循环，但又想用自己的 WP_Query 代码来获得更多灵活性。 原因可能是：内置设置做不到某些事（比如某些 WP_Query 参数需要更动态的处理），也可能你手上正好有一段复杂查询的现成代码——直接粘贴代码比在 UI 里手动重建快得多。 ## 用 Bricks 的查询过滤器实现 Bricks 自带几个过滤器（filters），可以改变各种功能的行为，正是它们让这件事成为可能。 开发者文档是逐个了解这些过滤器的好资料。这里我们组合使用其中几个：注册一个新的查询类型，并给查询循环功能注入自定义的 WP_Query 参数（本篇末尾附有具体用到的过滤器文档链接）。 ## 添加代码片段 这段代码要添加在构建器之外——放在子主题的 functions.php 里，或用 WPCodeBox 之类的代码片段管理插件。 下面的代码负责三件事： - 在查询循环控件的「类型」（type）下拉里新增一个选项

• 选中该选项时执行我们的新查询（也就是自定义 WP_Query 代码）

• 设置全局文章数据（global post data） ```php /* Add new query type control to query options */ add_filter( ‘bricks/setup/control_options’, ‘bl_setup_query_controls’); function bl_setup_query_controls( $control_options ) {

  /* Adding a new option in the dropdown */ $control_options[‘queryTypes’][‘my_new_query_type’] = esc_html__( ‘My new WP Query’ );

  return $control_options;

};

/* Run new query if option selected */ add_filter( ‘bricks/query/run’, ‘bl_maybe_run_new_query’, 10, 2); function bl_maybe_run_new_query( $results, $query_obj ) {

if ( $query_obj->object_type !== 'my_new_query_type' ) {
    return $results;
}

/* If option is selected, run our new query */ 
if ( $query_obj->object_type === 'my_new_query_type' ) {
    $results = run_new_query();
}

return $results;

};

/* Setup post data for posts */ add_filter( ‘bricks/query/loop_object’, ‘bl_setup_post_data’, 10, 3); function bl_setup_post_data( $loop_object, $loop_key, $query_obj ) {

if ( $query_obj->object_type !== 'my_new_query_type' ) {
    return $loop_object;
}

 global $post;
 $post = get_post( $loop_object );
 setup_postdata( $post );

 return $loop_object;

};

/* Return results from our custom WP Query arguments */ function run_new_query() {

/* Add all of your WP_Query arguments here */

$args = [ 
    'post_type' => 'post',
    'orderby'        => 'rand',
    'posts_per_page' => '1',
];

$posts_query = new WP_Query( $args );

return $posts_query->posts;

}; ``` ### 改成你自己的查询 - 把前三段函数里出现的查询类型标识 my_new_query_type 改成更有意义的名字；

• 修改第一段函数里的显示名 My new WP Query（这就是它在设置面板里显示的名字）；

• 在最后一段函数里，往 $args 数组里填你自己的 WP_Query 参数。 ## 完成 保存后回到 Bricks，查询循环的「类型」下拉里就会出现这个新选项，选中它即可创建你自己的文章循环。 补充：可以看下 Ivan Nugraha 的这条 YouTube 视频教程，里面有基于 ACF relationship 字段展示文章的完整实例：https://www.youtube.com/watch?v=JLCdFATDdvg ## 添加多个自定义查询 想把上面的代码扩展成支持多个新查询类型？下面是个现成例子，用 my_first_custom_query 和 my_second_custom_query 命名，方便阅读和改成你自己的： ```php /* Add new query type controls to query options */ add_filter( ‘bricks/setup/control_options’, ‘bl_setup_query_controls’); function bl_setup_query_controls( $control_options ) {

  /* Adding new options in the dropdown */ $control_options[‘queryTypes’][‘my_first_custom_query’] = esc_html__( ‘My first WP Query’ ); $control_options[‘queryTypes’][‘my_second_custom_query’] = esc_html__( ‘My second WP Query’ );

  return $control_options;

};

/* Run new query if option selected */ add_filter( ‘bricks/query/run’, ‘bl_maybe_run_new_queries’, 10, 2); function bl_maybe_run_new_queries( $results, $query_obj ) {

if ( $query_obj->object_type === 'my_first_custom_query' ) {
    $results = run_first_query();
}

if ( $query_obj->object_type === 'my_second_custom_query' ) {
    $results = run_second_query();
}

return $results;

};

/* Setup post data for posts */ add_filter( ‘bricks/query/loop_object’, ‘bl_setup_post_data’, 10, 3); function bl_setup_post_data( $loop_object, $loop_key, $query_obj ) {

/* setup post data if using any of our custom queries */
if ( $query_obj->object_type === 'my_first_custom_query' || $query_obj->object_type === 'my_second_custom_query' ) {
	
   global $post;
   $post = get_post( $loop_object );
   setup_postdata( $post );
	
}

return $loop_object;

};

/* first WP Query arguments */ function run_first_query() {

/* Add all of your WP_Query arguments here */
$args = [ 
    'post_type' => 'post',
    'orderby'        => 'rand',
    'posts_per_page' => '2',
];

$posts_query = new WP_Query( $args );

return $posts_query->posts;

};

/* second WP Query arguments */ function run_second_query() {

/* Add all of your WP_Query arguments here */
$args = [ 
    'post_type' => 'post',
    'orderby'        => 'rand',
    'posts_per_page' => '1',
];

$posts_query = new WP_Query( $args );

return $posts_query->posts;

};

>


- [ACF Relationship 字段 + Bricks 查询循环：显示关联文章](/blog/acf-relationship-query-loop/)


- [HappyFiles 文件夹图片的 Bricks 查询循环：三种取图方案](/blog/happyfiles-bricks-query-loop/)


- [Meta Box Relationship 字段 + Bricks 查询循环：显示关联文章](/blog/metabox-relationship-query-loop/)


## 相关教程 更多创建自定义查询循环、或改造现有查询类型以覆盖 Bricks 常见用例的实用代码示例，见 [Query Loop Tutorials](/topic/query-loop)。 过滤器文档参考： > [Filter: bricks/query/run](https://academy.bricksbuilder.io/article/filter-bricks-query-run/) > [Filter: bricks/setup/control_options](https://academy.bricksbuilder.io/article/filter-bricks-setup-control_options/) > [Filter: bricks/query/loop_object](https://academy.bricksbuilder.io/article/filter-bricks-query-loop_object/)

## 常见坑与性能提醒

- **`setup_postdata` 别省**：循环对象只给了文章 ID，不调 `setup_postdata`，循环项里的 `get_the_title()`、`the_content()` 这类函数就拿不到正确上下文，动态数据会串场。
- **`object_type` 判断要精确**：回调里先判断 `$query_obj->object_type !== 'my_new_query_type'` 再返回原结果，避免误伤其它查询。
- **注意查询开销**：自定义 WP_Query 是独立数据库查询，循环里别套循环；数据量大时给 `$args` 加上分页参数，一次只取一页（具体分页写法按官方文档补全）。

## 常见问题（FAQ）

**Q：代码要放在哪里？**
A：子主题的 `functions.php`，或用 WPCodeBox 之类的代码片段管理插件，不要直接放会被主题更新覆盖的文件里。

**Q：为什么循环里要调 `setup_postdata`？**
A：Bricks 的循环对象是文章 ID，不调它，模板标签（`get_the_title()` 等）拿不到正确上下文，循环项内容会串。

**Q：怎么添加多个自定义查询类型？**
A：文中有现成的双查询示例：分别注册 `my_first_custom_query`、`my_second_custom_query`，在 `bricks/query/run` 回调里按 `object_type` 分流执行。

**Q：会影响页面性能吗？**
A：自定义 WP_Query 是独立查询，注意别在循环里套循环；数据量大时加分页参数，一次只取一页更稳。



## 延伸阅读

- 想要现成外贸独立站模板与建站实战？看 [铲子铺 chanzipu 的外贸建站教程](https://chanzipu.com/)（同用 Bricks，从零搭出能收询盘的站）
- 相关阅读：[Bricks Query Loop Api Data](/blog/bricks-query-loop-api-data/)

## 相关阅读

- [Bricks 查询循环的分面筛选（Faceted Search）](/blog/bricks-query-filters-faceted-search/)
- [Bricks Form Builder 完整指南](/blog/bricks-form-builder-complete-guide/)

站长

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.

获取报价 →浏览全部教程