本文详解如何通过全局变量桥接机制，在 woocommerce_order_item_meta_start 钩子中准确识别并仅在指定邮件（如 customer_completed_order）中显示自定义商品元字段，解决 $email 对象不可用的核心问题。
本文详解如何通过全局变量桥接机制，在 `woocommerce_order_item_meta_start` 钩子中准确识别并仅在指定邮件（如 `customer_completed_order`）中显示自定义商品元字段，解决 `$email` 对象不可用的核心问题。
在 WooCommerce 开发中，woocommerce_order_item_meta_start 是一个常用于向邮件订单项区域注入自定义内容的钩子。但该钩子本身不接收 $email 参数，因此无法直接判断当前渲染的是哪一类邮件（如待支付提醒、发货通知或已完成订单）。若强行引用未定义的 $email->id（如 if ( $email->id == 'customer_completed_order' )），会导致 PHP Notice 错误并使函数失效。
要实现「仅在付款完成后的客户邮件中显示条款信息」这一需求，需采用跨钩子状态传递策略：利用 WooCommerce 邮件生命周期中更早触发、且明确提供 $email 对象的钩子（如 woocommerce_email_before_order_table），将邮件 ID 存入全局作用域；再在目标钩子中读取该值进行条件判断。
以下是完整、健壮的实现方案：
✅ 步骤一：在邮件渲染初期捕获并存储邮件 ID
// 在邮件表格渲染前获取并保存 email ID 到全局变量
add_action( 'woocommerce_email_before_order_table', 'set_current_email_id', 10, 4 );
function set_current_email_id( $order, $sent_to_admin, $plain_text, $email ) {
$GLOBALS['wc_current_email_id'] = $email->id;
}
该钩子在所有标准 WooCommerce 邮件模板中均被调用，且参数完整，是安全可靠的“入口点”。
✅ 步骤二：在目标钩子中读取并条件渲染
add_action( 'woocommerce_order_item_meta_start', 'display_product_terms_in_specific_emails', 10, 4 );
function display_product_terms_in_specific_emails( $item_id, $item, $order, $plain_text ) {
// 仅限邮件环境（排除前端页面、后台订单页等）
if ( is_wc_endpoint_url() || ! $item->is_type( 'line_item' ) ) {
return;
}
// 安全读取全局 email ID
$email_id = $GLOBALS['wc_current_email_id'] ?? '';
// 精确匹配目标邮件类型（支持多值，便于后续扩展）
$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 );
// 渲染 HTML 内容（注意转义与国际化）
if ( ! empty( $ot_address ) ) {
printf(
'<div class="order-item-terms">%s</div>',
wp_kses_post( __( 'Terms: ', 'your-textdomain' ) . $ot_address )
);
}
}
⚠️ 关键注意事项
- 全局变量命名规范：使用带前缀的键名（如 'wc_current_email_id'）避免与其他插件冲突；
- 空值防御：始终检查 $GLOBALS 中键是否存在，避免 Undefined index 警告；
- 钩子参数数量：woocommerce_order_item_meta_start 在较新版本 WooCommerce（≥6.0）中已升级为 4 参数（含 $plain_text），务必声明 4 作为 add_action 的第四个参数，否则 $plain_text 将不可用；
- 字段来源选择：get_post_meta( $product_id, ... ) 适用于产品级静态条款；若需订单项级动态值（如用户下单时填写的特殊条款），应改用 $item->get_meta('ot_address')；
- 样式兼容性：添加 class="order-item-terms" 便于后续 CSS 定制，同时使用 wp_kses_post() 过滤输出，保障安全性。
通过此方案，您即可精准控制自定义内容仅在 customer_completed_order 等指定邮件中呈现，逻辑清晰、兼容性强，是 WooCommerce 邮件定制开发中的最佳实践模式。
