动态折扣复选框需求分析
在 woocommerce 商店中，有时需要为用户提供额外的促销选项，例如通过勾选一个复选框来获得特定折扣。这个折扣需要是动态的：用户勾选时应用，取消勾选时移除，并且折扣金额应在购物车、结账页、迷你购物车、订单详情以及管理后台等所有相关位置正确显示和计算。理想情况下，此折扣也应能在管理员后台的订单详情页中进行管理。
实现这一功能需要结合 WordPress/WooCommerce 的钩子（Hooks）、JavaScript 和 AJAX 技术，以实现前端交互与后端逻辑的无缝连接。
核心实现思路
为了实现购物车页面的动态折扣复选框功能，我们将遵循以下核心策略：
- 前端复选框： 在购物车总计区域添加一个自定义复选框。
- JavaScript 交互： 监听复选框的 change 事件，当状态改变时，通过 AJAX 将其状态发送到后端。
-
后端处理：
- 注册 AJAX 处理器，接收前端发送的复选框状态。
- 将复选框状态存储在 WooCommerce 会话（Session）中，以确保状态在页面刷新和导航后得以保留。
- 使用 woocommerce_cart_calculate_fees 钩子，根据会话中存储的状态，动态地向购物车添加或移除一个负值费用（即折扣）。
- 全局显示： 由于折扣是作为购物车费用处理的，WooCommerce 会自动确保其在购物车、结账页、迷你购物车、订单和电子邮件中正确显示。
步骤一：添加折扣复选框
首先，我们需要在 WooCommerce 购物车页面添加一个复选框。我们可以利用 woocommerce_cart_totals_before_shipping 钩子，在购物车总计信息中的运费上方插入我们的复选框。
/**
* 在购物车总计区域添加折扣复选框
*/
function add_discount_checkbox_to_cart_totals() {
// 确保在购物车页面且购物车不为空
if ( is_cart() && ! WC()->cart->is_empty() ) {
// 从会话中获取复选框的当前状态
$is_discount_applied = WC()->session->get( 'apply_custom_discount', false );
?>
<tr class="discount-checkbox-row">
<th><?php esc_html_e( '应用折扣', 'your-text-domain' ); ?></th>
<td data-title="<?php esc_attr_e( '应用折扣', 'your-text-domain' ); ?>">
<label for="custom_discount_checkbox">
<input type="checkbox" id="custom_discount_checkbox" name="custom_discount_checkbox" value="1" <?php checked( $is_discount_applied, true ); ?>>
<?php esc_html_e( '勾选以获得固定折扣', 'your-text-domain' ); ?>
</label>
</td>
</tr>
<?php
}
}
add_action( 'woocommerce_cart_totals_before_shipping', 'add_discount_checkbox_to_cart_totals' );代码解释：
- is_cart() 和 ! WC()-youjiankuohaophpcncart->is_empty() 确保复选框只在购物车页面且购物车有商品时显示。
- WC()->session->get( 'apply_custom_discount', false ) 用于获取复选框的当前状态，以便在页面加载时正确显示其勾选状态。
- checked() 函数根据变量值自动添加 checked 属性。
- 我们将复选框包裹在 <tr><td> 结构中，使其与购物车总计的其他行对齐，保持页面布局的一致性。
步骤二：前端 JavaScript 交互
接下来，我们需要编写 JavaScript 代码来监听复选框的状态变化，并使用 AJAX 将其发送到后端。同时，在 AJAX 成功后，需要刷新购物车片段，以便用户立即看到总价的变化。
/**
* 前端 JavaScript 监听复选框变化并发送 AJAX 请求
*/
jQuery(function($) {
var $checkbox = $('#custom_discount_checkbox');
if ($checkbox.length) {
$checkbox.on('change', function() {
var isChecked = $(this).is(':checked');
// 显示加载指示器 (可选)
$('.woocommerce-cart-form, .cart_totals').block({
message: null,
overlayCSS: {
background: '#fff',
opacity: 0.6
}
});
$.ajax({
type: 'POST',
url: wc_cart_params.ajax_url, // WooCommerce 提供的 AJAX URL
data: {
action: 'update_custom_discount_status', // 后端 AJAX 动作
security: wc_cart_params.update_shipping_method_nonce, // 使用 WooCommerce 提供的 nonce
apply_discount: isChecked ? 1 : 0
},
success: function(response) {
if (response.success) {
// 成功后刷新购物车片段
$(document.body).trigger('update_checkout'); // 刷新结账页 (如果用户在结账页)
$(document.body).trigger('wc_fragment_refresh'); // 刷新迷你购物车
$(document.body).trigger('wc_update_cart'); // 刷新购物车总计
} else {
console.error('更新折扣状态失败:', response.data);
alert('更新折扣状态失败，请重试。');
}
},
error: function(xhr, status, error) {
console.error('AJAX 请求错误:', error);
alert('网络错误，请重试。');
},
complete: function() {
// 隐藏加载指示器
$('.woocommerce-cart-form, .cart_totals').unblock();
}
});
});
}
});代码解释：
- 使用 jQuery(function($){...}) 确保 DOM 加载完成后执行。
- 监听 #custom_discount_checkbox 的 change 事件。
- wc_cart_params.ajax_url 是 WooCommerce 提供的前端 AJAX 端点。
- action: 'update_custom_discount_status' 是我们将在后端注册的 AJAX 动作。
- security: wc_cart_params.update_shipping_method_nonce 使用 WooCommerce 提供的 nonce 进行安全验证，防止 CSRF 攻击。
- 成功回调中，$(document.body).trigger('wc_update_cart') 和 $(document.body).trigger('wc_fragment_refresh') 是 WooCommerce 用于刷新购物车和迷你购物车片段的事件。update_checkout 用于刷新结账页。
- .block() 和 .unblock() 是 WooCommerce 使用的 jQuery BlockUI 插件功能，用于在 AJAX 请求期间显示加载动画，提升用户体验。
步骤三：后端处理 AJAX 请求与折扣逻辑
现在，我们需要在 PHP 后端注册 AJAX 处理器，接收前端发送的复选框状态，并据此在 WooCommerce 会话中存储状态，最后通过 woocommerce_cart_calculate_fees 钩子动态应用或移除折扣。
/**
* 后端 AJAX 处理器：更新折扣复选框状态
*/
function handle_custom_discount_ajax() {
// 验证 nonce
if ( ! isset( $_POST['security'] ) || ! wp_verify_nonce( $_POST['security'], 'woocommerce-cart' ) ) {
wp_send_json_error( 'Nonce 验证失败！' );
}
$apply_discount = isset( $_POST['apply_discount'] ) ? (bool) intval( $_POST['apply_discount'] ) : false;
// 将状态存储到 WooCommerce Session
WC()->session->set( 'apply_custom_discount', $apply_discount );
// 重新计算购物车总计
WC()->cart->calculate_totals();
wp_send_json_success( array( 'message' => '折扣状态已更新。' ) );
}
add_action( 'wp_ajax_update_custom_discount_status', 'handle_custom_discount_ajax' );
add_action( 'wp_ajax_nopriv_update_custom_discount_status', 'handle_custom_discount_ajax' ); // 允许未登录用户使用
/**
* 根据复选框状态动态添加或移除购物车折扣费用
*/
function apply_custom_discount_fee( $cart ) {
if ( is_admin() && ! defined( 'DOING_AJAX' ) ) {
return; // 避免在管理后台非 AJAX 请求时执行
}
// 获取折扣金额 (固定值)
$discount_amount = 10; // 例如：固定折扣 10 元/美元
// 从会话中获取复选框状态
$apply_discount = WC()->session->get( 'apply_custom_discount', false );
if ( $apply_discount ) {
// 如果折扣已勾选，添加负值费用 (即折扣)
// 参数: name, amount, taxable, tax_class
$cart->add_fee( esc_html__( '自定义折扣', 'your-text-domain' ), -$discount_amount, false );
} else {
// 如果未勾选，确保移除任何之前可能存在的折扣 (虽然 add_fee 是动态的，但明确处理更好)
// 实际上，如果条件不满足，add_fee 就不会被调用，也就不会添加费用。
// 但如果需要更复杂的逻辑，这里可以进行清理。
}
}
add_action( 'woocommerce_cart_calculate_fees', 'apply_custom_discount_fee', 10, 1 );
/**
* 初始化 WooCommerce Session，如果尚未初始化
* 这对于某些环境可能不是必需的，但可以作为一种健壮性措施
*/
function init_woocommerce_session_for_discount() {
if ( ! WC()->session->has_session() ) {
WC()->session->set_customer_session_cookie( true );
}
}
add_action( 'init', 'init_woocommerce_session_for_discount' );代码解释：
-
handle_custom_discount_ajax 函数：
- wp_verify_nonce() 验证安全性，防止恶意请求。
- WC()->session->set( 'apply_custom_discount', $apply_discount ) 将复选框状态存储在用户的 WooCommerce 会话中。这是实现折扣持久化的关键。
- WC()->cart->calculate_totals() 强制 WooCommerce 重新计算购物车总价，以反映折扣的变化。
- wp_send_json_success() 或 wp_send_json_error() 返回 JSON 响应给前端。
- add_action( 'wp_ajax_...', ... ) 和 add_action( 'wp_ajax_nopriv_...', ... ) 注册 AJAX 动作，分别用于已登录和未登录用户。
-
apply_custom_discount_fee 函数：
- 这是核心的折扣应用逻辑，通过 woocommerce_cart_calculate_fees 钩子在购物车总价计算前执行。
- $discount_amount 定义了固定的折扣金额。你可以将其改为从 WordPress 选项中获取，以便在后台管理。
- WC()->session->get( 'apply_custom_discount', false ) 获取会话中存储的复选框状态。
- $cart->add_fee( '自定义折扣', -$discount_amount, false ) 是关键。通过添加一个负值费用，我们实际上是在应用一个折扣。false 表示此费用不可征税。
- init_woocommerce_session_for_discount 函数： 确保 WooCommerce 会话已启动。在大多数现代 WooCommerce 设置中，会话会自动启动，但这是一个额外的安全措施。
步骤四：确保折扣在各处显示
由于我们通过 add_fee 方法将折扣添加为购物车费用，WooCommerce 会自动处理其在以下位置的显示：
- 购物车页面： 折扣会作为一行显示在总计下方。
- 结账页面： 同样会作为费用显示在订单总计中。
- 迷你购物车： 迷你购物车会刷新并显示新的总价。
- 订单详情（用户和管理员）： 折扣会作为订单项或费用项显示在订单详情中。
- 订单电子邮件： 订单电子邮件也会包含这个折扣信息。
管理员后台管理： 当折扣作为费用添加到订单时，管理员可以在 WooCommerce 订单编辑页面看到并编辑（或移除）这个费用。这满足了在管理后台管理折扣的需求。
注意事项与优化
-
折扣金额的可配置性： 当前折扣金额是硬编码的 ($discount_amount = 10;)。为了更好的可管理性，建议将其存储在 WordPress 选项中，以便管理员可以在后台轻松修改。
// 示例：从选项中获取折扣金额 $discount_amount = floatval( get_option( 'custom_discount_amount', 10 ) ); // 你还需要在后台添加一个设置页面来管理这个选项
- 安全性： 始终使用 Nonce 验证 AJAX 请求，防止 CSRF 攻击。本教程已包含此项。
- 用户体验： 在 AJAX 请求期间显示加载动画（如本教程中的 block()/unblock()）可以提升用户体验。
-
折扣类型： 本教程实现了固定金额折扣。如果需要百分比折扣，则需要根据购物车小计 ($cart->get_subtotal()) 计算折扣金额。
// 示例：百分比折扣 $percentage_discount = 0.05; // 5% $discount_amount = $cart->get_subtotal() * $percentage_discount; $cart->add_fee( esc_html__( '自定义折扣 (5%)', 'your-text-domain' ), -$discount_amount, false );
- 文本域： 在 esc_html_e() 和 esc_html__() 中使用 your-text-domain 替换为你的主题或插件的实际文本域，以便翻译。
- 代码位置： 将上述 PHP 代码放置在你的主题的 functions.php 文件中，或者最好是创建一个自定义插件来管理这些功能。JavaScript 代码可以放在一个独立的 .js 文件中，并通过 wp_enqueue_script 正确加载。
- 兼容性： 确保你的代码与当前使用的 WooCommerce 版本兼容。
总结
通过上述步骤，我们成功地在 WooCommerce 购物车页面实现了一个功能完善的动态折扣复选框。该方案利用了 WooCommerce 的会话管理、AJAX 机制和费用钩子，确保了折扣的动态应用、持久化以及在整个购物流程和后台管理中的正确显示。遵循这些最佳实践，可以为你的 WooCommerce 商店添加灵活且用户友好的促销功能。
