把任意自定义 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/)

站长

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.

获取报价 →浏览全部教程