Bricks Templates Query Loop：在查询循环里显示模板截图

需求：模板库查询循环显示截图

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 定义的常量，直接拿来用即可。

相关阅读：

• Bricks 内容切换器：纯 CSS 方案（radio + :has 实现标签切换）

• Bricks 用 ACF Checkbox 字段渲染自定义 SVG 图标列表

• Bricks 按 ACF Gallery 图片数量做动态条件输出

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 里非常通用，值得收藏备用。

注意事项

模板截图功能有几个前提要确认：一是截图是 Bricks 1.10 才加的，老版本模板没有截图，函数里要用「有特色图用特色图、否则用自动截图」的兜底；二是截图是模板保存时生成的，改了模板设计要重新保存才会更新缩略图，别以为实时变；三是 bricks_template 是 Bricks 内部文章类型，查询它和普通文章查询一样支持 Query Filters，模板多了可以加搜索/筛选。另外代码放 PHP 查询编辑器后记得**签名（Sign code）**保存才生效。

常见问题（FAQ）

Q：为什么有的模板没截图？ A：截图是 Bricks 1.10 才加的，老模板没有；函数已做「无截图用特色图」兜底。

Q：改了模板截图没更新？ A：截图在保存模板时生成，重新保存一次模板才会刷新缩略图。

Q：bricks_template 能用查询筛选器吗？ A：能，它和普通文章查询一样支持 Bricks 的 Query Filters，模板多了可加搜索筛选。

Q：代码放进去没效果？ A：在 PHP 查询编辑器里点 Sign code 签名保存，未签名不生效。

延伸阅读

• 想要现成外贸独立站模板与建站实战？看 铲子铺 chanzipu 的外贸建站教程（同用 Bricks，从零搭出能收询盘的站）
• 相关阅读：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.

获取报价 →浏览全部教程