WooCommerce 订阅周期总额自定义短代码 | 轻松获取准确付款金额

2025-01-04 05:46:49

WooCommerce 订阅周期总额自定义短代码

当需要准确展示 WooCommerce 订阅的周期性付款总额时，使用默认订单总额可能并不总是合适的。比如，在初始订单费用可能被分摊或有促销活动时，实际的首次周期性付款额往往与订单总额存在差异。因此，创建一个自定义短代码来精确显示这些周期性总额，变得尤为重要。

问题分析

直接使用 WC_Subscription::get_total() 函数可能会导致错误，因为这个函数本身需要一个订阅对象作为上下文。仅仅调用函数而不传入适当的订阅信息会导致函数运行失败，因此简单直接的调用方式是无效的。该短代码的目标应当是：基于特定的订阅订单，准确获取并展示出周期的付款总额。我们需要访问到该订阅订单，进而才能读取到正确的总额数据。

解决方案

核心问题在于如何将当前正在查看的订阅订单与自定义的短代码关联起来，并将该订单的有效总额传递给短代码输出。可以有两种常见的解决方法：

方法一：基于当前订单ID

该方法通过全局订单对象 WC()->order 来获取当前显示的订单信息，尤其在订单详情页、付款完成页面等情境下非常实用。在短代码中，我们首先检查是否有订单对象可用，并进一步验证该订单是否是订阅类型。若是订阅，则通过订阅对象获取周期的总额。

add_shortcode('wdm_recurring_totals', 'wdm_get_recurring_totals');

function wdm_get_recurring_totals() {
    $order = wc_get_order( get_the_ID() ); // 从页面ID获取订单对象

    if( ! $order ) {
       return '无订单信息。';
    }
     
    if( ! wcs_is_subscription( $order ) ){
       return '当前不是订阅订单。';
    }


   $subscription =  wcs_get_subscription($order->get_id());
    if ($subscription) {
       $total = $subscription->get_total();
        return wc_price($total); 
    }

   return "无法获取订阅总额。";


}

操作步骤:

将上述代码添加到你主题的 functions.php 文件中（推荐使用子主题）。
在任何可以使用短代码的地方，如页面、文章、甚至是文本小工具，插入 [wdm_recurring_totals] 短代码。
访问带有订阅订单的页面，你会看到显示周期总额。

安全性建议: 建议对输出的值进行检查，确保它是一个有效数字。这里使用了 wc_price() 函数格式化价格，避免直接输出数字可能带来的格式错误。

方法二：使用 Subscription ID

有时候页面环境不一定能直接获得当前订阅订单对象。这时，可以使用另一个方法，要求用户传递一个特定的 subscription ID 作为短代码的属性，这样即使不在订单详情页也能正确获取总额。这种方法更灵活，可应用于多种情境，例如，在自定义通知邮件或者在特定的仪表盘页面中展示订阅总额。

add_shortcode('wdm_recurring_totals', 'wdm_get_recurring_totals_by_id');

function wdm_get_recurring_totals_by_id($atts) {

    $atts = shortcode_atts( array(
        'id' => '', //默认 Subscription ID为空
    ), $atts, 'wdm_recurring_totals' );

   $subscription_id = intval( $atts['id'] );

    if ( empty($subscription_id) ){
        return '订阅ID缺失。';
    }

   $subscription =  wcs_get_subscription($subscription_id);

    if (!$subscription) {
       return "无效的订阅ID。";
    }


       $total = $subscription->get_total();
       return wc_price($total); 
}

操作步骤:

将代码添加到你的 functions.php 中。
在使用短代码的地方，需要使用以下格式：[wdm_recurring_totals id="订阅ID"]，将 订阅ID 替换为实际的订阅ID。你可以在订阅订单页面上或通过 WooCommerce API 查询到它。

额外建议:
- 确保你传入的订阅ID有效，使用 intval() 将其转换为整数确保安全。
- 提供友好的错误提示，便于问题排查。

代码选择考量

选用哪一种方法取决于具体的使用场景。如果总是需要在订单详情或关联页面显示周期性总额，基于当前订单 ID 的方法较为简洁。而如果需要在不同环境或不同页面显示特定订阅的总额，那么通过传递 Subscription ID 更灵活可靠。两种方法均需加入对应的异常检查机制，防止运行时出错，确保代码的稳定性与健壮性。