如何通过ACF字段URL为WooCommerce产品图库添加视频

原代码的核心问题 #

1. 视频缩略图位置错误：你把视频缩略图放在了主图展示区域内，而非底部的缩略图列表中，导致它无法和其他图片缩略图并列显示。
2. 缺少交互逻辑：WooCommerce图库的图片切换依赖内置JS控制，你仅添加了缩略图，但未处理点击后替换主图为视频的逻辑，所以点击后无反应。
3. 未兼容图库动态行为：新增的视频元素没有被纳入WooCommerce图库的初始化流程，无法和原生图库功能联动。

修正后的完整方案 #

步骤1：调整PHP模板代码（子主题覆盖product-image.php） #

将视频缩略图的输出移到缩略图列表区域，使用WooCommerce统一的缩略图结构，保证样式和交互兼容：

<div class="<?php echo esc_attr( implode( ' ', array_map( 'sanitize_html_class', $wrapper_classes ) ) ); ?>" data-columns="<?php echo esc_attr( $columns ); ?>" style="opacity: 0; transition: opacity .25s ease-in-out;">
<figure class="woocommerce-product-gallery__wrapper">
    <?php
    if ( $post_thumbnail_id ) {
        $html = wc_get_gallery_image_html( $post_thumbnail_id, true );
    } else {
        $html  = '<div class="woocommerce-product-gallery__image--placeholder">';
        $html .= sprintf( '<img src="%s" alt="%s" class="wp-post-image" />', esc_url( wc_placeholder_img_src( 'woocommerce_single' ) ), esc_html__( 'Awaiting product image', 'woocommerce' ) );
        $html .= '</div>';
    }

    echo apply_filters( 'woocommerce_single_product_image_thumbnail_html', $html, $post_thumbnail_id ); // phpcs:disable WordPress.XSS.EscapeOutput.OutputNotEscaped

    do_action( 'woocommerce_product_thumbnails' );
    ?>
</figure>
</div>

<?php
// 输出视频缩略图，加入到缩略图列表
$video_url = get_field('video_url_mp4', $product->get_id());
if ($video_url) {
    $video_thumbnail = wp_get_attachment_image_src( $post_thumbnail_id, 'woocommerce_thumbnail' );
    if ($video_thumbnail) {
        ?>
        <div class="woocommerce-product-gallery__image">
            <a href="#" class="woocommerce-product-gallery__trigger video-thumbnail" data-video-url="<?php echo esc_url($video_url); ?>">
                <?php echo wp_get_attachment_image($post_thumbnail_id, 'woocommerce_thumbnail', false, array('alt' => '视频缩略图')); ?>
                <!-- 可选：添加视频标识图标 -->
                <span class="video-badge">▶</span>
            </a>
        </div>
        <?php
    }
}
?>

步骤2：添加JS交互逻辑 #

在主题functions.php或自定义JS文件中加入以下代码，处理视频缩略图的点击切换：

jQuery(document).ready(function($) {
    // 点击视频缩略图替换主图为视频
    $('.video-thumbnail').on('click', function(e) {
        e.preventDefault();
        const videoUrl = $(this).data('video-url');
        const $galleryWrapper = $('.woocommerce-product-gallery__wrapper');
        const $mainImageContainer = $galleryWrapper.find('.wp-post-image').parent();

        // 保存原始主图HTML，用于切换回来
        if (!$mainImageContainer.data('original-content')) {
            $mainImageContainer.data('original-content', $mainImageContainer.html());
        }

        // 替换主图为视频
        $mainImageContainer.html(`
            <video controls autoplay muted class="wp-post-image">
                <source src="${videoUrl}" type="video/mp4">
                你的浏览器不支持视频播放
            </video>
        `);
        $galleryWrapper.addClass('showing-video');
    });

    // 点击图片缩略图切换回原始图片
    $('.woocommerce-product-gallery__image a').not('.video-thumbnail').on('click', function(e) {
        const $galleryWrapper = $('.woocommerce-product-gallery__wrapper');
        const $mainImageContainer = $galleryWrapper.find('.wp-post-image').parent();

        if ($galleryWrapper.hasClass('showing-video') && $mainImageContainer.data('original-content')) {
            $mainImageContainer.html($mainImageContainer.data('original-content'));
            $galleryWrapper.removeClass('showing-video');
        }
    });
});

步骤3：添加视频标识样式（可选） #

为视频缩略图添加专属标识，方便用户区分：

.video-thumbnail {
    position: relative;
}

.video-badge {
    position: absolute;
    bottom: 8px;
    right: 8px;
    width: 28px;
    height: 28px;
    border-radius: 50%;
    background: rgba(0,0,0,0.6);
    color: #fff;
    display: flex;
    align-items: center;
    justify-content: center;
    font-size: 12px;
    pointer-events: none;
}

额外提示 #

• 建议通过子主题覆盖product-image.php，避免主题更新时丢失修改。
• 如果需要自定义视频缩略图，可新增ACF图片字段（如video_thumbnail），替换代码中获取缩略图的逻辑为get_field('video_thumbnail')。
• 视频添加autoplay muted是为了符合浏览器自动播放政策，确保视频能正常触发播放。

内容的提问来源于stack exchange，提问作者junglist