本文详解如何在 woocommerce 商品变体选择后，自动切换 swiper 轮播图显示对应变体的主图与画廊图，涵盖 php 图片数据注入、js 动态更新逻辑及 swiper 实例重初始化技巧。
本文详解如何在 woocommerce 商品变体选择后，自动切换 swiper 轮播图显示对应变体的主图与画廊图，涵盖 php 图片数据注入、js 动态更新逻辑及 swiper 实例重初始化技巧。
在 WooCommerce 单产品页中，当用户选择不同变体（如颜色、尺寸）时，默认仅更新价格和库存状态，而主图与画廊图仍保持原始产品的图片。若需实现“选中变体 → 切换对应图片”的交互体验，需结合 PHP 数据准备、前端 JS 监听与 Swiper 动态刷新三步完成。
✅ 正确初始化 Swiper 实例（关键修正）
首先，原 JS 代码中选择器写法存在错误：
❌ 错误写法（类名前缺点号）：
var swiper = new Swiper("swiper.swiper-single-product", { ... });
✅ 正确写法（必须使用 CSS 类选择器语法）：
var swiper = new Swiper(".swiper-single-product", {
slidesPerView: 1,
grabCursor: false,
preloadImages: false,
lazyLoading: true,
pagination: {
el: ".swiper-pagination",
clickable: true
}
});
但仅修正选择器不足以实现变体图片切换——Swiper 初始化后不会自动响应 DOM 变更，必须配合 WooCommerce 的 found_variation 事件进行动态更新。
✅ 完整解决方案：监听变体、更新图片、重置 Swiper
1. 在 product-image.php 中为图片容器添加可识别的数据属性（推荐）
修改你的 PHP 模板，确保每个图片项携带可被 JS 读取的标识（如 data-variation-id），并预留一个默认占位结构：
<?php global $product;
// 获取默认产品图片（基础图）
$attachment_ids = $product->get_gallery_image_ids();
$image_urls = [];
$image_id = $product->get_image_id();
if ( $image_id ) {
$image_urls[] = wp_get_attachment_image_url( $image_id, 'full' );
}
foreach ( $attachment_ids as $id ) {
$image_urls[] = wp_get_attachment_url( $id );
}
// 输出初始轮播结构（带 data-fallback 标识）
?>
<div class="swiper swiper-single-product" data-swiper-initialized="false">
<div class="swiper-wrapper">
<?php foreach ( $image_urls as $i => $url ) : ?>
<div class="swiper-slide" data-slide-index="<?php echo esc_attr($i); ?>">
<figure class="zoom"><img src="<?php%20echo%20esc_url(%24url);%20?>" alt="<?php echo esc_attr(get_the_title()); ?>"></figure>
</div>
<?php endforeach; ?>
</div>
<div class="swiper-pagination"></div>
</div>
2. 前端 JS：监听变体变更并动态刷新 Swiper
将以下脚本加入主题的 single-product.js 或通过 wp_add_inline_script() 注入：
jQuery(document).ready(function($) {
let swiperInstance = null;
// 初始化 Swiper（仅一次）
function initSwiper() {
if (swiperInstance) return;
swiperInstance = new Swiper(".swiper-single-product", {
slidesPerView: 1,
grabCursor: false,
preloadImages: false,
lazyLoading: true,
pagination: {
el: ".swiper-pagination",
clickable: true
}
});
}
// 清空并重建轮播内容
function updateSwiperSlides(imageUrls) {
const $swiper = $(".swiper-single-product");
const $wrapper = $swiper.find(".swiper-wrapper");
// 清空旧 slide
$wrapper.empty();
// 插入新图片
imageUrls.forEach((url, index) => {
$wrapper.append(`
<div class="swiper-slide" data-slide-index="${index}">
<figure class="zoom"><img src="%24%7BescUrl(url)%7D" alt=""></figure>
</div>
`);
});
// 重初始化 Swiper（销毁再新建）
if (swiperInstance) {
swiperInstance.destroy(true, true);
swiperInstance = null;
}
initSwiper();
}
// 辅助函数：安全转义 URL
function escUrl(url) {
return url ? url.replace(/"/g, '"').replace(/'/g, ''') : '';
}
// 监听 WooCommerce 变体选择事件
$(document).on('found_variation', function(event, variation) {
if (variation.image && variation.image.src) {
// 使用变体专属图片（主图 + 画廊图）
const urls = [variation.image.src];
if (variation.gallery_image && variation.gallery_image.src) {
urls.push(variation.gallery_image.src);
}
if (variation.gallery_images && Array.isArray(variation.gallery_images)) {
variation.gallery_images.forEach(img => {
if (img.src) urls.push(img.src);
});
}
updateSwiperSlides(urls);
}
});
// 页面加载时初始化
initSwiper();
});
⚠️ 注意事项：
- 确保 variation.image.src 字段已启用：在 WooCommerce → 设置 → 产品 → 显示 中勾选「启用变体图片」；
- 若变体未设置图片，variation.image 将为 undefined，需降级回退至原始产品图；
- Swiper v6+ 推荐使用 swiperInstance?.destroy()，旧版需手动判空；
- 避免重复初始化：通过 data-swiper-initialized 或闭包变量控制。
✅ 总结
实现变体图片联动的核心在于：不依赖静态 PHP 渲染，而是由 JS 主导动态响应 found_variation 事件，并通过销毁/重建 Swiper 实例确保视图同步。修正 Swiper 初始化选择器只是基础前提，真正的交互能力来自事件监听与 DOM 重绘逻辑。建议搭配 wp_enqueue_script() 正确加载 Swiper 和自定义脚本，并启用 wp_localize_script() 传递 i18n 或配置参数以提升健壮性。
