场景：附件数据直接复用
WordPress 媒体库里每张图片都自带元数据：Alt 文本、标题（Title）、说明文字（Caption）、描述（Description）。很多摄影师会用 Lightroom 之类的工具批量填好这些信息再同步进来，数据是现成的，但 Bricks 的图片元素默认只展示图片本身，Caption 一开还会盖在缩略图上。
于是常见需求是：在归档页的缩略图下方，把附件的 Alt/Caption/标题动态打出来。最笨的办法是给每个 CPT 文章再建字段手动复制粘贴——几百上千条内容时完全不现实。正解是注册几个自定义动态标签，从 ACF 图片字段返回的附件 ID 反查媒体库数据，在查询循环里直接插入。
Step 1：建 CPT 与 ACF 图片字段
- 在 ACF → Post Types 创建 CPT，比如
service（服务）。高级配置里打开 URLS 选项卡，启用 Archive（归档页），可以顺手填个归档 slug。 - 建字段组挂到该 CPT，加一个 Image 类型字段
service_image，Return Format 保持默认的 Image Array（返回数组，里面带附件 ID，这是下面代码能工作的前提）。 - 建若干服务文章，为每篇选一张图（图片在媒体库里已填好 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。
Step 3：归档页循环里输出
- 编辑
service的归档模板（或任意页面套查询循环），启用查询循环查全部service文章。 - 循环项结构：Featured Image（或图片元素绑定
{acf_service_image}）在上，下面放三个 Basic Text，分别插入动态数据{bl_acf_image_alt}、{bl_acf_image_caption}、{bl_acf_image_title}。 - 需要“点击图片看原图”的话，把图片包进链接元素，链接 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”的自定义逻辑也行。
小结：这套方案的核心是把“媒体库附件数据”当成可复用资产：ACF 图片字段的 Return Format 保持 Image Array，自定义动态标签用附件 ID 反查 _wp_attachment_image_alt（Alt）、post_excerpt（Caption）、post_title（Title）。同理还能扩展出 Description（post_content）、文件名（post_name）等更多标签，一套代码在任意查询循环里通用。