在 woocommerce 中，为配送方式标签添加额外信息，尤其是需要包含自定义 html 样式时，是一个常见的需求。例如，显示预计送达时间并希望其字体更小、字重更轻。直接通过修改配送费率的 label 属性来插入 html 往往无效，因为 woocommerce 在渲染这些标签时会对其进行转义处理，导致 html 标签被显示为纯文本。本文将深入探讨如何正确实现这一目标。
问题分析：为什么直接修改 label 属性无效？
当尝试在 woocommerce_package_rates 过滤器中直接向 $rates[$rate_key]->label 追加 HTML 代码时，如：
$rates[$rate_key]->label .= ' (' . $groundStuff . ')';虽然文本内容可以成功添加，但 等 HTML 标签却会丢失，只剩下纯文本。这是因为 WooCommerce 在内部渲染这些标签时，会通过 esc_html() 或类似函数对标签文本进行处理，以防止跨站脚本攻击 (XSS) 等安全问题。这意味着任何 HTML 都会被转义，无法按预期渲染。
为了实现带有自定义 HTML 的内容，我们需要利用 WooCommerce 提供的其他扩展点。
理解 WooCommerce 配送标签相关的钩子
在深入解决方案之前，我们先了解几个与配送标签相关的 WooCommerce 钩子：
立即学习“前端免费学习笔记（深入）”；
-
woocommerce_package_rates (过滤器): 此过滤器允许开发者修改配送包中的费率对象。主要用于调整费率的名称、价格、税费等属性。虽然可以修改 label 属性的文本内容，但如前所述，不适合直接插入 HTML。
function filter_woocommerce_package_rates( $rates, $package ){ foreach ( $rates as $rate_key => $rate ) { // 只能修改纯文本标签 $rates[$rate_key]->label = __( '我的自定义标签', 'woocommerce' ); } return $rates; } add_filter( 'woocommerce_package_rates','filter_woocommerce_package_rates', 10, 2 ); -
woocommerce_cart_shipping_method_full_label (过滤器): 此过滤器用于修改购物车页面上显示的完整配送方法标签。与 woocommerce_package_rates 类似，它也主要用于修改纯文本内容，不适合直接插入 HTML。
function filter_woocommerce_cart_shipping_method_full_label( $label, $method ) { // 可以覆盖或追加纯文本 if ( $method->id == 'local_pickup:1' ) { $label = __( '我的新标签', 'woocommerce' ); } elseif ( $method->id == 'free_shipping:2' ) { $label .= __( ' - 额外文本', 'woocommerce' ); } return $label; } add_filter( 'woocommerce_cart_shipping_method_full_label', 'filter_woocommerce_cart_shipping_method_full_label', 10, 2 );
了解了这些钩子的局限性后，我们需要寻找一个允许直接输出 HTML 的钩子。
解决方案一：使用 woocommerce_after_shipping_rate 动作钩子
woocommerce_after_shipping_rate 是一个动作钩子，它在每个配送费率标签渲染之后触发。这意味着我们可以在这里直接 echo 输出 HTML 内容，而无需担心被转义。这是添加自定义 HTML 内容的最推荐方法。
实现步骤：
- 获取动态数据： 假设你已经通过 API 调用或其他方式获取了预计送达时间 ($estimated_arrival_time)。
- 编写函数： 创建一个 PHP 函数，挂载到 woocommerce_after_shipping_rate 钩子上。
- 条件判断： 在函数内部，根据配送方法的 ID 来判断是否需要为特定方法添加额外信息。
示例代码：
第三版升级内容：1、增加了分类可以自定义分类名称的颜色和粗体显示 搜索引擎优化。2、增加了商品搜索引擎优化和相关文章添加3、增加了配套商品的添加4、增加了前台商品列表按照分类、属性、品牌、价格范围进行筛选5、增加了商品的配件功能6、增加了分类的批量删除7、增加了商品扩展属性在前台的显示关闭方式8、增加了商品具体显示页商品编码和打折商品图标显示形式9、增加了最近浏览商品功能10、增加了非会员直接购物
/**
* 在 WooCommerce 配送方式标签后添加带有自定义 HTML 的预计送达时间。
*
* @param object $method 配送方法对象。
* @param int $index 当前配送方法的索引。
*/
function add_estimated_arrival_times_with_html( $method, $index ) {
// 假设这是从 API 或其他逻辑获取的预计送达时间
// 在实际应用中，你需要根据 $method->id 或其他条件来获取对应配送方式的动态数据
$estimated_arrival_time = '';
// 示例：模拟从 API 获取数据
if ( $method->id === 'ups:6:09' ) { // 假设 UPS Ground 的 ID 是 'ups:6:09'
// 这里可以放置你的 API 调用逻辑，例如：
// $cart_info = WC()->cart->get_cart_contents();
// $api_response = call_ups_api($cart_info);
// $estimated_arrival_time = parse_arrival_time_from_api_response($api_response);
$estimated_arrival_time = '预计 3-5 个工作日'; // 模拟数据
} elseif ( $method->id === 'free_shipping:2' ) {
$estimated_arrival_time = '次日达';
}
// 如果获取到预计送达时间，则输出带有自定义样式的 HTML
if ( ! empty( $estimated_arrival_time ) ) {
echo '(' . esc_html( $estimated_arrival_time ) . ')';
}
}
add_action( 'woocommerce_after_shipping_rate', 'add_estimated_arrival_times_with_html', 10, 2 );代码解析：
- add_action( 'woocommerce_after_shipping_rate', 'add_estimated_arrival_times_with_html', 10, 2 );：将我们的函数挂载到 woocommerce_after_shipping_rate 钩子上。优先级为 10，接受 2 个参数。
- $method 参数：这是一个包含当前配送方法详细信息的对象，例如 id ($method->id)、label ($method->label) 等。你可以通过 id 来精确地定位到需要修改的配送方式。
- $index 参数：当前配送方法在列表中的索引。
- echo '(' . esc_html( $estimated_arrival_time ) . ')';：直接输出 HTML 内容。为了安全起见，即使是动态文本，也建议使用 esc_html() 进行转义，以防 $estimated_arrival_time 中意外包含恶意 HTML。
解决方案二：覆盖 WooCommerce 模板文件 (高级)
对于需要更精细控制布局或在标签内部插入 HTML 的情况，你可以选择覆盖 WooCommerce 的模板文件。这种方法提供了最大的灵活性，但也增加了维护成本。
实现步骤：
- 定位模板文件： 需要覆盖的文件是 plugins/woocommerce/templates/cart/cart-shipping.php。
- 复制到主题： 将此文件复制到你的主题目录下的 yourtheme/woocommerce/cart/ 路径中。
- 修改模板： 在复制的文件中找到渲染配送标签的代码行并进行修改。
示例修改点：
在 cart-shipping.php 文件中，查找类似以下的代码（在 WooCommerce 3.6.0 版本中大约在第 40 行）：
%3$s', $index, esc_attr( $method->id ), esc_html( $method->label ) ); ?>
你可以将其修改为：
label );
$estimated_arrival_time = ''; // 同样，这里需要你的逻辑来获取动态数据
// 示例：根据方法 ID 获取预计送达时间
if ( $method->id === 'ups:6:09' ) {
$estimated_arrival_time = '预计 3-5 个工作日';
} elseif ( $method->id === 'free_shipping:2' ) {
$estimated_arrival_time = '次日达';
}
if ( ! empty( $estimated_arrival_time ) ) {
$full_label .= ' (' . esc_html( $estimated_arrival_time ) . ')';
}
printf( '', $index, esc_attr( $method->id ), $full_label );
?>注意事项：
- 版本兼容性： 模板文件可能会在 WooCommerce 更新时发生变化。覆盖模板意味着你需要自行跟踪这些变化，并在每次 WooCommerce 更新后检查你的自定义模板是否仍然兼容。
- 维护成本： 模板覆盖会增加主题的维护复杂性。
- 优先使用钩子： 除非绝对必要，否则优先使用动作钩子和过滤器，因为它们通常更易于维护且对未来更新的兼容性更好。
最佳实践与注意事项
-
选择合适的方案：
- 如果只需要在标签 后 添加额外信息并允许 HTML，woocommerce_after_shipping_rate 是最佳选择。
- 如果需要在标签 内部 插入 HTML 或对整个渲染逻辑有极高的自定义需求，才考虑模板文件覆盖。
- 性能考虑： 如果在钩子函数中进行外部 API 调用（如获取 UPS 预计时间），请确保这些调用是高效的，或者考虑缓存机制，以避免在购物车或结算页面加载时造成性能瓶颈。
-
国际化 (I18n)： 对于任何用户可见的文本，务必使用 __() 或 _e() 函数进行国际化，以便网站可以轻松翻译。
echo '(' . esc_html( sprintf( __( '预计 %s', 'your-text-domain' ), $estimated_arrival_time ) ) . ')'; -
CSS 样式： 建议将样式定义放在主题的 CSS 文件中，而不是直接内联在 HTML 中，以保持代码整洁和易于维护。
.shipping-eta { font-size: 12px; font-weight: normal; margin-left: 5px; }然后在 PHP 代码中只需输出 ...。
总结
为 WooCommerce 配送方式标签添加带有自定义 HTML 的额外信息，不能通过直接修改 label 属性实现。最推荐且最安全的方法是利用 woocommerce_after_shipping_rate 动作钩子，在该钩子中直接输出所需的 HTML 内容。对于需要更深层次控制的情况，可以考虑覆盖 cart-shipping.php 模板文件，但这需要权衡其带来的维护成本。通过合理选择方法并遵循最佳实践，可以有效地增强 WooCommerce 商店的用户体验。
