WooCommerce购物车添加自定义HTML信息

在WooCommerce商店中，为配送方式标签添加额外信息（如预计送达时间）可以显著提升用户体验。然而，当这些额外信息需要包含自定义HTML样式时，直接修改配送标签的文本内容往往无法实现预期效果，因为WooCommerce默认会剥离标签中的HTML标签。本文将深入探讨这一问题，并提供两种有效的解决方案。

理解WooCommerce配送标签的渲染机制

WooCommerce提供了多个钩子（Hook）来修改配送方式的文本标签，例如woocommerce_package_rates和woocommerce_cart_shipping_method_full_label。这些钩子主要用于调整或追加纯文本内容。

例如，以下代码尝试在配送标签中添加带HTML样式的预计送达时间：

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添加到 $rate->label 会被剥离
            $rates[$rate_key]->label .= ' (' . $groundStuff . ')';
            break;
        }
    }
    return $rates;
}
add_filter( 'woocommerce_package_rates','add_estimated_arrival_times', 50, 2 );

尽管上述代码能成功添加纯文本，但标签及其样式会被移除，导致预计送达时间以普通文本形式显示。这是因为WooCommerce在渲染这些标签时，出于安全和显示一致性的考虑，会过滤掉其中的HTML。

要解决这个问题，我们需要采用不同的策略，将自定义HTML内容放置在配送标签的外部，或直接修改渲染标签的模板。

方法一：利用 woocommerce_after_shipping_rate 动作钩子（推荐）

对于在现有配送标签后追加自定义HTML内容的需求，woocommerce_after_shipping_rate动作钩子是首选方案。这个钩子允许你在每个配送方式选项的HTML结构之后，直接输出任意HTML内容。

代码示例

以下代码演示了如何使用woocommerce_after_shipping_rate钩子，为特定的配送方式添加带有自定义样式的预计送达时间：

/**
 * 在WooCommerce配送方式标签后添加自定义HTML信息
 *
 * @param WC_Shipping_Rate $method 当前配送方式对象。
 * @param int              $index  配送方式的索引。
 */
function custom_add_html_after_shipping_rate( $method, $index ) {
    // 示例：获取预计送达时间 (实际应用中应从API或数据库动态获取)
    $estimated_arrival_time = '约3-5个工作日'; // 假设这是从API获取的值

    // 可以根据配送方式ID进行条件判断，只对特定方式添加信息
    // 例如，如果配送方式ID是 'ups:6:09' (UPS Ground)
    if ( $method->id === 'ups:6:09' ) {
        // 使用 echo 直接输出带有自定义样式的HTML
        echo '(' . esc_html($estimated_arrival_time) . ')';
    }
    // 你也可以根据需要，为其他配送方式添加不同的信息
    // elseif ( $method->id === 'free_shipping:2' ) {
    //     echo '（免费配送）';
    // }
}
add_action( 'woocommerce_after_shipping_rate', 'custom_add_html_after_shipping_rate', 10, 2 );

代码解析

• $method 参数： 这是一个WC_Shipping_Rate对象，包含了当前配送方式的所有详细信息，例如$method->id（配送方式的唯一标识符）、$method->label（原始标签文本）等。你可以利用$method->id来精准定位并修改特定的配送方式。
• echo 输出： 在这个钩子内部，你可以直接使用echo语句输出任何HTML内容。这些内容将紧随原始配送标签之后显示。
• esc_html() 函数： 为了增强安全性，当输出从外部（如API或用户输入）获取的动态文本时，建议使用esc_html()函数对其进行转义，以防止跨站脚本（XSS）攻击。
• 样式控制： 通过内联样式（style="..."）或添加自定义CSS类（class="shipping-eta"），你可以完全控制额外信息的字体大小、颜色、粗细等样式。

注意事项

• 代码放置位置： 将上述PHP代码添加到你的WordPress子主题的functions.php文件，或通过自定义插件进行管理。
• CSS样式： 建议将复杂的CSS样式定义在你的主题style.css文件中，而不是使用内联样式，以保持代码的整洁和可维护性。
• 兼容性： woocommerce_after_shipping_rate钩子通常具有良好的兼容性，不易受WooCommerce版本更新的影响。

方法二：覆盖WooCommerce模板文件（高级定制）

如果你的需求不仅仅是在标签后追加内容，而是需要对整个配送方式的显示布局进行更深层次的修改，或者需要将自定义信息插入到标签的特定位置（而非仅仅在后方），那么覆盖WooCommerce的模板文件是更灵活但更复杂的方法。

操作步骤

1. 复制模板文件： 找到WooCommerce插件目录中的配送模板文件： wp-content/plugins/woocommerce/templates/cart/cart-shipping.php 将此文件复制到你的子主题目录中，路径为： yourtheme/woocommerce/cart/cart-shipping.php重要提示： 始终在子主题中进行模板覆盖，切勿直接修改插件文件。

2. 修改模板文件： 打开yourtheme/woocommerce/cart/cart-shipping.php文件。你需要找到负责渲染配送标签的相应代码行。根据WooCommerce的版本，这通常在循环内部，例如在@version 3.6.0左右的第40行附近。

   原始代码可能类似于：

   你可以在wc_cart_totals_shipping_method_label( $method )的输出之后，或者在标签内部的任何位置，插入你的自定义HTML：

   
       
       id === 'ups:6:09' ) {
           $estimated_arrival_time = '约3-5个工作日'; // 假设从API获取
           echo '(' . esc_html($estimated_arrival_time) . ')';
       }
       ?>
   

   请注意，在模板文件中，你同样可以访问$method对象来获取配送方式的详细信息。

注意事项

• 版本兼容性： 模板覆盖最大的风险是WooCommerce插件更新时，官方模板文件结构可能发生变化，导致你的自定义模板不再兼容，甚至引发错误。因此，在使用此方法时，每次WooCommerce更新后都需要检查你的自定义模板文件。
• 维护成本： 相比于使用钩子，模板覆盖的维护成本更高。只有在钩子无法满足需求时才考虑使用。
• 代码审查： 在模板文件中直接输出HTML时，同样需要注意安全性，对动态内容进行适当的转义。

总结与最佳实践

• 优先使用钩子： 对于在配送标签后追加少量HTML信息的需求，woocommerce_after_shipping_rate动作钩子是更推荐、更非侵入性且易于维护的方法。它避免了直接修改核心模板文件可能带来的兼容性问题。
• 模板覆盖用于深度定制： 当你需要对配送方式的整体布局进行重大调整，或者将自定义内容插入到现有标签结构中的特定复杂位置时，才考虑覆盖cart-shipping.php模板文件。
• 安全性： 无论采用哪种方法，始终确保对从外部获取的动态内容进行适当的转义（例如使用esc_html()），以防止安全漏洞。
• 测试： 在将任何代码部署到生产环境之前，务必在开发或测试环境中进行充分的测试，以确保功能正常且没有引入新的问题。

通过上述方法，你可以灵活地在WooCommerce购物车和结算页面为配送方式添加自定义HTML信息，从而提供更丰富、更具引导性的用户体验。