HappyFiles 文件夹图片用 Bricks Query Loop 输出（三种方式）

什么时候需要自己写查询

HappyFiles 是一款把 WordPress 媒体库图片整理进文件夹的插件。和传统的“图片塞进文章”不同，HappyFiles 用文件夹（内部实现为自定义分类法）来组织媒体库，图片本身还是 Media 库里的附件（attachment），只是被归到了某个分类下。它自带的 “HappyFiles – Gallery” Bricks 元素就能直接输出图片，开箱即用。

本文的三种查询循环方案，只在你想获得比官方元素更多控制权时才需要。典型场景包括：需要精确控制每张图的输出结构（比如图文混排、自定义卡片）、需要按自己的顺序排列、需要自定义灯箱内容，或者想把 HappyFiles 的图片和文章循环混排。下面按由简到繁介绍。

方式一：嵌套查询循环

假设要展示 “Business” 文件夹里的图片。需要两层循环：

1. 外层查询：遍历 “Business” 这个 HappyFiles 分类项（term）——HappyFiles 用自定义分类法 happyfiles_category 组织文件夹。

2. 内层查询：遍历 Business 文件夹里的 Media（attachment）文章。

结构上，外层是 Terms 查询（查询 happyfiles_category 分类法），内层是挂在其内部的 Media 查询循环（文章类型选 Media），图片元素放在内层循环里。想让图片点击后放大看原图，就把图片包进一个链接或灯箱结构。Bricks 的嵌套查询循环在构建器里直接搭就行，全程无需写代码，适合喜欢纯可视化操作的用户。官方还提供了完整的 Section JSON 可以一键粘贴。

方式二：单个 PHP 查询

如果不想用两层循环，或者需要在同一个循环里做更多逻辑（比如排序、过滤），可以在一个查询循环里启用 PHP 查询，粘贴：

// 查询 HappyFiles 分类里的附件
$args = [
  'post_type' => 'attachment',
  'post_status' => 'inherit',
  'posts_per_page' => -1,
  'fields' => 'ids',
  'no_found_rows' => true,
  'tax_query' => [
    [
      'taxonomy' => 'happyfiles_category',
      'field' => 'slug',
      'terms' => 'business',
    ],
  ],
];
$hf_query = new WP_Query( $args );
$image_ids = $hf_query->posts;
// 返回给 Bricks 的查询参数
if ( ! empty( $image_ids ) ) {
  return [
    'post_type' => 'attachment',
    'post_status' => 'inherit',
    'posts_per_page' => -1,
    'no_found_rows' => true,
    'post__in' => $image_ids,
    'orderby' => 'post__in',
  ];
}
// 返回空结果集
return [
  'post_type' => 'attachment',
  'post__in' => [ 0 ],
];

把 business 换成你的 HappyFiles 文件夹 slug。核心逻辑分两步：先用 tax_query 按 happyfiles_category 分类法查出文件夹里的图片 ID 数组（fields => 'ids' 只取 ID，省内存），再用 post__in + orderby => post__in 把这份 ID 列表原样返回给 Bricks，顺序由 ID 数组决定。文件夹为空时返回 post__in => [0] 这个空结果惯用写法。签名代码并保存。

相关阅读：

• Bricks 自定义查询类型：输出 Meta Box 可克隆字段

• Bricks 输出 Meta Box 图片高级字段的随机一张图

• Bricks 输出 Meta Box 设置页里选中文章的数据（PHP 查询实现）

方式三：BricksExtras Dynamic Lightbox

想完全控制每张图在灯箱里显示什么内容（比如大图、标题、描述、自定义链接），用 BricksExtras 的 Dynamic Lightbox 元素：

• 给 “Small Image”（缩略图）加一个 CSS 类 post-lightbox，并确保它链接到 #——这样点击缩略图时触发灯箱而不是跳转。

• Dynamic Lightbox 设置里指定大图来源，可以绑定到附件 URL 或自定义字段。

• 显示图片描述时，可以用 {x_attachment_description} 动态标签（花括号包裹）。

BricksExtras 为附件（图片）提供的其他动态标签：

• x_attachment_alt_text – 显示附件的替代文本

• x_attachment_title – 显示附件标题

• x_attachment_url – 显示附件图片 URL

• x_attachment_caption – 显示附件说明文字

这些标签配合查询循环，可以在灯箱里做出“图 + 标题 + 描述”的完整展示卡片，比 HappyFiles 官方元素的灯箱灵活得多。

小结：三套方案按需选——要纯构建器操作就用嵌套循环；要一个循环搞定、精确控制顺序就用 PHP 查询；要做高级灯箱交互就上 Dynamic Lightbox。HappyFiles 在 Bricks 里的玩法基本被这三条路覆盖全了。进阶用户可以三种混用：嵌套循环负责布局，PHP 查询负责取数，Dynamic Lightbox 负责交互，各取所长。

三种方式怎么选

决策很简单：纯构建器、不想碰代码 → 嵌套查询循环；要一个循环搞定、还想精确控制图片顺序 → 单个 PHP 查询；要做高级灯箱交互（图+标题+描述卡片） → BricksExtras Dynamic Lightbox。性能上三者和普通媒体库查询无异，瓶颈在图片数量和是否懒加载，别为了「控制权」硬上 PHP 查询——HappyFiles 官方 Gallery 元素开箱即用，只有当你需要图文混排、自定义排序或定制灯箱时才值得自己写。三者也能混用：嵌套负责布局、PHP 负责取数、Dynamic Lightbox 负责交互。

常见问题（FAQ）

Q：一定要自己写查询吗？ A：不一定，HappyFiles 自带 Gallery 元素开箱即用；只有要更细的控制（排序、图文混排、定制灯箱）才需自己写。

Q：三种方式性能差很多吗？ A：差别不大，瓶颈在图片数量和懒加载，按控制需求选即可。

Q：动态灯箱能显示标题和描述吗？ A：能，配合 x_attachment_* 动态标签可在灯箱里做「图+标题+描述」卡片。

Q：ACF 图集能用同样思路吗？ A：思路一致，取数换成 ACF Gallery 的取法即可。

延伸阅读

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

获取报价 →浏览全部教程