如何在 WooCommerce 订阅管理页添加已支付续订订单计数列

本文介绍如何在 WooCommerce Subscriptions 后台订阅列表页（/wp-admin/edit.php?post_type=shop_subscription）中新增一列，准确显示每条订阅下已完成和待处理的续订订单总数，并关联到对应商品。

这段内容主要讲的是：如何在 WooCommerce Subscriptions 的后台订阅列表页（/wp-admin/edit.php?post_type=shop_subscription）里新增一个字段列，把每条订阅名下已完成和待处理的续订订单总数清楚展示出来，同时还能关联到对应的商品。

要在 WooCommerce 订阅管理界面中增强数据可视化能力，最实用的方式之一是在订阅列表页添加自定义列。默认情况下，该页面仅展示订阅状态、用户、开始/结束日期等基础信息，但无法直观反映续订行为的活跃度。本文将指导你通过两个核心钩子——manage_edit-shop_subscription_columns（控制列头）和 manage_shop_subscription_posts_custom_column（渲染列内容）——安全、高效地插入“续订订单计数”列，并确保数据按商品粒度准确呈现。

首先，使用 manage_edit-shop_subscription_columns 过滤器在“结束日期”列之后插入新列。我们采用 array_slice 精确定位插入位置（索引 10），避免硬编码依赖列顺序变化：

function dd_columns_head( $defaults ) {
return array_slice( $defaults, 0, 10, true ) +
array( 'count' => '续订订单数' ) +
array_slice( $defaults, 10, count( $defaults ) - 1, true );
}
add_filter( 'manage_edit-shop_subscription_columns', 'dd_columns_head', 30 );

接下来，就该在 manage_shop_subscription_posts_custom_column 这个动作里把列内容真正渲染出来了。这里有几个地方尤其不能马虎：
✅ 第一，必须先通过 wcs_get_subscription( $post_ID ) 拿到订阅对象，再用 is_a( $subscription, 'WC_Subscription' ) 做一次类型校验。原因很直接：一旦遇到空值或异常对象，后台就很容易出问题，严重时甚至直接白屏；
✅ 第二，使用 $subscription->get_payment_count() 分别统计 'completed' 和 'pending' 状态下的续订订单，也就是 renewal 类型订单，最后再相加，得到总续订次数；
✅ 第三，如果订阅里包含多个商品，比如组合订阅，就不能只粗略展示一条信息，而是要遍历 $subscription->get_items()，为每个商品各输出一行表格，这样读起来更清楚，也更贴合实际业务场景；
✅ 第四，所有输出都必须经过 esc_html_e() 或 absint() 这类安全过滤处理，把 XSS 风险和类型问题提前拦住，这才稳妥。

完整实现如下：

function dd_column_content( $column_name, $post_ID ) {
if ( 'count' !== $column_name ) {
return;
}

$subscription = wcs_get_subscription( $post_ID );
if ( ! is_a( $subscription, 'WC_Subscription' ) ) {
echo '—';
return;
}

$completed_count = $subscription->get_payment_count( 'completed', 'renewal' );
$pending_count = $subscription->get_payment_count( 'pending', 'renewal' );
$total_count = absint( $completed_count + $pending_count );

echo '

⚠️ 注意事项：

• 请勿在 woocommerce_subscription_before_actions 等前端钩子中尝试渲染管理列，该钩子作用于单个订阅详情页，与列表页列逻辑完全无关；
• get_payment_count() 的第二个参数 'renewal' 明确限定只统计续订订单（排除初始订阅订单），确保数据语义准确；
• 如需区分“仅已完成续订”，可单独输出 $completed_count；若需支持导出或排序，需额外实现 manage_edit-shop_subscription_sortable_columns 及 SQL 查询优化；
• 建议将代码放入子主题的 functions.php 或独立插件中，避免主题更新覆盖。

通过以上方案，你将获得一个稳定、可维护且符合 WooCommerce 最佳实践的管理列扩展，显著提升订阅运营的数据洞察效率。