本文介绍如何通过 WooCommerce 原生钩子（而非短代码）灵活控制订单商品元数据（如自定义字段、属性、下载链接等）在「感谢页」（Order Received Page）中的渲染位置，避免 wc_get_order_item_meta() 短代码失效问题，并实现图文并茂、结构清晰的商品展示。
本文介绍如何通过 woocommerce 原生钩子（而非短代码）灵活控制订单商品元数据（如自定义字段、属性、下载链接等）在「感谢页」（order received page）中的渲染位置，避免 `wc_get_order_item_meta()` 短代码失效问题，并实现图文并茂、结构清晰的商品展示。
在 WooCommerce 感谢页（即订单成功页）中，开发者常需重构订单商品的展示结构——例如将商品缩略图前置、商品名称右对齐、元数据（如尺寸、颜色、赠品标识等）嵌入商品内容区。但直接尝试封装 wc_get_order_item_meta() 为短代码（如 add_shortcode('custom_order_meta', 'wc_get_order_item_meta')）会失败，原因在于该函数不是独立可调用的输出函数：它需接收 $item_id、$order 对象及可选参数，且返回的是数组而非 HTML 字符串，无法直接用于短代码上下文。
✅ 正确做法是放弃短代码思路，转而使用 WooCommerce 提供的语义化动作钩子，精准控制元数据的插入时机与位置：
1. 使用 woocommerce_order_item_meta_start 和 woocommerce_order_item_meta_end 钩子
这两个钩子分别位于订单项元数据渲染区域的起始与结束处，允许你在默认元数据前后注入自定义 HTML 或动态内容：
// 在商品名称前插入缩略图（替代原 custom_product_on_thankyou 函数）
add_action('woocommerce_order_item_meta_start', 'add_thumbnail_before_item_meta', 10, 3);
function add_thumbnail_before_item_meta($item_id, $item, $order) {
if (!is_order_received_page()) return;
$product = $item->get_product();
if (!$product) return;
echo '<div class="thk-product-image" style="margin-bottom: 8px;">';
echo $product->get_image('thumbnail');
echo '</div>';
}
// 在元数据后追加自定义字段（示例：显示下单时填写的刻字内容）
add_action('woocommerce_order_item_meta_end', 'add_custom_engraving_meta', 10, 3);
function add_custom_engraving_meta($item_id, $item, $order) {
if (!is_order_received_page()) return;
$engraving = wc_get_order_item_meta($item_id, '_engraving_text', true);
if ($engraving) {
echo '<div class="thk-engraving-meta" style="font-size: 0.9em; color: #666; margin-top: 4px;">';
echo '<strong>刻字内容：</strong>' . esc_html($engraving);
echo '</div>';
}
}
2. 移除冗余过滤器，交由 CSS 控制布局
原方案中通过 woocommerce_order_item_name 过滤器整体重写商品 HTML，虽可行但耦合度高、难以维护。改用上述钩子后，WooCommerce 默认仍会正常渲染商品名与元数据，你只需用 CSS 调整视觉流：
/* 将商品名与元数据右对齐，形成紧凑卡片式布局 */
.woocommerce-thankyou .woocommerce-table--order-details .product-name,
.woocommerce-thankyou .woocommerce-table--order-details .woocommerce-item-meta {
text-align: right;
}
.woocommerce-thankyou .woocommerce-table--order-details .woocommerce-item-meta {
margin-top: 0.5em;
font-size: 0.9em;
}
/* 可选：为自定义缩略图添加居中或右对齐 */
.thk-product-image img {
max-width: 60px;
height: auto;
display: block;
margin: 0 auto;
}
⚠️ 注意事项
- ❌ 不要尝试将
wc_get_order_item_meta()直接注册为短代码——它缺少$item_id和$order上下文，必然报错或返回空； - ✅ 钩子函数中务必校验
is_order_received_page()，防止在邮件、后台等其他场景误触发； - ✅ 若需访问订单级元数据（如支付方式、配送备注），请使用
$order->get_meta('key')，而非wc_get_order_item_meta()（后者仅限订单项级别）； - ✅ 元数据钩子（
_start/_end）自动传入$item_id（整数）、$item（WC_Order_Item对象）、$order（WC_Order对象），可安全调用wc_get_order_item_meta($item_id, $key)。
通过合理组合 woocommerce_order_item_meta_start 与 woocommerce_order_item_meta_end，你既能保持 WooCommerce 渲染逻辑的健壮性，又能完全掌控元数据的视觉位置与内容扩展，无需 hack 过滤器或构造不可靠的短代码——这才是专业、可持续的 WooCommerce 主题定制实践。
