Bricks Query Filters 分面搜索教程——无插件实现筛选、排序与实时搜索

Bricks 自带一套「Query Sort, Filter & Live Search」系统（官方叫 Query Filters）：让访客不用刷新页面就能改 Query Loop 的查询结果——加搜索框、复选框、单选框、下拉、区间滑杆、日期选择、提交/重置按钮、当前筛选展示和 AJAX 分页。本文按官方文档拆解这套系统的完整用法。

Query Filters 是什么

Query Filters 是 Bricks 内置的分面筛选系统，适合做这类交互式列表：

• 博客归档筛选
• 产品筛选
• 目录搜索
• 团队成员/人才筛选
• 分类、自定义字段、WordPress 字段筛选
• 排序控件
• 每页条数控件
• 实时搜索框

筛选元素可以放在页面任意位置——侧边栏、页头、Offcanvas 或列表上方都行，只要每个筛选元素正确指向目标查询即可。

三步启用与心智模型

启用路径：Bricks > Settings > Query filters，打开 Enable query sort / filter / live search，保存后进编辑器，从 Filter 元素组拖元素。

启用后 Bricks 会自动检查并维护用于筛选元素、筛选值和后台索引任务的自定义数据库表。

心智模型就三句话：

1. 筛选元素收集访客输入；
2. 目标查询循环接收筛选状态；
3. Bricks 把筛选状态转成查询参数，刷新目标循环。

首次页面加载时，Bricks 可以从 URL 参数读取筛选值；交互过程中，JavaScript 存储选中状态、按需更新浏览器 URL、发 AJAX 请求、拿回更新后的循环 HTML、刷新动态筛选元素并恢复焦点。服务端则做消毒、按目标查询类型构造查询变量、合并进原查询并重新渲染。

支持的查询类型

嵌套查询场景下，筛选器只能作用于外层受支持的查询层，别指望循环外的筛选器能命中深层子查询。

组件限制

筛选元素不要放进 Bricks 组件里；目标查询循环也不能是组件内的循环（除非组件根节点本身就是查询循环）。原因是筛选器要按具体的查询元素 ID 定位，AJAX 需要稳定地找到并渲染对应查询元素。

基础搭建：目标查询 + 筛选元素

搭建步骤：

1. 建一个 Query Loop；
2. 复制目标查询 ID——通常是 Bricks 元素 ID 里 #brxe- 后面的六位字符；
3. 加一个或多个 Filter 元素；
4. 在每个筛选元素上设置 Target Query；
5. 列表要分页就加 Pagination 元素，并开启 AJAX 让分页和筛选协同；
6. 测试：首次加载、AJAX 更新、浏览器返回键、直接带 URL 参数访问。

Apply On Input 还是 Submit

8 种筛选元素逐个说

Filter - Search

搜索筛选向目标查询发送文本值。文章查询默认走 s 查询变量，分类和用户查询走对应类型的搜索参数，也可以配置自定义搜索条件。

关键设置：

• Target Query：要刷新的查询循环
• URL parameter：前端参数名，要与原生 WordPress 搜索联动就用 s
• Debounce：打字后延迟多久才搜索
• Min. characters：最少输入几个字符才触发搜索
• Search Criteria：自定义字段、文章字段、分类字段、用户字段、分类法及加权选项
• Clear icon：允许访客一键清空搜索值

当 URL 参数是 s 且作用于主搜索查询时，Bricks 会优先使用当前 Search 模板上的搜索条件，而不是单个筛选元素的设置。

Filter - Checkbox

多选场景用复选框。支持数据源：

选中多个分类法或自定义字段值时，可按筛选设置用 OR 或 AND 逻辑组合。

Filter - Radio

单选场景用单选框，可充当三种角色：筛选器、排序控件、每页条数控件。同样支持 Taxonomy、WordPress 字段、自定义字段数据源和按钮式显示。

Filter - Select

紧凑下拉，可做筛选、排序或每页条数。开启 Choices.js 和多选后支持多值，多值规则同复选框筛选。

Filter - Range

数字型自定义字段（价格、面积、评分、分数）用区间滑杆，构造数值 BETWEEN 查询。Bricks 能用索引里的 min/max 自动设定滑杆范围。值含小数时必须设置小数位数，否则数值比较会出错。

Filter - Datepicker

日期字段用日期选择器，支持单日期和日期区间两种模式。Bricks 会消毒日期值，区间会转成双值格式再构造查询变量。

Filter - Active Filters

展示当前已选的筛选并允许移除。选项包括：排除指定筛选 ID、单个筛选上配置的前缀/后缀/标题标签、当前筛选标签与移除按钮的样式。

Filter - Submit / Reset

筛选攒着不刷时用 Submit，重置用 Reset。Submit 可以跳转到另一个 URL 并保留当前筛选值——典型场景是首页搜索框把访客带到搜索结果页。Reset 在无激活筛选时可自动隐藏（Bricks 会加一个类便于样式化）。

Bricks 2.4 起 Submit 元素还会为 AJAX 提交发出专门的 submit 开始/结束事件，可用 Filter Submit interaction triggers 让其他元素只在「用户刻意提交」时响应——例如移动端筛选结果加载完再关 Offcanvas。

Pagination 参与筛选

Pagination 在开启 AJAX 且指向同一查询时纳入筛选系统：Bricks 把分页当筛选状态处理，让「已选筛选 + 当前页码」保持一致。多个 Pagination 指向同一查询时，Bricks 会同步更新这些分页实例的当前页状态。

筛选值如何变成查询参数

Bricks 在后期合并筛选变量，让激活的筛选能收窄或覆盖原查询；当前归档路由等页面级上下文也会保留并合并（除非关闭）。

URL 参数与浏览器历史

Query Filters 支持从 URL 参数加载，两种风格：

• brx_FILTERID=value——默认格式，低摩擦内部参数
• 自定义友好名，例如 category=shirts——在筛选元素上配置，URL 更可读

页面加载时 Bricks 读 URL 参数 → 找到匹配筛选元素 → 按筛选类型消毒值 → 设置当前值 → 把查询变量合并进目标查询。若想让循环忽略 URL 参数，在目标 Query Loop 上开启 Disable URL Params Filter。

开启 URL 参数后，Bricks 会把筛选变化记进浏览器历史，访客可以用后退/前进在筛选状态间切换。Bricks 监听浏览器导航、恢复目标查询的筛选值、走同样的 AJAX 流程刷新列表。页面上有自定义脚本改写 URL 时务必测一下这个场景。

交互触发器（Interactions）

Bricks 为筛选状态和提交提供触发器：

经典用法：给「当前筛选」标题 + Active Filters 元素套个外层容器，加两个交互——Filter: Empty 隐藏、Filter: Not empty 显示。没激活筛选时整块隐藏，有筛选时才出现。

自定义字段与筛选索引

Query Filters 对「能被索引和比较的简单值」效果最好。默认简单自定义字段按普通值索引；序列化数组或复杂对象存的自定义字段不适合当默认筛选源，可能需要开 Custom fields integration 才能正确索引。

被索引的筛选元素类型：Checkbox、Datepicker、Radio、Range、Select。Search、Submit、Active Filters、Pagination 是动态筛选控件，不走同样的索引。

在 Bricks > Settings > Query filters 开启 Custom fields integration 后，筛选源选 Custom Field 时会显示 Provider 控件（有支持的插件时），再用 Meta key 里的动态数据选择器选字段。内置集成支持 Advanced Custom Fields 和 Meta Box：ACF 支持关系、文章对象、用户、真/假、选择、日期、日期时间等字段；Meta Box 支持多选字段及文章、分类、用户、日期字段（Meta Box 自定义表字段不支持）。

筛选索引（Filter Index）

Bricks 用自定义表存筛选数据，方便高效生成选项和数量。索引跟踪：筛选元素及设置、元素是否激活可索引、文章/分类/用户被索引的值、后台索引任务与进度。站点大时可能需要后台任务跑完，每个筛选选项才准确。

在 Bricks > Settings > Query filters 可管理索引：

• Regenerate filter index：重建所有可索引筛选元素的索引记录
• Continue index job：立即执行待处理的索引任务（不等 cron）
• Fix corrupted database：筛选元素缺失/过期/移动时重建元数据

站点开了 HTTP 认证的话，后台索引可能因 Bricks 够不到自己的后台端点而失败，需要给远程请求加认证头：

add_filter( 'bricks/remote_post', function( $args, $url ) {

  if ( strpos( $url, 'action=bricks_background_index_job' ) === false && strpos( $url, 'action=bricks_system_info_wp_remote_post_test' ) === false ) {

    return $args;

  }

  $username = 'USERNAME';
  $password = 'PASSWORD';
  $args['headers']['Authorization'] = 'Basic ' . base64_encode( $username . ':' . $password );

  return $args;
}, 10, 2 );

实时搜索（Live Search）与动态标签

Live Search 让结果只在发生搜索交互后显示。搭建：

1. 加 Filter - Search 元素；
2. 建一个文章/分类/用户 Query Loop；
3. Search 筛选的 Target Query 指向该循环；
4. 目标查询设置里开启 Live Search；
5. 设置 Live Search Wrapper Selector 为应显示/隐藏结果区域的外层容器。

Bricks 用这个选择器隐藏空的实时搜索结果、AJAX 期间显示加载器、访客点击搜索/结果区外时隐藏结果框。首次加载时 Bricks 仍会准备查询（保证脚本、样式、模板、弹窗内容可用），只是前端先抑制输出，等访客搜索。

动态数据标签

生成的计数 span 可以样式化：

span[data-brx-af-count] {
  /* Your styles here */
}

搜索条件与自定义标签

文章搜索条件可搜：文章字段、文章 meta 键、分配的分类与分类法；分类可搜：分类字段、分类 meta 键；用户可搜：用户字段、用户 meta 键。加权搜索按相关度返回 ID 顺序，Bricks 在无排序筛选激活时保留该顺序。每加一个字段或分类法查询都会变贵，搜索面要保持聚焦。

Checkbox、Radio、Select 筛选支持自定义选项标签——存的值不友好时用它映射，例如把 _stock_status 的值映射成「In stock / Out of stock」。

每页条数（Results Per Page）

Filter - Select 和 Filter - Radio 可当「每页条数」控件，默认值：

10, 20, 50, 100

在 Options: Results per page 里改，逗号分隔允许的页大小。激活值只改变被筛选请求的目标查询页大小，不重写原查询循环设置。若 Active Filters 不想列出每页条数，在 Active Filters 设置里排除该筛选元素 ID。

WooCommerce 筛选来源

装了 WooCommerce 后，支持的筛选元素会多出 WooCommerce 数据源，Select/Radio 还能用 WooCommerce 排序选项：

产品查询循环上常见的组合：产品分类/属性筛选 + 库存状态 + 价格区间 + 评分 + 价格排序。相关教程可看 Bricks 产品归档模板构建。

实战套路与排错

四个常见套路

1. 归档筛选侧边栏：Query Loop 当归档主查询，侧边栏放分类法筛选，开 AJAX 分页，保持 query merge 开启让循环尊重当前归档路由。
2. 产品筛选：分类法筛选管分类和属性、Range 管价格、Checkbox/Select 管库存、Select 管排序。加完新筛选记得重建筛选索引。
3. 原生 s 搜索页：Filter - Search 的 URL 参数设 s、目标设主搜索查询、搜索条件在 Search 模板上配。
4. 首页实时搜索：Filter - Search + Submit 跳转，或用 Live Search + wrapper 选择器让结果内联显示。

常见问题速查

更多 Query Loop 基础知识可看本站的 Bricks 动态数据标签指南 和 文章归档模板构建。

小结

Bricks Query Filters 是一套完整的分面搜索方案：Filter 元素收集输入 → 目标查询接收 → Bricks 转查询参数 → AJAX 刷新循环。8 种筛选元素覆盖搜索、多选、单选、下拉、区间、日期、当前筛选展示和提交/重置；配合 URL 参数、浏览器历史、筛选索引和 WooCommerce 数据源，绝大多数筛选场景都不用装第三方插件。唯一要记住的硬限制：API 查询和 Array 查询不支持筛选，复杂自定义字段要先开 Custom fields integration。

延伸阅读

• 相关阅读：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.

获取报价 →浏览全部教程