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] 这个空结果惯用写法。签名代码并保存。

方式三：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 负责交互，各取所长。