本文介绍如何在 woocommerce 商品目录页（shop loop）中，为每个商品自动显示其所属首个产品分类（product_cat）的自定义缩略图徽章，兼容响应式尺寸与占位图回退机制。
在 WooCommerce 中，默认的商品循环（woocommerce_before_shop_loop_item_title 钩子）不包含分类缩略图展示功能。若需在商品标题上方统一显示其所属首个产品分类的自定义徽章（如品牌图标、品类标识等），应避免遍历全部分类或依赖硬编码 slug（如 'sunglasses'），而应采用健壮、可扩展的方式实现。
以下是一段经过优化的专业级代码，推荐添加至当前子主题的 functions.php 文件中：
/**
* 在商品列表页顶部显示首个产品分类的缩略图徽章
* 支持 WooCommerce 原生图片尺寸、srcset 响应式适配及占位图回退
*/
add_action('woocommerce_before_shop_loop_item_title', 'display_product_category_thumbnail', 20);
function display_product_category_thumbnail()
{
global $product;
// 获取当前商品的所有 product_cat 分类，并取第一个（按层级顺序，通常为最具体分类）
$terms = get_the_terms($product->get_id(), 'product_cat');
if (empty($terms) || is_wp_error($terms)) {
return;
}
$first_category = reset($terms); // 等价于 array_shift()，但不修改原数组
// 获取分类缩略图 ID（WooCommerce 4.4+ 推荐使用 term meta 的 thumbnail_id 字段）
$thumbnail_id = get_term_meta($first_category->term_id, 'thumbnail_id', true);
// 定义图片尺寸（复用 WooCommerce 标准缩略图配置）
$size = 'woocommerce_thumbnail'; // 对应 300×300 或自定义尺寸（见 WooCommerce → 设置 → 产品 → 显示）
$dimensions = wc_get_image_size($size);
// 构建图像 URL 及响应式属性
if ($thumbnail_id && wp_get_attachment_image_src($thumbnail_id, $size)) {
$image_data = wp_get_attachment_image_src($thumbnail_id, $size);
$image = is_array($image_data) ? $image_data[0] : '';
$srcset = function_exists('wp_get_attachment_image_srcset')
? wp_get_attachment_image_srcset($thumbnail_id, $size)
: false;
$sizes = function_exists('wp_get_attachment_image_sizes')
? wp_get_attachment_image_sizes($thumbnail_id, $size)
: false;
} else {
// 回退至 WooCommerce 占位图
$image = wc_placeholder_img_src();
$srcset = $sizes = false;
}
// 渲染徽章容器与图像（建议使用 CSS 控制宽高，而非内联 style）
if ($image) {
echo '<div class="category-badge-wrapper" aria-hidden="true">';
echo '<img src="' . esc_url($image) . '"'
. ($srcset ? ' srcset="' . esc_attr($srcset) . '"' : '')
. ($sizes ? ' sizes="' . esc_attr($sizes) . '"' : '')
. ' alt="' . esc_attr(sprintf(__('Category: %s'), $first_category->name)) . '"'
. ' class="category-badge-img">';
echo '</div>';
}
}✅ 关键改进说明：
- ✅ 语义化 & 安全性： 使用 esc_url() 和 esc_attr() 防止 XSS；aria-hidden="true" 表明该图仅为装饰用途，不向屏幕阅读器暴露冗余信息。
- ✅ 响应式支持： 自动集成 srcset 和 sizes 属性，适配 Retina 屏与不同视口宽度。
- ✅ 兼容性： 兼容 WooCommerce 3.0+（get_term_meta 替代已废弃的 get_woocommerce_term_meta）；支持自定义图片尺寸配置。
- ✅ 鲁棒性： 增加空值与错误判断（is_wp_error、empty），避免 PHP 警告；使用 $product->get_id() 替代全局 $post->ID，更符合 WooCommerce 最佳实践。
- ✅ 样式建议： 请通过 CSS 控制 .category-badge-wrapper 和 .category-badge-img 的尺寸与布局（例如 max-width: 60px; height: auto;），避免使用内联 width="35%" 等不可维护写法。
⚠️ 注意事项：
- 确保已在「产品 → 分类」中为各分类上传了「图像」（即设置“分类图像”，后台自动存为 thumbnail_id meta）。
- 若需显示多个分类徽章（非仅首个），需重构逻辑并注意 DOM 性能与 UI 冗余问题，建议结合 CSS Grid/Flex 控制多徽章排列。
- 此钩子作用于所有商品卡片（包括搜索、分类归档等），如需限定页面，请包裹 is_shop()、is_product_category() 等条件判断。
通过以上实现，您将获得一个轻量、稳定、符合现代 Web 标准的分类徽章系统，显著提升商品列表页的信息传达效率与视觉专业度。
