本文介绍如何通过全局变量桥接机制，在 woocommerce_order_item_meta_start 钩子中准确识别并仅在指定邮件（如 customer_completed_order）中显示自定义商品元信息，避免误触其他邮件或前端页面。
本文介绍如何通过全局变量桥接机制，在 `woocommerce_order_item_meta_start` 钩子中准确识别并仅在指定邮件（如 `customer_completed_order`）中显示自定义商品元信息，避免误触其他邮件或前端页面。
在 WooCommerce 开发中，woocommerce_order_item_meta_start 是一个常用于向订单邮件中的商品行项插入自定义内容的钩子。但该钩子本身不接收 $email 对象参数，因此无法直接判断当前渲染的是哪一类邮件（如“新订单”、“付款完成”或“订单完成”）。若强行在函数内引用未定义的 $email->id（如示例中所示），将导致 PHP Notice 错误并使整个钩子失效。
要实现“仅在订单完成邮件（customer_completed_order）中显示定制条款”的目标，需采用跨钩子状态传递策略：利用 WooCommerce 邮件发送流程中更早触发、且明确传入 $email 对象的钩子（如 woocommerce_email_before_order_table），将当前邮件 ID 临时存入全局变量；再在 woocommerce_order_item_meta_start 中读取该值进行条件判断。
以下是完整、健壮的实现方案：
✅ 步骤一：在邮件渲染初期捕获并存储邮件 ID
// 在邮件正文表格渲染前，保存当前邮件类型 ID 到全局变量
add_action( 'woocommerce_email_before_order_table', 'set_current_email_id_in_global', 10, 4 );
function set_current_email_id_in_global( $order, $sent_to_admin, $plain_text, $email ) {
$GLOBALS['wc_current_email_id'] = $email->id;
}
⚠️ 注意：此钩子仅在 WooCommerce 邮件模板渲染时触发，不会影响前台页面或后台订单页，安全可靠。
✅ 步骤二：在商品元字段钩子中读取并条件渲染
add_action( 'woocommerce_order_item_meta_start', 'display_ot_address_in_specific_emails', 10, 4 );
function display_ot_address_in_specific_emails( $item_id, $item, $order, $plain_text ) {
// 仅限邮件环境（排除 My Account 页面、订单详情页等）
if ( is_wc_endpoint_url() || ! $item->is_type( 'line_item' ) ) {
return;
}
// 安全读取全局邮件 ID
$email_id = $GLOBALS['wc_current_email_id'] ?? '';
// 精确匹配目标邮件类型（支持多值，如 'new_order', 'customer_processing_order'）
$target_emails = array( 'customer_completed_order', 'customer_processing_order' );
if ( empty( $email_id ) || ! in_array( $email_id, $target_emails, true ) ) {
return;
}
// 获取商品级自定义字段（注意：此处使用 get_post_meta，因字段绑定到产品而非订单项）
$ot_address = get_post_meta( $item->get_product_id(), 'ot_address', true );
// 可选：若字段实际存储在订单项中，请改用 $item->get_meta('ot_address')
// $ot_address = $item->get_meta( 'ot_address', true );
if ( ! empty( $ot_address ) ) {
printf( '<div class="order-item-terms">%s</div>', wp_kses_post( __( 'Terms: ', 'woocommerce' ) . $ot_address ) );
}
}
? 关键要点说明：
- 钩子参数差异：woocommerce_order_item_meta_start 默认为 3 参数钩子，但 WooCommerce 6.0+ 已扩展为 4 参数（含 $plain_text），建议统一声明 4 并保留兼容性。
- 安全性增强：使用 wp_kses_post() 过滤输出，防止 XSS；in_array(..., true) 启用严格类型比较，避免字符串误匹配。
- 字段来源辨析：get_post_meta($product_id, ...) 适用于产品级设置；若字段随订单动态生成（如用户下单时填写），应改用 $item->get_meta() 并确保前端已正确保存。
- 调试建议：开发阶段可临时添加 error_log("Email ID: " . $email_id); 辅助验证邮件 ID 是否正确捕获。
通过这一模式，你不仅能精准控制 customer_completed_order 邮件，还可灵活扩展至任意邮件类型（如 customer_invoice 或自定义邮件），同时保持代码清晰、低耦合、高可维护性。
