需求：模板库查询循环显示截图
Bricks 论坛里有用户问：Bricks 1.10 新版本给模板加了截图（screenshots）功能。他为自己的模板建了一个 Query Loop，想在这个循环里调用每张模板的截图，怎么实现？
这个需求的场景很典型：很多做 Bricks 模板站、主题展示站的人，会把模板作为一种内容（post type）来管理，然后用 Query Loop 把模板列表展示成卡片墙。每张卡片上如果能有模板的视觉截图，转化率会高很多——访客不用点进去就能看到模板长什么样。
Bricks 1.10（当时处于 beta）确实新增了 Template screenshots 支持，但要手动开启，而且自动生成的截图不会作为文章的特色图片（featured image）存在——这正是绕弯的地方。如果你直接把 Image 元素绑到特色图片上，得到的往往是空白，因为模板文章通常根本没有设置特色图片。
Step 1：开启模板截图功能
在 Bricks → Settings 里开启模板截图选项（默认关闭）。开启后：
- 编辑器的 Templates 对话框里可以按需生成截图（主要是为开启前已存在的模板补生成）。
- 所有模板会自动生成截图。
Step 2：定义取图函数
问题在于：如果你直接把 Image 元素的图片来源设为特色图片，Bricks 会先检查模板有没有特色图片，没有才去拉自动生成的模板截图——而模板通常没有特色图片，走的是自动截图逻辑。这个逻辑定义在 /wp-content/themes/bricks/includes/admin.php 里。
所以我们要定义一个自定义函数，先检查特色图片，没有就去找自动生成的截图文件：
<?php
function bl_get_bricks_template_image_url(): ?string {
$post_id = get_the_ID();
// 先检查文章是否有缩略图
if ( has_post_thumbnail( $post_id ) ) {
return get_the_post_thumbnail_url( $post_id, 'thumbnail' );
} else {
// 从自定义目录取自动生成的模板截图
$wp_upload_dir = wp_upload_dir();
$custom_dir = $wp_upload_dir['basedir'] . '/' . BRICKS_TEMPLATE_SCREENSHOTS_DIR . '/';
$custom_url = $wp_upload_dir['baseurl'] . '/' . BRICKS_TEMPLATE_SCREENSHOTS_DIR . '/';
$existing_files = glob($custom_dir . "template-screenshot-$post_id-*.webp");
$file_path = $existing_files[0] ?? null;
if ( $file_path ) {
return str_replace( $custom_dir, $custom_url, $file_path );
}
}
// 找不到图片返回 null
return null;
}代码思路：有特色图片就用特色图片；否则到上传目录里按 template-screenshot-{post_id}-*.webp 的命名模式找到自动生成的截图并返回其 URL；都没有就返回 null。glob 用通配符匹配的原因是：截图文件名里可能带时间戳或尺寸后缀，用 * 兜住变化的部分。注意 BRICKS_TEMPLATE_SCREENSHOTS_DIR 是 Bricks 定义的常量，直接拿来用即可。
Step 3：白名单与查询设置
先把函数加进 Bricks 白名单：
<?php
add_filter( 'bricks/code/echo_function_names', function() {
return [
'bl_get_bricks_template_image_url'
];
} );白名单里应包含你站点正在使用的其他函数，可在 Bricks → Settings → Custom code 的 Code review 里核对。详见 bricks/code/echo_function_names 文档。
然后在查询编辑器里用 PHP 设置查询循环：
return [
'post_type' => 'bricks_template',
'posts_per_page' => 100, // 大数字，拉全部
'no_found_rows' => true,
];**签名代码（Sign code）**并保存。bricks_template 是 Bricks 存放模板的文章类型，no_found_rows => true 告诉 WordPress 不需要统计总页数，能省一次 COUNT 查询。
最后添加一个 Image 元素，把图片来源设为：
{echo:bl_get_bricks_template_image_url}保存后前端就能看到：模板列表里每张模板都显示对应截图——有特色图片的用特色图片，否则用自动生成的模板截图。
小技巧：如果你只想在编辑器里预览效果，也可以临时把 posts_per_page 调小加快查询；正式上线再改回 100 或更多。另外，bricks_template 查询和普通文章查询一样支持 Bricks 的 Query Filters，模板多了以后可以加搜索和筛选，让访客按模板名快速定位。
小结：模板截图和特色图片是两套体系，直接设图片来源只能拿到特色图片。自定义函数把两条路都覆盖了，是模板库页、模板展示站的常见需求，代码量不大但逻辑完整。这套“自定义函数 + 白名单 + 动态标签”的组合拳在 Bricks 里非常通用，值得收藏备用。