HUSKY - WooCommerce Product Filter Professional

WooCommerce AJAX 筛选破坏产品网格布局:原因与修复

商店在第一次点击筛选器之前一切正常。之后三列变成四列,行中出现空洞,产品卡片丢失主题的徽章或按钮,或者侧边栏滑到了产品下方。当 WooCommerce AJAX 筛选器破坏了产品网格布局时,产品本身是正确的;变化的是绘制它们的 HTML。下文说明 HUSKY 的 AJAX 模式替换了什么、为什么主题专有的标记会在此过程中丢失,以及每种症状的解决办法。

AJAX 模式替换了什么,又无法复制什么

当尝试将商店 AJAX 化 (Try to ajaxify the shop)设为是 (Yes)时(WooCommerce → 设置 → Products Filter → 选项 (Options)),插件会标出商店页面和分类页面的产品区域。它在 woocommerce_before_shop_loop 钩子(优先级 2)上打开一个容器 <div class="woocommerce woocommerce-page woof_shortcode_output">,并在其中放入 <div id="woof_results_by_ajax">,然后在 woocommerce_after_shop_loop(优先级 10)上把两者关闭。

当访客更改筛选器时,脚本会向 /wp-admin/admin-ajax.php 发送一个动作为 woof_draw_products 的请求。服务器渲染 [woof_products is_ajax=1],脚本再用结果替换该容器。这个结果只由标准的 WooCommerce 组件构建:

  • woocommerce_before_shop_loop 钩子(通知、结果计数、排序下拉列表);
  • woocommerce_product_loop_start(),它输出 <ul class="products columns-N">;
  • 每个产品对应的 content-product.php 模板部件;
  • woocommerce_product_loop_end() 和 woocommerce_after_shop_loop 钩子(分页)。

由此可以得出两点。第一,您的主题归档模板在这两个钩子之间自行输出的任何内容(额外的包装元素、网格类名、页面构建器的循环外观)都不在新的 HTML 中。第二,新的 HTML 是在 admin-ajax 请求中生成的,而不是在商店页面上。那些在商店页面加载时运行的代码,无论是挂在 wp 或 template_redirect 动作上、位于归档模板内,还是仅在 is_admin() 为 false 时运行,都不会为它运行。曾在页面加载时一次性设置网格样式的主题脚本,也不会再次运行。

找出变化:比较筛选前后的标记

在隐私窗口中打开商店,右键点击第一个产品并选择检查 (Inspect)。记下 ul.products、它的父元素以及第一个 li.product 上的类名。应用一个筛选器,再检查同一位置。差异会指出解决办法:

筛选后的症状原因章节
列数不同,columns-4 而不是 columns-3主题的列数设置没有在 AJAX 请求中应用列数与间隙
3 个一行,然后 1 个,再 3 个;网格中出现空洞first/last 行类名是按另一个列数计算的列数与间隙
侧边栏或页脚移位、消失或重复;产品显示两次主题没有在循环前后调用这两个商店循环钩子商店循环钩子
ul.products 上缺少类名,按钮或徽章又出现,网格/列表视图丢失,图片空白主题标记、PHP 条件或主题脚本主题卡片功能

筛选后产品列数改变并出现空隙

[woof_products] 从 WooCommerce 的 loop_shop_columns 过滤器获取列数,该过滤器会回退到外观 → 自定义 → WooCommerce → 产品目录中的每行产品数 (Products per row)。带有自己列数选项的主题往往只在商店页面加载时应用它。在 AJAX 请求中,这段代码不会运行,所以返回的结果使用 WooCommerce 的值:商店显示 3 列的地方,往往变成 4 列。

空隙的根源相同。WooCommerce 会给每一行的第一个产品添加类名 first,给最后一个产品添加 last,它们都是按这个列数计算的,而经典的浮动网格会在每个 first 处开始新的一行。如果主题的 CSS 适配每行 3 个产品,而 AJAX 的 HTML 按 4 个计数,那么每第四个产品都会强制另起一行:3 个产品,然后单独 1 个,再是 3 个。

请对所有请求一次性设置列数,使用您的商店在桌面端显示的数量:

/**
 * Same number of columns on shop pages and in HUSKY AJAX results.
 * Child theme functions.php or a code snippets plugin.
 */
add_filter( 'loop_shop_columns', function () {
    return 3; // products per row on desktop
}, 999 );

不要用 is_shop() 或类似的检查把它包起来,否则它在 AJAX 请求中会被跳过。优先级 999 让它压过主题自己的过滤器。简短的常见问题强制筛选结果显示固定列数使用的是同一个过滤器。在自定义页面上,[woof_products columns=3] 可以直接设置数量。两种情况下,手机和平板的样式都由主题 CSS 的媒体查询决定。

如果筛选后类名显示为 columns-3,宽度却仍然不对,说明主题是通过被替换区域之外它自己的包装元素上的类名来设置产品尺寸的。请为 AJAX 容器添加 CSS,可以放在外观 → 自定义 → 额外 CSS 中,或放在插件的自定义 CSS 代码 (Custom CSS code)字段中(高级 → 代码):

/* HUSKY AJAX results: 3 products per row in a float-based grid */
#woof_results_by_ajax ul.products li.product {
    width: 30.75%;
    margin-right: 3.8%;
    clear: none;
}
#woof_results_by_ajax ul.products li.product:nth-child(3n) {
    margin-right: 0;
}
#woof_results_by_ajax ul.products li.product:nth-child(3n+1) {
    clear: both;
}

如果您的主题使用 CSS 网格而不是浮动来排列 ul.products,一条规则就足够了:#woof_results_by_ajax ul.products { grid-template-columns: repeat(3, 1fr); }。如果主题在手机上使用更少的列数,请把任一版本包在桌面端媒体查询中。

侧边栏跑到产品下方、页脚错乱、结果重复:商店循环钩子

AJAX 模式要求主题像标准 WooCommerce 模板那样,在产品列表之前直接调用 woocommerce_before_shop_loop,在产品列表之后直接调用 woocommerce_after_shop_loop。如果没有这样做:

  • 缺少结束钩子。这两个容器永远不会被关闭,浏览器只会在它们的父元素结束时才把它们关闭。侧边栏、第二列或页脚最终落到产品区域内部:往往在页面加载时侧边栏就已经位于产品下方,而第一次点击筛选器后,容器内的一切(包括带有筛选器的侧边栏)都会被结果替换。
  • 钩子在别处被调用。如果主题在工具栏中触发这些钩子,并在 woocommerce_after_shop_loop 之后才输出产品循环,那么 AJAX 结果会进入容器,而原来的网格仍留在它下方,于是产品出现两次。
  • 主题的包装元素跨越了这些容器。主题在 woocommerce_before_shop_loop 上打开、在 woocommerce_after_shop_loop 上关闭的元素,必须完全位于 HUSKY 的容器之内(在优先级 2 之后打开,在优先级 10 之前关闭),或者完全位于它们之外。任何介于两者之间的做法都会与它们重叠,破坏嵌套结构。

检查方法:打开页面源代码(Ctrl+U),搜索 woof_results_by_ajax 并顺着 HTML 往下看:在产品的 </ul> 和分页之后,侧边栏或页脚开始之前,必须有两个 </div>。在主题文件夹中,搜索归档模板里的 woocommerce_after_shop_loop。适用于 AJAX 模式的模板,其产品部分与 WooCommerce 自己的 archive-product.php 类似:

<?php
if ( woocommerce_product_loop() ) {
    do_action( 'woocommerce_before_shop_loop' );

    woocommerce_product_loop_start();
    if ( wc_get_loop_prop( 'total' ) ) {
        while ( have_posts() ) {
            the_post();
            do_action( 'woocommerce_shop_loop' );
            wc_get_template_part( 'content', 'product' );
        }
    }
    woocommerce_product_loop_end();

    do_action( 'woocommerce_after_shop_loop' );
} else {
    do_action( 'woocommerce_no_products_found' );
}

请在子主题中的模板副本里进行修改,或者请主题作者补上缺失的钩子。页面构建器的布局很少会同时调用这两个钩子;对它们来说,下文介绍的重定向模式才是现实的选择。完全不变化的产品,请参阅筛选器 URL 变化但产品没有变化,Elementor 模板请参阅 Elementor Loop Grid 和归档模板无法筛选。

主题卡片功能丢失:徽章、按钮、网格类名、脚本

您的 PHP 只在商店页面上做的修改

隐藏加入购物车按钮、添加分类行或徽章的代码,如果是在 wp 或 template_redirect 上结合 is_shop() 来决定的,就不会在 AJAX 请求中运行,所以筛选后会恢复成默认的卡片。请让它也为 HUSKY 的请求运行。admin_init 会在每个 admin-ajax 请求中触发:

/**
 * Card changes for shop pages AND for HUSKY AJAX results.
 * Child theme functions.php or a code snippets plugin.
 */
function my_shop_card_changes() {
    // Example: no add-to-cart buttons in the product grid
    remove_action( 'woocommerce_after_shop_loop_item', 'woocommerce_template_loop_add_to_cart', 10 );
}

// Normal page loads of the shop and product archives
add_action( 'wp', function () {
    if ( is_shop() || is_product_taxonomy() ) {
        my_shop_card_changes();
    }
} );

// HUSKY AJAX filtering, sent through admin-ajax.php
add_action( 'admin_init', function () {
    if ( wp_doing_ajax() && isset( $_REQUEST['action'] ) && 'woof_draw_products' === $_REQUEST['action'] ) {
        my_shop_card_changes();
    }
} );

改变卡片的主题选项(分类行、悬停图片、快速查看按钮)往往也是在主题内部以同样的方式应用的。如果它们在筛选后消失,而主题没有能同时覆盖 AJAX 请求的钩子,请使用重定向模式。

主题添加到产品列表上的类名

如果比较结果显示,ul.products 上有一个类名在页面加载时存在、筛选后却缺失,请使用 woof_draw_products_html 过滤器把它添加到 AJAX 响应中。它接收即将发送给浏览器的 HTML:

/**
 * Add the theme's grid class to the product list in HUSKY AJAX results.
 * Child theme functions.php or a code snippets plugin.
 */
add_filter( 'woof_draw_products_html', function ( $html, $shortcode_str ) {
    return str_replace(
        '<ul class="products columns-',
        '<ul class="products my-theme-grid columns-', // use the class from your page
        $html
    );
}, 10, 2 );

这个搜索字符串对应的是 WooCommerce 自己的 loop/loop-start.php;如果您的主题覆盖了该文件,请从页面源代码中复制开头的标签。当主题使用 content-product.php 以外的模板部件来渲染卡片时,请用 woof_template_part 过滤器返回它的名称:值 product-grid 会从您主题的 woocommerce 文件夹中加载 content-product-grid.php。

主题脚本:懒加载图片、等高、瀑布流、快速查看

在页面加载时只运行一次的脚本(懒加载图片、卡片等高、瀑布流、网格/列表切换器、快速查看按钮)看不到新的产品。HUSKY 在每次替换之后都会触发 jQuery 事件 woof_ajax_done;请把主题的初始化调用放在那里,可以放在主题的 JS 文件中,也可以放在AJAX 完成后的 JavaScript 代码 (JavaScript code after AJAX is done)中(高级 → 代码)。函数名称可以请主题作者提供;关于该事件的更多内容见 woof_ajax_done。

jQuery(document).on('woof_ajax_done', function () {
    // Many layout scripts recalculate on resize
    jQuery(window).trigger('resize');
    // Call your theme's own init function here if it has one
});

结果计数或排序显示了两次

如果主题在产品区域之外输出了自己的计数和排序栏,AJAX 结果内部仍然可能带上 WooCommerce 默认的副本。只有在它们确实是重复内容时,才隐藏内部的副本:

#woof_results_by_ajax .woocommerce-result-count,
#woof_results_by_ajax .woocommerce-ordering {
    display: none;
}

如果该区域之外主题自己的计数在筛选后没有更新,请把它的 CSS 选择器填入结果计数 CSS 选择器 (Result count css selector)(高级 → 选项):这样插件会在每个 AJAX 响应中发送最新的计数,并替换它找到的元素。

何时放弃 AJAX:重定向模式和涡轮模式

有些布局无法用标准的 WooCommerce 组件重建:页面构建器的循环外观、轮播、没有这些钩子的主题模板。请将尝试将商店 AJAX 化 (Try to ajaxify the shop)设为否 (No)。这样每次更改筛选器都会加载筛选后的 URL,由您的主题照常渲染整个页面,所以网格与未筛选的商店完全一致。代价是失去原位更新。若想每次搜索只重新加载一次,而不是每次点击后都加载,请将自动提交 (Autosubmit)设为否 (No),让筛选器等待它的按钮,并参阅重定向模式下自动滚动到产品,让访客直接看到结果。

如果尝试将商店 AJAX 化 (Try to ajaxify the shop)又跳回了是 (Yes),说明涡轮模式处于开启状态:它会在每次加载页面时打开 AJAX 模式。请先在其标签页中将启用涡轮模式 (Enable turbo mode)设为否 (No),再关闭 AJAX,并清除页面缓存,让访客获得新的设置。

检查清单

  • 已在浏览器检查器中比较筛选前后的标记。
  • loop_shop_columns 返回商店的列数,且不带页面条件。
  • 页面源代码显示,两个 HUSKY 容器在产品和分页之后紧接着关闭。
  • PHP 中的卡片修改同样会为 woof_draw_products 请求运行;主题脚本在 woof_ajax_done 时重新运行。
  • 如果布局仍有差异:尝试将商店 AJAX 化 (Try to ajaxify the shop) = 否 (No),同时关闭涡轮模式并清除缓存。

如果在 Storefront 之类的默认主题下,只启用 HUSKY,布局仍然被破坏,请在 HUSKY 支持论坛上发起一个主题,并附上商店页面的链接以及筛选后发生了哪些变化的说明。