WooCommerce 运输标签添加 HTML 信息教程

在 WooCommerce 商店中，有时我们需要为运输方式标签添加额外的信息，例如预计送达时间，并且希望这些信息能够以不同的字体大小或颜色显示，即包含自定义 HTML。然而，直接在修改运输方式标签文本的过滤器中添加 HTML 往往会失效。本文将深入探讨这一问题的原因，并提供两种有效的解决方案。

理解 WooCommerce 运输标签的渲染机制

当我们在 WooCommerce 中尝试通过 woocommerce_package_rates 过滤器修改运输方式的标签时，例如：

function add_estimated_arrival_times($rates, $package){
    $groundStuff = '预计 3-5 个工作日'; // 假设这是从 API 获取的预计时间
    $ground_rate_id = 'ups:6:09'; // 示例 UPS 地面运输方式 ID

    foreach ( $rates as $rate_key => $rate ) {
        if( $ground_rate_id === $rate_key ) {
            // 问题所在：直接添加的 HTML 会被移除或转义
            $rates[$rate_key]->label .= ' (' . $groundStuff . ')';
            break;
        }
    }
    return $rates;
}
add_filter( 'woocommerce_package_rates','add_estimated_arrival_times', 50, 2 );

上述代码虽然能够将纯文本添加到标签中，但 标签及其样式会被剥离。这是因为 woocommerce_package_rates 过滤器主要用于修改运输方式的文本标签，其输出通常会经过 WooCommerce 内部的净化或转义处理，以确保前端渲染的安全性与一致性，防止恶意代码注入或布局混乱。

类似的，woocommerce_cart_shipping_method_full_label 过滤器也主要用于修改最终显示的标签文本，不适合直接插入 HTML。

function filter_woocommerce_cart_shipping_method_full_label( $label, $method ) {
    if ( $method->id == 'free_shipping:2' ) {
        // 同样，这里添加的 HTML 也会被处理掉
        $label .= ' (免费送达！)';
    }
    return $label;
}
add_filter( 'woocommerce_cart_shipping_method_full_label', 'filter_woocommerce_cart_shipping_method_full_label', 10, 2 );

为了在运输方式标签旁添加带有自定义 HTML 的内容，我们需要采用不同的策略。

方案一：利用 woocommerce_after_shipping_rate 动作钩子

这是最推荐且非侵入性的方法，它允许我们在每个运输方式的 HTML 结构渲染完毕后，立即插入自定义内容。由于这是一个动作钩子，我们可以直接 echo HTML，而不会被 WooCommerce 净化。

核心思想

woocommerce_after_shipping_rate 动作钩子在每个运输方式的单选按钮和标签渲染完成后触发。这意味着我们可以在这里输出任何有效的 HTML 内容，它将紧随原始标签之后显示。

代码示例

以下代码演示了如何利用此钩子为特定运输方式添加带自定义样式的预计送达时间：

/**
 * 在 WooCommerce 运输方式标签后添加带 HTML 的预计送达时间。
 *
 * @param object $method 运输方式对象。
 * @param int    $index  运输方式的索引。
 */
function custom_add_estimated_arrival_times_html( $method, $index ) {
    // 示例：从 API 或其他逻辑获取预计送达时间
    // 在实际应用中，您需要根据 $method->id 或其他购物车信息来动态获取
    $estimated_time = '';
    $ground_rate_id = 'ups:6:09'; // 示例：UPS 地面运输方式 ID

    // 根据运输方式 ID 判断并获取对应的预计时间
    if ( $method->id === $ground_rate_id ) {
        // 假设这里是获取到 UPS 地面运输的预计时间
        $estimated_time = '预计 3-5 个工作日';
    } elseif ( strpos( $method->id, 'free_shipping' ) !== false ) {
        // 针对免费送货的示例
        $estimated_time = '预计 5-7 个工作日';
    }
    // 您可以根据需要添加更多条件来匹配不同的运输方式

    if ( ! empty( $estimated_time ) ) {
        // 输出带自定义样式的 HTML 内容
        // 注意：对于动态文本内容，建议使用 esc_html() 进行安全转义
        echo '(' . esc_html( $estimated_time ) . ')';
    }
}
add_action( 'woocommerce_after_shipping_rate', 'custom_add_estimated_arrival_times_html', 10, 2 );

优点

• 非侵入性： 不会修改 WooCommerce 核心模板文件，更新 WooCommerce 时不易出现兼容性问题。
• 灵活性高： 可以输出任何有效的 HTML 结构和样式。
• 易于维护： 所有逻辑集中在一个函数中，便于管理。
• 精确控制： 通过 $method 参数，可以针对特定的运输方式添加内容。

注意事项

• 安全转义： 如果您输出的文本内容是动态的或来自用户输入，请务必使用 esc_html() 或 wp_kses_post() 等函数进行安全转义，以防止跨站脚本 (XSS) 攻击。
• 样式冲突： 确保您添加的内联样式或自定义 CSS 不会与主题或 WooCommerce 默认样式产生冲突。

方案二：覆盖 WooCommerce 模板文件

当您需要对运输方式的整体布局或结构进行更深层次的修改，而不仅仅是添加额外内容时，覆盖 WooCommerce 模板文件是更合适的选择。

适用场景

• 需要将额外信息放置在标签内部的不同位置。
• 需要更改运输方式的整体 HTML 结构（例如，将单选按钮和标签包裹在自定义 div 中）。
• 需要引入更复杂的交互元素。

操作步骤

1. 复制模板文件： 找到 WooCommerce 插件目录下的 plugins/woocommerce/templates/cart/cart-shipping.php 文件。 将其复制到您的主题目录下的 yourtheme/woocommerce/cart/cart-shipping.php。如果 woocommerce 文件夹不存在，请创建它。

2. 修改模板文件： 打开您复制到主题目录下的 cart-shipping.php 文件。 查找渲染运输方式标签的相关代码。根据 WooCommerce 版本，这通常在 foreach 循环内部，可能在显示单选按钮和标签的行附近（例如，在 WooCommerce 3.6.0 版本中，大约在第 40 行左右）。

   原始代码可能类似于：

   
       label ); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped ?>
   

   您可以在此处直接修改 $method->label 的输出，或者在其前后插入自定义 HTML。例如：

   
       label ); // 原始标签
       // 假设这里根据 $method->id 获取到预计时间
       $estimated_time = '';
       if ( $method->id === 'ups:6:09' ) {
           $estimated_time = '预计 3-5 个工作日';
       }
       if ( ! empty( $estimated_time ) ) {
           echo '(' . esc_html( $estimated_time ) . ')';
       }
       ?>
   

优点

• 最高灵活性： 您可以完全控制运输方式在购物车和结算页面的渲染方式。
• 深度定制： 适合需要进行复杂布局调整或集成其他组件的场景。

缺点与注意事项

• 维护成本高： WooCommerce 插件更新时，其模板文件也可能发生变化。您需要定期检查您的覆盖模板是否与新版本兼容，并进行必要的更新，否则可能导致显示错误或功能异常。
• 学习曲线： 需要对 WooCommerce 的模板结构和 PHP 有一定的了解。
• 不推荐小改动： 对于仅仅添加一些额外信息，不建议使用此方法，因为它会增加项目的维护负担。

总结与选择建议

为 WooCommerce 运输方式标签添加带 HTML 的额外信息时，选择正确的方法至关重要：

• 对于简单的内容追加，例如添加预计送达时间、促销信息等，并且希望这些内容紧跟在原始标签之后显示，强烈推荐使用 woocommerce_after_shipping_rate 动作钩子。 这种方法非侵入性、易于实现和维护，且不易受 WooCommerce 更新的影响。
• 如果您的需求是彻底改变运输方式的布局、将额外信息嵌入到标签内部的特定位置，或者需要添加更复杂的交互元素，那么覆盖 cart-shipping.php 模板文件是必要的。 但请务必注意其维护成本，并确保在每次 WooCommerce 更新后进行兼容性检查。

无论选择哪种方法，始终遵循 WordPress 和 WooCommerce 的最佳实践，确保代码安全、高效且易于维护。