本文详解如何通过正确钩子和逻辑，在 WooCommerce 订单详情表（order-details.php）中精准移除所有退款记录行，解决因键名动态生成（如 refund_123）导致的 unset($total_rows['refund']) 失效问题。
本文详解如何通过正确钩子和逻辑，在 woocommerce 订单详情表（order-details.php）中精准移除所有退款记录行，解决因键名动态生成（如 `refund_123`）导致的 `unset($total_rows['refund'])` 失效问题。
在 WooCommerce 中，订单详情页（如用户账户中的“订单详情”或管理员后台订单页面）会通过 woocommerce_get_order_item_totals 过滤器生成总计行表格。许多开发者尝试直接 unset($total_rows['refund']) 来隐藏退款信息，但该方法始终无效——根本原因在于：WooCommerce 并不使用静态键 'refund'，而是为每个退款记录动态生成唯一键名，格式为 'refund_{refund_id}'（例如 refund_456）。这一设计源于 WC_Order::add_order_item_totals_refund_rows() 方法的内部实现。
因此，要真正移除退款行，必须：
- 获取当前订单的所有退款对象；
- 遍历退款列表，逐个构造并删除对应的动态键；
- 确保过滤器优先级与参数数量匹配，避免被其他插件覆盖。
以下是经过生产环境验证的完整解决方案：
/**
* 从订单详情总计行中移除所有退款记录行
*
* @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_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 );✅ 关键要点说明：
- ✅ 使用 $order->get_refunds() 获取退款集合，而非假设单个 'refund' 键；
- ✅ 动态构造键名 'refund_' . $refund_id，严格匹配 WooCommerce 内部命名规范；
- ✅ 添加 isset() 检查，增强代码健壮性，避免未定义键警告；
- ✅ 钩子挂载为 10 优先级、接收 3 个参数，确保与 WooCommerce 原生调用签名完全一致。
⚠️ 注意事项：
- 此过滤器仅影响前端订单详情表格渲染（如 order-details.php 模板），不影响后台订单编辑页、邮件模板或 REST API 返回值；
- 若需同步隐藏后台订单详情中的退款行，还需额外针对 woocommerce_admin_order_data_after_order_details 等管理端钩子进行定制；
- 不建议直接修改 WooCommerce 核心模板文件（如 order-details.php），应优先使用过滤器机制以保障升级兼容性。
通过上述方法，您可稳定、安全地从订单总计区域清除所有退款条目，提升客户界面简洁性，同时保持系统可维护性与扩展性。
