Bricks 让元素输出 N 次（N = 自定义字段值）：Array 查询类型实战

⚠️ 原文为 BricksLabs Pro 付费教程，核心代码锁定。本文按可见步骤写场景 + 骨架，代码用 Bricks 官方钩子补全并标注「补全实现」。

场景：图标按字段数值重复 N 次

Bricks Facebook 群有人问：能不能让某个元素显示 x 次，其中 x 是自定义字段里存的数字？

例子很典型：页面用 ACF 建了一个 Number 类型字段 number_of_icons_to_display，某页填了 6，希望该页的图标元素（比如一排五星/技能图标）正好输出 6 个；另一个页填 3，就输出 3 个。元素重复次数完全由字段值驱动，而不是手写死。

Bricks 2.2 的 Array 查询类型

Bricks 2.2 新增了 Array 查询类型：它的“查询结果”就是一个 PHP 数组，循环体对数组的每个元素渲染一次。配合 {echo:函数名} 动态数据，函数返回什么数组，循环就渲染多少项——这正是“按字段值重复元素”的官方解法：写一个返回 [1, 2, ..., n] 的函数，n 来自自定义字段，Array 查询就会把元素渲染 n 次。

Step 1：返回 1..n 数组的函数（补全实现）

以下为补全实现（基于 Bricks 官方 {echo:} + Array 查询类型机制，非原文代码），放入子主题 functions.php（去掉开头 <?php）：

// 补全实现：返回 1..n 的数组，n 为指定自定义字段的值，非原文代码
function bl_range_from_field( $field_name = '', $post_id = null ) {
    $post_id = $post_id ?: get_the_ID();
    // 从自定义字段取值（ACF / Meta Box 通用，数据都在 wp_postmeta）
    $n = (int) get_post_meta( $post_id, $field_name, true );
    if ( $n < 1 ) {
        return []; // 值为空或小于 1 时不输出任何项
    }
    // 防御性上限，防止误填超大数字拖垮页面
    $n = min( $n, 100 );
    return range( 1, $n );
}

白名单注册，让函数可被 {echo:} 调用：

add_filter( 'bricks/code/echo_function_names', function( $names ) {
    return array_merge( $names, [ 'bl_range_from_field' ] );
} );

Step 2：查询设置与模板

1. 在页面里加一个 Block / Container，开启 Query Loop。

2. Query 类型选 Array，在数组值输入框（Array 查询类型的数据源）里填：

   {echo:bl_range_from_field:number_of_icons_to_display}

   其中 `number_of_icons_to_display` 换成你的字段名。`{echo:}` 会执行函数，把 `[1,2,...,n]` 作为查询结果交给循环。


3. 循环项模板里放图标元素（Icon 等）。由于 Array 查询的循环对象是数字本身，图标元素不需要依赖循环对象数据，直接静态渲染即可——循环会按数组长度重复它。





检查前台：字段值填 6 的页面输出 6 个图标，填 3 的页面输出 3 个，字段为空输出 0 个（配合 `{query_results_count}` 条件可以整体隐藏空区块）。














> **相关阅读：**


>


- [Bricks 内容切换器：纯 CSS 方案（radio + :has 实现标签切换）](/blog/a-css-approach-to-content-switcher-in-bricks/)


- [Bricks 用 ACF Checkbox 字段渲染自定义 SVG 图标列表](/blog/acf-checkbox-svg-bullets/)


- [Bricks 按 ACF Gallery 图片数量做动态条件输出](/blog/acf-gallery-images-count-condition/)


## 适用场景与常见坑

- **别把字段值填得太大**：函数里有防御上限（默认 100），防止误填超大数字一次性渲染几百个元素拖垮页面；真有大批量需求，按官方文档评估性能再放开。
- **字段为空 / 小于 1 时返回空数组**：此时循环不输出任何项，配合 `{query_results_count}` 条件可以整体隐藏空区块。
- **别忘白名单**：`{echo:}` 默认只执行白名单内函数，`bricks/code/echo_function_names` 没注册，函数不会被执行，前端安静地什么都不显示。

这套「Array 查询 + {echo:}」能玩的花样很多：按评分字段输出星级、按步骤数量输出编号、按数量重复技能条，改字段值即生效，全站统一。

## 中文小结





"按字段值重复元素"的现代解法 = **Array 查询类型 + {echo:} 动态数据**：自定义函数返回 `range(1, n)`，n 从 `get_post_meta` 读取，Array 查询把数组的每个元素渲染一次。相比老办法（复制多份元素 + 条件显隐），它完全由数据驱动、数量无上限、改字段即生效。这套组合的想象空间很大：星级评分（按评分字段输出星标）、技能条数量、步骤编号、重复任意组件块……核心就一句话——**Array 查询让"循环多少次"变得可编程**。

## 常见问题（FAQ）

**Q：Array 查询类型是 Bricks 哪个版本引入的？**
A：Bricks 2.2 新增的查询类型，查询结果就是一个 PHP 数组，循环体对每个元素渲染一次。

**Q：函数返回的数组怎么生成的？**
A：示例函数用 `range(1, n)` 生成，n 从自定义字段读取（`get_post_meta`），字段值填 6 就输出 6 项。

**Q：字段为空会怎样？**
A：函数返回空数组，循环不输出任何项；配合 `{query_results_count}` 条件可以整体隐藏空区块。

**Q：`{echo:}` 不生效怎么办？**
A：检查 `bricks/code/echo_function_names` 白名单有没有注册函数名，这是最常见的遗漏。

**Q：除了重复图标还能做什么？**
A：按评分输出星级、按数量输出步骤编号、重复任意组件块——「循环多少次」变成由数据驱动的可编程逻辑。



## 延伸阅读

- 想要现成外贸独立站模板与建站实战？看 [铲子铺 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.

获取报价 →浏览全部教程