Bricks 将 WooCommerce 产品分类图片设为 Section 背景

应用场景

很多 B2B / 电商站的产品分类归档页，希望顶部 Hero 区直接铺上当前分类的缩略图作为背景，分类名叠在上面，视觉冲击力强、也不需要每建一个分类就手动改一次模板。

WooCommerce 的产品分类本质上是一种 taxonomy，分类图保存在 term meta 的 thumbnail_id 里。Bricks 没有现成的“分类图片”动态标签，但通过自定义函数 + {echo:...} 动态数据，两步就能接上。

Step 1：给产品分类设置图片

先在 WP 后台 产品 → 分类 里，为每个要展示的分类设置好图片（缩略图）。这一步是数据源，不做后面全是空背景。

Step 2：注册取图函数

在子主题的 functions.php（不需要开头 <?php 标签）或代码片段插件中添加：

function bl_get_wc_category_image_url(): string {
    // Check if WooCommerce is active
    if ( ! function_exists( 'is_woocommerce' ) ) {
        return false;
    }

    // Get the category thumbnail ID
    $thumbnail_id = get_term_meta( get_queried_object_id(), 'thumbnail_id', true );

    // If there's no thumbnail ID, return false
    if ( ! $thumbnail_id ) {
        return false;
    }

    // Get the image URL
    $image_url = wp_get_attachment_url( $thumbnail_id );

    // Return the image URL
    return $image_url;
}

逻辑拆解：

• function_exists( 'is_woocommerce' )：确认 WooCommerce 已激活，避免裸奔报错；
• get_queried_object_id()：拿到当前归档页的对象 ID——在产品分类归档模板里就是当前分类的 term ID；
• get_term_meta( ..., 'thumbnail_id', true )：读出分类缩略图的附件 ID；
• wp_get_attachment_url()：把附件 ID 转成可直接用于 CSS 背景的 URL。

Step 3：白名单化

Bricks 只允许执行白名单内的函数，把新函数加进去：

add_filter( 'bricks/code/echo_function_names', function() {
  return [
    'bl_get_wc_category_image_url'
  ];
} );

提示：建议把你站点里所有要用到的自定义函数都收集到这个数组里统一管理，Bricks → 设置 → 自定义代码 里的 Code review 按钮可以帮你核对。

Step 4：模板中应用为背景

1. 为产品分类归档创建一个 Bricks 模板（模板类型选 WooCommerce 相关的归档类型），用 Bricks 编辑；
2. 添加一个 Section，里面放一个 h1 Heading 显示分类名：{term_name}；
3. 选中 Section → 样式 → 背景，在背景图片的 URL 处粘贴动态数据标签：

{echo:bl_get_wc_category_image_url}

保存后打开任意产品分类页，背景就会自动变成该分类的缩略图。如果觉得图片太刺眼，还可以在背景上加一层渐变叠加色（Gradient overlay）压暗，让白色文字更清晰。

小结

整个方案的骨架是：term meta 存图片 → 自定义函数取 URL → 白名单放行 → {echo:...} 填背景。这套“自定义函数 + echo 动态数据”的组合是 Bricks 处理 WooCommerce 专属数据的万能钥匙——分类图、SKU、库存、促销日期都能用同样的方式接进 Bricks 界面，强烈建议掌握。