本文详解为何直接 unset($total_rows['refund']) 无效，并提供正确移除所有退款行（包括多笔退款）的过滤器实现方案，附完整代码与关键注意事项。
本文详解为何直接 unset($total_rows['refund']) 无效，并提供正确移除所有退款行（包括多笔退款）的过滤器实现方案，附完整代码与关键注意事项。
在 WooCommerce 订单详情页（如「我的账户 → 订单详情」），订单总计区域默认会显示每笔退款为独立行，其键名格式为 refund_{refund_id}（例如 refund_123、refund_456），而非简单的 refund。这是由 WooCommerce 核心类 WC_Order::add_order_item_totals_refund_rows() 动态生成的——它遍历订单所有退款对象，并为每一笔创建唯一键名。因此，仅使用 unset($total_rows['refund']) 完全无法匹配实际存在的键，自然不会生效。
要可靠移除所有退款行，必须基于订单实际退款数据动态构建待删除的键名。以下是经过生产环境验证的解决方案：
/**
* 从订单总计行中移除所有退款行（支持多笔退款）
*
* @param array $total_rows 当前总计行数组，键为行标识符（如 'subtotal', 'refund_123'）
* @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 ) {
$key_to_remove = 'refund_' . absint( $refund_id );
if ( isset( $total_rows[ $key_to_remove ] ) ) {
unset( $total_rows[ $key_to_remove ] );
}
}
}
return $total_rows;
}
add_filter( 'woocommerce_get_order_item_totals', 'filter_woocommerce_get_order_item_totals', 10, 3 );✅ 关键说明与最佳实践：
- 务必使用 absint() 处理 $refund_id：确保键名安全，防止潜在类型异常；
- 添加 isset() 检查再 unset：避免因键不存在触发 PHP notice，提升代码健壮性；
- 钩子优先级保持 10 即可：该过滤器在 WooCommerce 默认逻辑之后执行，无需调整；
- 不影响后台管理订单页：此过滤器仅作用于前端客户视图（如 order-details.php 模板），后台订单编辑页使用不同逻辑，无需额外处理；
- 兼容性保障：适用于 WooCommerce 6.0+（含最新版本），底层退款行生成机制稳定。
⚠️ 注意事项：
若你同时使用了第三方插件（如退款增强工具、会计同步插件），它们可能自行向 woocommerce_get_order_item_totals 添加自定义退款行。此时需检查其键名规则，必要时在 unset 前增加日志调试：
error_log( 'Total rows keys: ' . print_r( array_keys( $total_rows ), true ) );
以确认是否新增了非标准键（如 custom_refund），并针对性移除。
通过以上方法，即可干净、可靠地从客户可见的订单详情表中隐藏全部退款记录，满足合规性或UI精简需求。
