WoodMart 的 AJAX 产品筛选器与属性设置

一、创建产品属性

筛选器的核心逻辑是「按属性过滤产品」。没有属性，筛选器就是空壳。所以这一篇从创建属性开始，先把数据基础打好，再接筛选器。

产品属性（Attributes）和产品分类（Categories）是两套不同的组织维度。分类是「这件商品属于哪个类目」，属性是「这件商品有什么特征」。一件 T 恤可以同时属于「男装」分类，并且拥有「黑色」「L 码」「Nike」三个属性。筛选器筛的是属性，不是分类。

🌐 1.1 什么是全局属性

WooCommerce 中有两种属性：

• 全局属性（Global Attributes）：在后台 产品 → 属性（Products → Attributes）中创建，所有产品共用同一套属性值。筛选器只能使用全局属性。
• 自定义属性（Custom Attributes）：在编辑单个产品时手动添加，仅作用于当前产品，不能用于筛选器。

⚠️ 这一点很重要：如果你在产品编辑页面的「属性」选项卡里直接手打了一个属性名和值，它只是自定义属性，筛选器读不到。必须先在 产品 → 属性 中创建全局属性，然后在产品编辑页面从下拉列表中选择它，筛选器才能识别。

🎨 1.2 创建全局属性：颜色（Color）

1. 进入 WordPress 后台，点击 产品 → 属性（Products → Attributes）。

2. 在页面顶部的表单中填写：
– 名称（Name）：Color
– 别名（Slug）：color（自动生成，也可手动填写，用英文小写加连字符）
– 启用属性（Enable attribute）：勾选
3. 点击 添加属性（Add attribute）。
4. 创建完成后，页面左侧的属性列表中会出现 Color。鼠标移上去会显示几个操作链接，点击 配置属性项（Configure terms）。
5. 在配置页面中，逐个添加颜色的属性值（Terms）：
– 名称填 Black，别名 black，点击 添加新属性项。
– 继续添加 White、Red、Blue、Green 等，每次添加后点击 添加新属性项。
6. 添加完毕后，Color 属性下就有了完整的颜色值列表。

💡 属性值的名称建议用英文填写，方便后续做多语言翻译（如配合 WPML 插件）。如果你的站点只面向单一语言市场，也可以直接用中文，如「黑色」「白色」。

📏 1.3 创建全局属性：尺寸（Size）

按照同样的流程创建尺寸属性：

1. 回到 产品 → 属性 页面。
2. 名称填 Size，别名 size，勾选启用，点击 添加属性。
3. 点击 Size 的 配置属性项。
4. 逐个添加尺寸值：S、M、L、XL、XXL（或根据你的产品线调整，如 38、39、40、41 等鞋码）。

🏷️ 1.4 创建全局属性：品牌（Brand）

1. 同样在 产品 → 属性 页面创建：名称 Brand，别名 brand，勾选启用，添加。
2. 配置属性项，添加品牌名称：Nike、Adidas、Puma 等。

📌 如果你的品牌列表较长，也可以考虑使用 WoodMart 内置的品牌功能（主题设置 → Shop → Brands），它提供了更完善的品牌页面和品牌 Logo 展示能力。但对于筛选器来说，用全局属性 Brand 完全够用。

🔗 1.5 为产品分配属性值

属性创建好了，但还没有跟具体产品关联。筛选器只显示「当前页面中有产品使用」的属性值——如果所有产品都没设置颜色，颜色筛选器就是空的。

为简单产品（Simple Product）分配属性：

1. 进入 产品 → 所有产品，点击某个产品进入编辑页面。
2. 向下滚动到 属性（Attributes）选项卡，点击展开。
3. 在 自定义属性（Custom Product Attributes）下拉框中，选择之前创建的全局属性（如 Color）。
4. 点击 添加（Add）。
5. 在出现的 值（Values）字段中，从下拉列表选择已配置的属性值（如 Black、White）。可以多选。
6. 点击 保存属性（Save attributes）。
7. 重复以上步骤，继续添加 Size、Brand 等属性。

为变体产品（Variable Product）分配属性：

1. 产品编辑页面，在 属性 选项卡中添加全局属性（如 Color 和 Size）。
2. 勾选 用于变体（Used for variations）。
3. 保存属性后，切换到 变体（Variations）选项卡。
4. 从下拉菜单选择 创建所有组合变体（Create variations from all attributes），点击 前往（Go）。
5. WooCommerce 会自动生成所有属性值的组合（如 黑色+S、黑色+M、白色+S 等），每个组合可以单独设置价格、库存和图片。

⚠️ 筛选器能筛到什么，取决于产品设置了什么属性。建议先给 5–10 个测试产品都设置好 Color、Size、Brand 三个属性，然后在商店页刷新查看筛选器效果。确认无误后再批量处理全站产品。

🌈 1.6 配置属性色板（Swatches）

默认情况下，属性在产品详情页以下拉框（Dropdown）形式展示。WoodMart 支持将属性下拉框转换为色板（Swatches），用颜色圆点、图片缩略图或文本标签替代单调的下拉菜单。这个功能对服装、配饰、家居类产品尤其有用——用户看到色块比看到”Black”这个单词更直观。

色板可以配置为三种形式：颜色（Color）、图片（Image）、文本（Text）。

⚠️ 色板功能仅适用于全局属性。在产品编辑页面手动创建的自定义属性无法配置色板。

配置颜色色板：

1. 进入 产品 → 属性，找到 Color 属性，点击 配置属性项（Configure terms）。

2. 点击某个颜色值（如 Black）的 编辑（Edit）链接。
3. 在编辑页面中，找到 色板（Swatch）设置区域：
– 启用色板（Enable swatch）：勾选，开启色板功能。
– 色板类型（Swatch style）：选择 Color。
– 颜色预览（Color preview for this value）：点击颜色选择器，选择对应的颜色（如黑色 #000000）。
4. 点击 更新（Update）保存。
5. 对每个颜色值重复以上操作，分别设置对应的颜色值。

配置图片色板（适用于品牌 Logo、材质纹样等）：

1. 在属性值编辑页面，色板类型选择 Image。
2. 点击 上传图片（Upload image），上传或从媒体库选择一张图片（如品牌 Logo）。
3. 确保 使用产品变体图片（Use images from product variations）选项为关闭状态——这个选项开启后，色板图片会自动从变体产品的特色图片中提取，而不是使用你手动上传的图片。
4. 更新保存。

配置文本色板（适用于尺寸等没有颜色和图片的属性）：

1. 在属性值编辑页面，色板类型选择 Text。
2. 不需要额外设置，属性值名称会直接作为文本标签显示（如 S、M、L）。
3. 更新保存。

在产品列表页（Product Grid）显示色板：

色板配置好后，默认只在产品详情页生效。如果想在商店页的产品卡片上也显示颜色色板，需要额外设置：

1. 进入 WoodMart → 主题设置 → Shop → Attribute swatches。
2. 找到 Grid swatch attribute to display（产品卡片上显示的色板属性），从下拉列表选择 Color。
3. 如果你想让色板图片自动使用变体产品的特色图片，开启 Use images from product variations。开启后，每个颜色色块会显示该颜色变体的产品主图，而不需要你手动在属性值中上传图片。
4. 保存设置。

💡 开启 Use images from product variations 后，用户在产品卡片上点击不同颜色色块，产品主图会自动切换为对应颜色的变体图片。这是服装类独立站非常常见的交互效果，能显著提升点击率。

---

二、添加 WoodMart 筛选小工具

属性准备好了，接下来把筛选器放到商店页的侧边栏。WoodMart 自带了几个专用的筛选小工具，不需要额外安装插件。

📐 2.1 确认侧边栏位置已开启

在添加小工具之前，先确认商店页的侧边栏没有被关闭：

1. 进入 WoodMart → 主题设置 → Product archive → Sidebar。
2. 确认 Sidebar position 设置为 Left 或 Right，而不是 Without sidebar。
3. 保存设置。

⚠️ 如果选择了 Without sidebar，即使你往 Shop page widget area 添加了小工具，前台也不会显示。这是最高频的「筛选器不显示」原因之一。

🧩 2.2 添加属性筛选小工具

属性筛选（Layered Nav）是筛选器的核心组件，让用户按颜色、尺寸、品牌等属性过滤产品。

1. 进入 外观 → 小工具（Appearance → Widgets）。
2. 在右侧区域列表中找到 Shop page widget area（商店页侧边栏）。
3. 在左侧小工具列表中找到 WOODMART WooCommerce Layered Nav，点击或拖入该区域。
4. 展开小工具设置：
5. Title（标题）：填写筛选标题，如 Color 或 颜色。
6. Filter by（筛选属性）：从下拉列表选择要筛选的产品属性。列表中显示的是你在 产品 → 属性 中已创建的全局属性，如 Color、Size、Brand。
7. Display type（显示样式）：选择筛选选项的展示形式——
   • List（列表）：文字列表，每项前面有复选框。
   • Dropdown（下拉）：折叠为一个下拉菜单，节省空间。
   • Colors（颜色色块）：用颜色圆点展示，适合颜色属性。
   • Images（图片标签）：用图片缩略图展示，适合品牌或图案类属性。
8. 点击 更新（Update）保存。
9. 如果需要按多个属性筛选，重复添加多个 WOODMART WooCommerce Layered Nav 小工具，每个选择不同的属性（一个筛颜色、一个筛尺寸、一个筛品牌）。

💡 颜色属性推荐使用 Colors 显示模式，WoodMart 会用色块替代文字，视觉效果更直观。品牌属性推荐使用 Images 显示模式，用品牌 Logo 作为筛选标签。尺寸属性推荐使用 List 或 Dropdown。

💰 2.3 添加价格筛选小工具

1. 在 Shop page widget area 中添加 WOODMART Price Filter 小工具。
2. 展开设置：
3. Title：填写标题，如 Price 或 价格区间，也可留空不显示标题。
4. 更新保存。

💡 WOODMART Price Filter 会自动读取当前商店页产品的最低和最高价格，生成一个滑动条。用户拖动滑块后，产品列表会实时更新（需开启 AJAX shop，见第三节）。

🔀 2.4 添加排序小工具

1. 在 Shop page widget area 中添加 WOODMART WooCommerce Sort by 小工具。
2. 展开设置：
3. Title：填写标题，如 Sort by 或 排序，也可留空。
4. 更新保存。

排序小工具会生成一个下拉菜单，支持按以下方式排序：Popularity（人气）、Average rating（平均评分）、Latest（最新上架）、Price: low to high（价格从低到高）、Price: high to low（价格从高到低）。

📦 2.5 添加库存状态筛选小工具

1. 在 Shop page widget area 中添加 WOODMART Stock status 小工具。
2. 展开设置：
3. Title：填写标题，如 Availability 或 库存状态。
4. 更新保存。

库存状态筛选器提供 In stock（有货）和 Out of stock（缺货）两个选项，让用户快速过滤掉缺货产品。对于经常有商品断货的跨境独立站，这个筛选器能减少用户点进缺货产品后的流失。

📂 2.6 设置筛选器在特定分类中显示

WoodMart 的 WOODMART WooCommerce Layered Nav 小工具支持按产品分类控制显示范围——比如颜色筛选器只在「服装」分类页显示，在「电子产品」分类页不显示。

1. 展开 WOODMART WooCommerce Layered Nav 小工具设置。
2. 找到 Show in categories（在指定分类中显示）设置项。
3. 勾选你希望该筛选器出现的分类（如 Clothing、Shoes）。
4. 也可以使用 Hide in categories（在指定分类中隐藏）来反向设置——在大部分分类显示，只在个别分类中隐藏。
5. 更新保存。

💡 这个功能非常适合多品类独立站。比如你同时卖服装和电子产品，服装需要「颜色」「尺寸」筛选，电子产品需要「存储容量」「屏幕尺寸」筛选。用分类控制显示范围，用户在不同分类页看到的都是最相关的筛选项，不会看到一堆空的筛选条件。

🔢 2.7 调整小工具排列顺序

在 Gutenberg 小工具编辑界面中，直接拖动小工具块可以调整上下顺序。建议的排列顺序从上到下：

1. WOODMART WooCommerce Sort by（排序）
2. WOODMART Price Filter（价格筛选）
3. WOODMART WooCommerce Layered Nav — Color（颜色筛选）
4. WOODMART WooCommerce Layered Nav — Size（尺寸筛选）
5. WOODMART WooCommerce Layered Nav — Brand（品牌筛选）
6. WOODMART Stock status（库存状态）

排序放最上面是因为用户进入商店页后，第一反应往往是「先按最新或价格排一下」，然后再用筛选条件缩小范围。

📌 除了侧边栏的 Shop page widget area，WoodMart 还提供了 Shop filters 区域，位于面包屑导航和产品网格之间，筛选条件横向排列。如果你更偏好顶部横向筛选布局，可以把小工具放到 Shop filters 区域。两种位置可以同时使用，但通常选一种即可，避免筛选项重复。

---

三、开启 AJAX 筛选与加购

前面添加的筛选器在默认状态下是「点击筛选 → 页面刷新 → 显示结果」的传统模式。开启 AJAX 后，筛选、排序、翻页都不需要刷新页面，产品列表会在原地实时更新。这种体验更流畅，也更接近主流电商网站的标准交互。

🛒 3.1 开启 WooCommerce 原生 AJAX 加购

WooCommerce 自带一个基础的 AJAX 加购功能，但仅作用于商店页、分类页等归档页面（Archive Pages），产品详情页不受影响。

1. 进入 WooCommerce → 设置（Settings）→ 产品（Products）选项卡。
2. 在 常规（General）部分找到 在归档页面上启用 AJAX 添加到购物车按钮（Enable AJAX add to cart buttons on archives）。
3. 勾选开启。
4. 点击 保存更改（Save changes）。

这是 WooCommerce 原生功能，是 AJAX 加购的基础层。建议先开启它，再配置 WoodMart 的增强功能。

⚡ 3.2 开启 WoodMart AJAX shop

AJAX shop 是 WoodMart 的核心 AJAX 功能。开启后，用户在商店页进行筛选、排序、翻页等操作时，页面不会整体刷新，只有产品列表区域会通过 AJAX 请求更新数据。

1. 进入 WoodMart → 主题设置 → Product archive → Product grid。
2. 找到 AJAX shop 选项，切换为 On（开启）。
3. 保存设置。

💡 AJAX shop 开启后，用户点击颜色筛选、拖动价格滑块、切换排序方式、点击翻页按钮——所有这些操作都会在不刷新页面的情况下实时更新产品列表。交互体验会从「点击→白屏→加载→显示」变成「点击→原地更新」，体感速度快很多。

⚠️ AJAX shop 开启后，页面不再触发完整的页面加载。这意味着依赖页面浏览量（Pageview）统计的分析工具（如 Google Analytics）可能会低估商店页的浏览数据，因为用户翻页和筛选不再产生新的页面加载事件。如果你使用 GA4，需要配置增强型测量（Enhanced Measurement）或自定义事件来追踪 AJAX 页面变化。这不是 bug，是 AJAX 技术的固有特性。

➕ 3.3 开启 WoodMart AJAX add to cart

WooCommerce 原生的 AJAX 加购只覆盖归档页面。WoodMart 将 AJAX 加购扩展到了产品详情页和变体产品：

产品详情页 AJAX 加购：

1. 进入 WoodMart → 主题设置 → Single product → Add to cart。
2. 找到 AJAX Add to cart（AJAX 加购），开启。
3. 保存设置。

开启后，用户在产品详情页点击「加入购物车」按钮时，页面不会刷新，购物车数量和总价会实时更新。

商店页 AJAX 加购（WoodMart 增强）：

1. 进入 WoodMart → 主题设置 → Product archive → Product grid（与 AJAX shop 同一区域）。
2. 找到 AJAX add to cart 选项，切换为 On（开启）。
3. 保存设置。

这个选项控制的是商店页和分类页产品卡片上的「加入购物车」按钮。开启后，用户在浏览产品列表时直接点击加购，页面不会跳转也不会刷新，购物车侧边栏会自动弹出显示已添加的商品。

🗄️ 3.4 AJAX shop 与缓存插件的注意事项

AJAX 依赖 JavaScript 发送异步请求。如果你的站点使用了页面缓存插件（如 WP Rocket、W3 Total Cache、LiteSpeed Cache），需要注意以下问题：

• 不要缓存 AJAX 请求：主流缓存插件通常会自动排除 AJAX 请求，但如果你做了自定义缓存规则，确保 AJAX 端点（通常包含 ?wc-ajax= 或 admin-ajax.php）被排除在缓存之外。
• JS 文件不要被延迟加载（Defer/Delay JS）：部分缓存插件的「延迟执行 JavaScript」功能可能会导致 AJAX 筛选脚本加载时机错乱。如果开启 AJAX shop 后筛选器不响应，先尝试关闭缓存插件的 JS 延迟加载功能，测试是否恢复正常。
• 清空缓存测试：每次修改主题设置中的 AJAX 选项后，清空缓存插件缓存和浏览器缓存，再访问前台验证。

📌 如果你不确定缓存插件是否影响了 AJAX 功能，最简单的排查方法是：暂时关闭缓存插件 → 访问前台测试筛选 → 如果正常，说明是缓存插件配置问题 → 重新开启缓存插件并调整排除规则。

---

四、筛选器外观设置

筛选小工具添加好后，可以通过主题设置进一步控制外观和交互行为。

📁 4.1 分类折叠开关

当侧边栏中放了产品分类小工具时，分类列表可能很长，占据大量侧边栏空间。WoodMart 提供了折叠功能，让分类默认收起，用户点击时再展开。

1. 进入 WoodMart → 主题设置 → Product archive → Widgets。
2. 找到 Toggle function for categories widget（分类小工具折叠开关）。
3. 开启后，产品分类小工具中的子分类默认折叠，点击父分类可展开下级分类。
4. 保存设置。

💡 这个设置同时影响桌面端侧边栏和移动端 Off-canvas 面板中的分类小工具。如果你的分类层级较深（如 服装 → 男装 → 上衣 → T 恤），强烈建议开启此功能。

📜 4.2 筛选器滚动与高度限制

当侧边栏中放了多个筛选小工具时，总高度可能超过产品列表区域，导致页面被拉得很长。WoodMart 提供了两种控制方式：

滚动模式：

1. 在 Product archive → Widgets 中找到 Scroll for filters widgets（筛选小工具滚动）。
2. 开启后，每个筛选小工具的内容区域超出指定高度时会出现内部滚动条，而不是把整个侧边栏撑长。
3. 配合 Height for filters widgets（筛选小工具高度限制）设置最大高度值（如 200px）。超出此高度的内容会通过滚动条查看。
4. 保存设置。

💡 这个功能在移动端尤其有用。手机屏幕宽度有限，如果筛选面板太高，用户需要反复滑动才能找到「应用」按钮。设置高度限制后，每个筛选项区域独立滚动，面板整体高度可控。

📌 Height for filters widgets 的值需要根据你的筛选项数量和设计偏好调整。一般建议 200px 到 300px 之间，既能显示足够多的选项，又不会让面板过长。设为 0 或留空表示不限制高度。

---

五、移动端筛选按钮与弹出面板

移动端屏幕窄，侧边栏直接显示在产品列表旁边会导致内容被挤压。WoodMart 的解决方案是 Off-canvas sidebar（离屏侧边栏）——在移动端隐藏侧边栏，改用一个筛选按钮触发弹出面板，面板从屏幕边缘滑入，覆盖在内容上方。

📥 5.1 开启 Off-canvas sidebar

1. 进入 WoodMart → 主题设置 → Product archive → Sidebar。
2. 找到 Off canvas sidebar for mobile（移动端离屏侧边栏）。
3. 开启此选项。
4. 保存设置。

开启后，在移动端访问商店页时，侧边栏不再固定显示在产品列表旁，而是被收进一个弹出面板中。页面顶部或产品列表上方会出现一个筛选按钮（通常标注为 Filter 或带有筛选图标），用户点击后弹出面板，面板内显示所有筛选小工具。

💡 Off-canvas sidebar 开启后，桌面端侧边栏的显示不受影响。这个设置只改变移动端的行为，属于响应式设计的一部分。你可以分别控制不同设备的侧边栏显示方式。

👁️ 5.2 确认移动端筛选按钮可见

开启 Off-canvas sidebar 后，移动端商店页应该自动出现筛选按钮。如果按钮没有出现，按以下步骤排查：

1. 确认 Off canvas sidebar for mobile 已开启。
2. 确认 Shop page widget area 中至少添加了一个小工具。如果侧边栏区域为空，筛选按钮不会显示，因为没有内容可以弹出。
3. 清空缓存插件和浏览器缓存后重新访问。
4. 用手机或浏览器的开发者工具切换到移动端视图（如 Chrome DevTools 的设备模拟模式）刷新页面查看。

📌 5.3 开启 Sticky 筛选按钮

默认情况下，筛选按钮出现在产品列表上方。当用户向下滚动浏览产品时，按钮会滚出可视区域。WoodMart 提供了一个 Sticky（粘性）选项，让筛选按钮固定在屏幕底部，随时可点。

1. 进入 WoodMart → 主题设置 → Product archive → Sidebar。
2. 找到 Sticky offcanvas sidebar button for mobile（移动端粘性筛选按钮）。
3. 开启此选项。
4. 保存设置。

开启后，移动端屏幕底部会出现一个固定的筛选按钮，用户无论滚动到页面哪个位置，都能随时点击展开筛选面板。

💡 Sticky 按钮提升了筛选功能的可达性，尤其是产品数量多、页面较长的商店页。用户不需要滚回顶部才能筛选——这个细节能减少移动端的跳出率。

📱 5.4 在移动端底部导航栏添加筛选入口

除了筛选按钮，WoodMart 还提供了移动端底部导航栏（Mobile Bottom Navbar），可以放置常用功能入口（首页、搜索、筛选、购物车等），类似原生 App 的底部 Tab Bar。

1. 进入 WoodMart → 主题设置 → General → Mobile bottom navbar。
2. 开启 Enable sticky navbar（启用粘性导航栏）。
3. 在导航栏按钮配置中，添加 Off canvas sidebar（离屏侧边栏）按钮。
4. 可以同时添加其他按钮，如 Home（首页）、Search（搜索）、Cart（购物车）、Account（账户）。
5. 保存设置。

配置后，移动端屏幕底部会显示一个固定的导航栏，其中筛选按钮点击后弹出与 5.1 节中相同的 Off-canvas 筛选面板。

📌 Sticky 筛选按钮（5.3 节）和移动端底部导航栏筛选入口（5.4 节）都能实现「随时可筛选」的效果，两者选其一即可。如果同时启用，屏幕底部会出现两个筛选入口，视觉上会显得冗余。建议根据整体布局选择一种：如果没用底部导航栏，用 Sticky 按钮；如果用了底部导航栏，把筛选入口放在导航栏里。

🎛️ 5.5 移动端面板中的筛选器显示

在 Off-canvas 面板中，筛选小工具的显示方式与桌面端侧边栏一致。第四节中设置的 Toggle function（分类折叠）和 Scroll for filters（滚动筛选）同样适用于移动端面板。

💡 移动端建议开启 Toggle function for categories widget（分类折叠）。手机屏幕空间有限，分类默认折叠可以减少面板高度，用户需要时再点击展开。同时建议开启 Scroll for filters widgets 并设置合理的高度限制，让面板内容不会无限拉长。

---

六、常见问题排查

6.1 筛选没反应

用户点击筛选项后，产品列表不更新，页面也没有任何变化。

按顺序排查：

1. 确认 AJAX shop 已开启：主题设置 → Product archive → Product grid，确保 AJAX shop 为 On。如果关闭了 AJAX shop，筛选器会走传统的页面刷新模式——点击筛选后页面应该刷新。如果页面既不刷新也不更新，可能是 JavaScript 报错导致。
2. 检查浏览器控制台：按 F12 打开开发者工具，切换到 Console（控制台）标签，刷新页面后点击筛选，查看是否有红色报错信息。常见的报错包括 jQuery 未加载、JS 文件 404 等。
3. 检查缓存插件：参照第 3.4 节的方法，暂时关闭缓存插件测试。如果关闭后正常，说明是缓存插件配置问题。
4. 检查插件冲突：逐个禁用非必要插件，每禁用一个测试一次筛选功能。某些不兼容的插件可能会阻止 WooCommerce 的 AJAX 脚本正常执行。

6.2 筛选项为空

WOODMART WooCommerce Layered Nav 小工具添加后，前台只显示标题，没有筛选选项。

1. 确认 Filter by 已选择属性：展开小工具设置，检查 Filter by 下拉框是否选择了正确的属性。如果选择了「请选择」（默认空值），筛选器不会显示任何选项。
2. 确认属性下有属性值：进入 产品 → 属性 → 对应属性的「配置属性项」，检查是否添加了属性值（如 Black、White 等）。没有属性值，筛选器自然为空。
3. 确认产品已分配属性值：至少有一个产品在该属性下设置了属性值。筛选器只显示「当前页面产品中存在的属性值」。如果当前分类的产品都没有设置颜色属性，颜色筛选就不会出现。
4. 确认 Show in categories 设置：如果在小工具中设置了「在指定分类中显示」，而当前浏览的分类不在勾选列表中，筛选器不会出现。检查或清除分类限制设置。

6.3 缓存拦截 JS 导致筛选失效

站点使用了 WP Rocket、LiteSpeed Cache 等缓存插件后，AJAX 筛选不工作。

1. 排除 AJAX 端点：在缓存插件的设置中，确保以下模式不被缓存——/wc-ajax/、admin-ajax.php。大部分主流缓存插件默认排除这些端点，但自定义规则可能意外覆盖。
2. 关闭 JS 延迟加载：WP Rocket 的 Delay JavaScript execution（延迟执行 JS）和 LiteSpeed Cache 的 JS Defer 可能导致 AJAX 脚本加载时机不对。尝试暂时关闭这些优化选项，测试筛选是否恢复。
3. 关闭 Minify JS 测试：JS 合并压缩可能破坏某些脚本依赖顺序。如果关闭 Minify 后筛选正常，说明是合并压缩导致的问题，需要将相关脚本加入排除列表。
4. 清空全部缓存：修改任何缓存相关设置后，务必清空缓存插件缓存、对象缓存（如 Redis/Memcached）和浏览器缓存。

6.4 色板（Swatches）不显示

颜色属性配置了色板，但产品详情页或产品卡片上仍然显示下拉框。

1. 确认属性已启用色板：进入 产品 → 属性 → 对应属性 → 配置属性项 → 编辑每个属性值，确认「Enable swatch」已勾选，且色板类型和颜色/图片已设置。
2. 确认产品使用的是全局属性：色板仅支持全局属性。如果产品编辑页面中使用的是手动添加的自定义属性（不是从下拉列表选择的全局属性），色板不会生效。删除自定义属性，重新从下拉列表添加全局属性。
3. 确认产品卡片色板设置：如果产品详情页色板正常但产品卡片不显示，进入 主题设置 → Shop → Attribute swatches，确认 Grid swatch attribute to display 选择了正确的属性。
4. 变体产品重新保存一次：如果是变体产品，进入产品编辑页面 → 变体选项卡，保存一次变体设置，清空缓存后再检查前台色板是否渲染出来。

6.5 AJAX shop 开启后统计数据异常

开启 AJAX shop 后，Google Analytics 或其他分析工具的页面浏览量明显下降。

这不是故障，而是 AJAX 技术的特性。AJAX shop 让用户在不刷新页面的情况下翻页和筛选，因此每次翻页不再产生新的页面加载事件（Pageview）。

• 如果你使用 GA4，配置 增强型测量（Enhanced Measurement）来追踪页面变化事件。
• 如果统计数据对你的运营决策非常重要，可以在主题设置中关闭 AJAX shop，恢复传统的页面刷新模式。筛选功能仍然可用，只是体验不如 AJAX 流畅。
• 另一种方案是保持 AJAX shop 开启，但通过自定义事件追踪（如监听筛选按钮点击、翻页按钮点击）来补充数据。