Bricks Query Loop 从 API 拉数据——REST/外部 JSON 接口展示教程

Bricks 2.1 起，Query Loop 可以直接从外部 API 拉 JSON，把返回的数组当循环项渲染。数据不在 WordPress 里时用这个功能：外部库存系统的产品、公开 API 的食谱/图书/活动/职位、另一个 WordPress 站的 REST API、自定义后端的结构化数据、暴露 JSON 端点的表格或无代码工具。

注意：API 查询循环目前标记为 experimental，不支持 Query Filters、实时搜索和 Bricks 组件。

API 查询的生命周期

整个流程官方文档写得非常清楚：

1. 循环元素查询类型设为 API；
2. 在 API Settings 弹窗里配置请求；
3. Bricks 解析大部分 API 设置里的动态数据；
4. 构造请求 URL、请求头、鉴权、请求体和分页参数；
5. 开了缓存就先查缓存；
6. 通过 WordPress 发请求；
7. 解码 JSON 响应；
8. 提取配置好的响应路径；
9. 提取到的数组就是查询结果；
10. 每个数组项渲染一次循环。

只有数组能循环。响应路径解析出来是对象、字符串、数字或缺失路径时，循环渲染不出预期的结果集。

创建 API 查询循环

步骤：

1. 加一个支持循环的元素（Container、Block 或 Div）；
2. 开启 Query Loop；
3. Type 设为 API；
4. 点 API Settings；
5. 填 API URL 和请求设置；
6. 在预览面板点 Fetch；
7. 设置响应路径，让它解析到你想要循环的数组；
8. 保存 API 设置；
9. 在循环内加子元素；
10. 用 {query_api} 动态标签渲染每个数组项的字段。

API 设置弹窗与请求配置

弹窗左侧是控件、右侧是响应预览。先做预览再做设计——Bricks 拉不到或解析不了响应，就先修请求。

请求设置

Bricks 发送的默认请求头：

Content-Type: application/json
User-Agent: BricksBuilder/{CURRENT_VERSION}

URL 参数示例：

动态数据支持

API 配置里大部分字符串设置都能用 Bricks 动态数据，包括 URL、请求头、参数、请求体值和直接存进设置的鉴权值。故意不解析动态数据的只有两个：API Name 和 响应路径。

动态设置会在请求时按当前页面上下文解析，很适合依赖当前文章/用户/分类/URL 状态的端点：

https://example.com/api/events?city={acf_city}

{
  "postId": "{post_id}"
}

鉴权：API Key、Bearer、Basic Auth 与 PHP 常量

Bricks 支持三种鉴权：API key、Bearer token、Basic Auth。API Key 可以放在请求头或 URL 参数里；Bearer 和 Basic Auth 走 Authorization 请求头。

敏感值请开启 Use PHP Constant——Bricks 从 PHP 常量读密钥，而不是把值存在构建器里。常量名基于查询元素 ID（大写）：

define( 'BRX_QUERY_API_KEY_ABC123', 'your-api-key' );
define( 'BRX_QUERY_BEARER_TOKEN_ABC123', 'your-token' );
define( 'BRX_QUERY_BASIC_AUTH_USERNAME_ABC123', 'username' );
define( 'BRX_QUERY_BASIC_AUTH_PASSWORD_ABC123', 'password' );

把 ABC123 换成大写的查询元素 ID。生产环境凭据务必用常量——存在构建器里的密钥容易被导出、截图或团队协作者看到。

响应路径与 query_api 动态标签

Response path 告诉 Bricks JSON 响应的哪一部分变成循环结果。顶层响应本身就是要循环的数组时留空；嵌套数据用点号：

data.results

例如响应长这样：

{
  "data": {
    "results": [
      { "name": "Recipe A" },
      { "name": "Recipe B" }
    ]
  }
}

响应路径就设 data.results。路径缺失时 Bricks 回退到完整解码响应——如果完整响应不是目标数组，循环就渲染不对。

循环内部用 query_api 动态数据标签渲染字段：

{query_api @key:'name'}

嵌套字段用竖线分隔键：

{query_api @key:'title|rendered'}

竖线表示当前数组项内部的嵌套键。在 API 响应预览里悬停字段可直接复制现成的动态标签，也可以创建出现在 Dynamic Data 选择器里的快捷方式。注意：快捷方式存在浏览器 localStorage，不存数据库、不跨浏览器共享。

分页：页码分页与偏移分页

API 查询循环支持分页，前提是 API 能接收 page 或 offset 参数，且响应暴露了页数或条数。启用步骤：API 设置里开 Pagination → 页面加 Pagination 元素 → 让它指向 API 查询 → 选分页方法 → 配置参数位置（URL 参数 / Header / 请求体）→ 配置总数路径。

页码分页（Page Number Pagination）

API 期望页码时用，例如 page=3。WordPress REST API 示例：

页码分页时，Bricks 把提取到的总数当总页数。

偏移分页（Offset Pagination）

API 期望 offset/skip 值时用，例如 limit=5&skip=10。配置要点：

• Page parameter：Bricks 要更新的 offset/skip 参数
• Offset key：包含每页条数值的参数或头
• 每页条数值要保持在 URL 参数或头里，Bricks 才能算页数
• Total path 设成数字型总条数

偏移分页时，Bricks 用总条数除以每页条数计算总页数。

缓存与错误状态

缓存时长大于 0 时，API 响应用 WordPress transient 缓存。默认 300 秒。设置建议：

缓存键包含端点、方法、请求头、URL 参数和请求体——不同请求参数产生不同缓存条目。响应不更新时：调短缓存、临时设 0，或点 API 设置弹窗里的 Fetch 清掉该元素的 API 缓存。

常见错误状态：端点缺失/无效、WordPress 请求错误、HTTP 401/403/404/500、空响应体、JSON 解码失败、分页配置无效、分页缺 total path、响应路径没解析到预期数据。

常见修法：

• 浏览器或 API 客户端先测端点
• 确认 API 返回的是 JSON 不是 HTML
• 检查鉴权值或 PHP 常量
• 只有自定义前端脚本直连 API 才查 CORS（Bricks 服务端请求走 WordPress）
• 响应路径指向数组，不是单个对象
• 调试期临时把缓存时长设 0

实战例子：WordPress REST API 文章

URL：

https://example.com/wp-json/wp/v2/posts

URL 参数：

响应路径：留空——WordPress REST API 顶层就是数组。

渲染字段：

{query_api @key:'title|rendered'}
{query_api @key:'excerpt|rendered'}

另一个 WordPress 站的 REST API 同理：https://example.com/wp-json/wp/v2/posts 加上 per_page 参数即可。

实战例子：DummyJSON 商品

URL：

https://dummyjson.com/products

URL 参数：

响应路径：

products

渲染字段：

{query_api @key:'title'}
{query_api @key:'price'}
{query_api @key:'thumbnail'}

DummyJSON 这类公开测试 API 很适合先练手：预览 → 设路径 → 拖字段 → 调分页，全流程走一遍就知道 API 查询循环的脾气了。

局限性与排错

API 查询循环刻意比文章/分类/用户查询窄，当前限制：

• ❌ 不支持 Query Filters
• ❌ 不支持实时搜索
• ❌ 不支持 Bricks 组件
• 只支持 JSON 响应
• 响应数据必须解析成数组
• 除 query_api 动态标签外没有内置 schema 映射
• 不自动从远程 URL 导入媒体
• 对限流 API 没有自动重试/退避
• 密钥要小心处理（用 PHP 常量）

如果需求里有筛选、搜索、排序或复杂数据关联，官方建议把外部数据同步进 WordPress，或做自定义集成。

排错速查

想更系统地玩 Query Loop，可以配合本站的 Bricks 动态数据标签指南 和 ACF 关系字段 Query Loop 用法 一起看。

小结

API 查询循环 = API 设置弹窗配请求 → Fetch 预览 → 响应路径定数组 → query_api 标签渲染字段 → 分页/缓存收尾。适合展示不在 WordPress 里的 JSON 数据，尤其是 WordPress REST API 和公开 API。记住三件事：响应路径必须指向数组；密钥用 PHP 常量别存构建器；它不支持筛选/搜索/组件——需要这些能力就把数据同步进 WordPress。

站长

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.

获取报价 →浏览全部教程