本文详解如何通过 WordPress 钩子精准过滤 WooCommerce 订单详情表（order-details.php）中动态生成的多笔退款行，解决直接 unset($total_rows['refund']) 无效的问题，并提供可直接部署的健壮代码方案。
本文详解如何通过 wordpress 钩子精准过滤 woocommerce 订单详情表（order-details.php）中动态生成的多笔退款行，解决直接 `unset($total_rows['refund'])` 无效的问题，并提供可直接部署的健壮代码方案。
在 WooCommerce 默认订单详情模板（order-details.php）中，订单总计行（如“总计”、“运费”、“税额”及“退款”）由 $order->get_order_item_totals() 方法生成并渲染。许多开发者尝试通过 woocommerce_get_order_item_totals 过滤器简单移除 'refund' 键来隐藏退款信息，但该方法始终失效——根本原因在于：WooCommerce 并未使用固定键 'refund'，而是为每笔退款动态生成唯一键名，格式为 'refund_{refund_id}'（例如 refund_123、refund_456）。
这一行为源于 WooCommerce 核心类 WC_Order 中的 add_order_item_totals_refund_rows() 方法（位于 /includes/class-wc-order.php）。该方法遍历订单所有退款对象（$order->get_refunds()），为每一笔退款构造独立的总计项，并以 refund_{id} 作为数组键写入 $total_rows。因此，硬编码 unset($total_rows['refund']) 完全匹配不到真实键名，自然无法生效。
✅ 正确解法是：在过滤器中主动获取订单全部退款记录，再逐个 unset 对应的动态键。以下是经过生产环境验证的完整实现：
/**
* 从订单总计行中移除所有退款行（支持多笔退款）
*
* @param array $total_rows 当前总计行数组（key => ['label', 'value']）
* @param WC_Order $order 当前订单对象
* @param string $tax_display 税额显示模式（'excl' 或 'incl'）
* @return array 修正后的总计行数组
*/
function filter_woocommerce_get_order_item_totals( $total_rows, $order, $tax_display ) {
// 获取订单关联的所有退款对象（WC_Order_Refund 实例数组）
$refunds = $order->get_refunds();
// 仅当存在退款时执行移除逻辑
if ( ! empty( $refunds ) ) {
foreach ( $refunds as $refund_id => $refund ) {
$dynamic_key = 'refund_' . $refund_id;
if ( isset( $total_rows[ $dynamic_key ] ) ) {
unset( $total_rows[ $dynamic_key ] );
}
}
}
return $total_rows;
}
add_filter( 'woocommerce_get_order_item_totals', 'filter_woocommerce_get_order_item_totals', 10, 3 );? 关键注意事项：
- ✅ 必须使用 3 个参数：该过滤器签名严格为 ( $total_rows, $order, $tax_display )，缺一不可，否则钩子不会触发；
- ✅ 键名校验更安全：添加 isset() 判断可避免因 WooCommerce 版本差异或异常数据导致的 PHP Notice；
- ⚠️ 不影响后台与邮件：此过滤器仅作用于前端订单详情页（order-details.php 渲染阶段），不修改数据库、不干扰管理后台订单总览或客户邮件中的退款展示；
- ? 如需同时隐藏后台订单页：需额外挂载 woocommerce_admin_order_item_totals 钩子，逻辑类似；
- ? 扩展建议：若需保留部分退款（如仅隐藏无理由退款），可在 foreach 内增加 $refund->get_reason() 条件判断。
该方案兼容 WooCommerce 6.0+ 主流版本，逻辑清晰、无副作用，是移除订单详情页退款行的推荐实践。部署后刷新订单页面即可立即生效——退款行将彻底消失，而其他总计项（含税费、运费等）保持原样，确保用户体验与财务数据完整性不受影响。
