Bricks 查询循环输出 ACF 图片字段的 Alt、Caption、标题数据

场景：附件数据直接复用

WordPress 媒体库里每张图片都自带元数据：Alt 文本、标题（Title）、说明文字（Caption）、描述（Description）。很多摄影师会用 Lightroom 之类的工具批量填好这些信息再同步进来，数据是现成的，但 Bricks 的图片元素默认只展示图片本身，Caption 一开还会盖在缩略图上。

于是常见需求是：在归档页的缩略图下方，把附件的 Alt/Caption/标题动态打出来。最笨的办法是给每个 CPT 文章再建字段手动复制粘贴——几百上千条内容时完全不现实。正解是注册几个自定义动态标签，从 ACF 图片字段返回的附件 ID 反查媒体库数据，在查询循环里直接插入。

Step 1：建 CPT 与 ACF 图片字段

1. 在 ACF → Post Types 创建 CPT，比如 service（服务）。高级配置里打开 URLS 选项卡，启用 Archive（归档页），可以顺手填个归档 slug。

2. 建字段组挂到该 CPT，加一个 Image 类型字段 service_image，Return Format 保持默认的 Image Array（返回数组，里面带附件 ID，这是下面代码能工作的前提）。

3. 建若干服务文章，为每篇选一张图（图片在媒体库里已填好 Alt/Caption 等）。

Step 2：注册 4 个自定义动态标签

把下面代码加到子主题 functions.php 或代码片段插件：

add_filter( 'bricks/dynamic_data/tags', function( $tags ) {
  $tags['bl_acf_image_alt']     = [ 'label' => 'BL ACF Image Alt',     'render' => 'bl_acf_image_data' ];
  $tags['bl_acf_image_caption'] = [ 'label' => 'BL ACF Image Caption', 'render' => 'bl_acf_image_data' ];
  $tags['bl_acf_image_title']   = [ 'label' => 'BL ACF Image Title',   'render' => 'bl_acf_image_data' ];
  $tags['bl_acf_image_url']     = [ 'label' => 'BL ACF Image URL',     'render' => 'bl_acf_image_data' ];
  return $tags;
} );
function bl_acf_image_data( $tag, $post, $context, $name ) {
  if ( ! function_exists( 'get_field' ) ) {
    return '';
  }
  $img = get_field( 'service_image', $post->ID );
  if ( empty( $img['ID'] ) ) {
    return '';
  }
  switch ( $name ) {
    case 'bl_acf_image_alt':
      // 附件的 Alt 存在 _wp_attachment_image_alt 这个 meta 里
      return get_post_meta( $img['ID'], '_wp_attachment_image_alt', true );
    case 'bl_acf_image_caption':
      // 附件的 Caption 就是附件的 post_excerpt
      return get_post_field( 'post_excerpt', $img['ID'] );
    case 'bl_acf_image_title':
      return get_the_title( $img['ID'] );
    case 'bl_acf_image_url':
      return wp_get_attachment_url( $img['ID'] );
  }
  return '';
}

要点：

• bricks/dynamic_data/tags 是 Bricks 注册自定义动态标签的官方钩子，每个标签配一个 render 回调；回调参数 $name 就是被调用的标签名，所以 4 个标签可以共用一个渲染函数；

• 查询循环里渲染时，$post 就是当前循环项的文章，get_field( 'service_image', $post->ID ) 取到图片数组（含 ID、url、alt、sizes 等）；

• Alt 文本不在附件文章本身，而在 _wp_attachment_image_alt 这个 meta 键里，必须用 get_post_meta 取——这是最常见的坑；

• Caption 对应附件的 post_excerpt，Title 对应附件的 post_title，URL 用 wp_get_attachment_url。

相关阅读：

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

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

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

Step 3：归档页循环里输出

1. 编辑 service 的归档模板（或任意页面套查询循环），启用查询循环查全部 service 文章。

2. 循环项结构：Featured Image（或图片元素绑定 {acf_service_image}）在上，下面放三个 Basic Text，分别插入动态数据 {bl_acf_image_alt}、{bl_acf_image_caption}、{bl_acf_image_title}。

3. 需要“点击图片看原图”的话，把图片包进链接元素，链接 URL 用 {bl_acf_image_url}。

保存后刷新归档页：每张缩略图下方自动出现该图片在媒体库里维护的 Alt、Caption 和标题。以后在媒体库改任何一条数据，前端全部自动更新——图片没换，字段没换，纯靠动态标签读取附件数据。

两点补充：

• 性能无忧：get_post_meta、get_post_field、get_the_title 读的都是附件对象和 meta 缓存，每个标签只多一次内存级查询，归档页几十上百张图毫无压力，不需要担心 N+1 问题；

• 场景延伸：这套标签不限于归档页的文章循环——ACF Repeater 循环（图片子字段）、Meta Box Group 循环、甚至单篇文章里手动插入，只要代码里 get_field 的对象是当前上下文，标签一律通用。图片字段换成“从 CPT 文章反查附件 ID”的自定义逻辑也行。

常见误区与维护建议

• Return Format 选错：图片字段的 Return Format 必须保持 Image Array（返回数组），选成 Image URL 或 Image ID，代码里 $img['ID'] 就拿不到了——这是这类标签最常见的翻车点。
• Alt 是附件的数据，不是文章的数据：Alt 存在媒体库附件的 _wp_attachment_image_alt 里，维护时要进媒体库批量编辑，而不是去文章里找。
• 顺手把图片 SEO 做了：Alt / Caption / 标题填得规范，本身就是图片搜索流量的基础，这套标签让归档页也能把这些附件数据用起来，别浪费。

小结：这套方案的核心是把“媒体库附件数据”当成可复用资产：ACF 图片字段的 Return Format 保持 Image Array，自定义动态标签用附件 ID 反查 _wp_attachment_image_alt（Alt）、post_excerpt（Caption）、post_title（Title）。同理还能扩展出 Description（post_content）、文件名（post_name）等更多标签，一套代码在任意查询循环里通用。

常见问题（FAQ）

Q：图片字段的 Return Format 必须设成什么？ A：保持默认的 Image Array（返回数组），代码里才能取到 $img['ID'] 反查附件数据；设成 URL 或 ID 会导致标签取不到值。

Q：附件的 Alt 存在哪里？ A：存在 _wp_attachment_image_alt 这个 meta 键里，必须用 get_post_meta 取，这是最常见的坑。

Q：这套标签只用在归档页吗？ A：不限于归档页的文章循环。ACF Repeater 循环、Meta Box Group 循环、单篇文章手动插入都能用，只要 get_field 的对象是当前上下文。

Q：性能有影响吗？ A：get_post_meta、get_post_field 读的都是附件对象和 meta 缓存，每个标签只多一次内存级查询，几十上百张图毫无压力。

Q：怎么扩展出 Description 或文件名？ A：按同样模式加标签即可：Description 对应附件的 post_content，文件名对应 post_name。

延伸阅读

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

站长

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.

获取报价 →浏览全部教程