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} 条件可以整体隐藏空区块）。

中文小结

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