https://github.com/coowinit/wordpress-product-category-filter-theme
一套用于学习 WordPress 产品目录开发的经典主题，完整演示多层级产品分类导航、GET 多条件筛选、pre_get_posts、tax_query、meta_query、产品排序与分页参数保留。
https://github.com/coowinit/wordpress-product-category-filter-theme
custom-post-type custom-taxonomy learning-project meta-query php product-category product-filter taxonomy wordpress wordpress-development wordpress-theme wp-query
Last synced: 11 days ago
JSON representation
一套用于学习 WordPress 产品目录开发的经典主题，完整演示多层级产品分类导航、GET 多条件筛选、pre_get_posts、tax_query、meta_query、产品排序与分页参数保留。
- Host: GitHub
- URL: https://github.com/coowinit/wordpress-product-category-filter-theme
- Owner: coowinit
- Created: 2026-06-15T03:06:46.000Z (11 days ago)
- Default Branch: main
- Last Pushed: 2026-06-15T06:47:35.000Z (11 days ago)
- Last Synced: 2026-06-15T07:18:28.701Z (11 days ago)
- Topics: custom-post-type, custom-taxonomy, learning-project, meta-query, php, product-category, product-filter, taxonomy, wordpress, wordpress-development, wordpress-theme, wp-query
- Language: PHP
- Homepage:
- Size: 125 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# WordPress 产品分类导航与动态筛选主题
> 一套用于学习 WordPress 产品目录系统的经典主题，完整演示多层级分类导航、动态属性、AJAX 无刷新筛选、联动计数、移动端抽屉、SEO 与结构化数据。
## 项目简介
本项目用于系统学习 WordPress 产品目录、分类导航、动态属性和多条件筛选开发。
当前版本：
```text
v1.6.0｜筛选交互与移动端体验优化版
```
v1.6.0 保留 v1.5.0 的动态属性、AJAX、联动计数、缓存、SEO 和结构化数据，重点解决筛选组较多、选项较多以及移动端页面过长的问题。
---
# v1.6.0 核心更新
## 移动端筛选抽屉
小屏幕下不再直接铺开整个筛选器，而是显示：
```text
筛选产品（已选 3 项）
```
点击后打开右侧抽屉。抽屉支持：
- 遮罩关闭；
- 关闭按钮；
- `Esc` 键关闭；
- 焦点限制在抽屉内部；
- 关闭后焦点返回原按钮；
- 打开时锁定页面滚动；
- 底部固定“清空条件”和“查看结果”操作栏；
- AJAX 更新后同步结果数量。
## 筛选组折叠
每个筛选组都使用可访问的按钮控制：
```html
```
默认规则：
- 有已选条件的组自动展开；
- 品牌、电压等主要分组默认展开；
- 其他分组可以折叠；
- AJAX 更新不会重置展开状态。
## “显示更多”与收起
taxonomy 筛选组默认仅显示部分选项。超过首屏数量时显示：
```text
显示更多 2 项
```
展开后可以再次收起。首屏数量由：
```php
pfl_get_filter_ui_config()
```
统一管理。
## 已选项置顶
每次筛选状态或联动数量变化后，组内选项按以下顺序展示：
1. 已选择项；
2. 可用且匹配数量较多的项；
3. 其他可用项；
4. 数量为 0 的禁用项。
这里只改变前端显示顺序，不修改 WordPress term 的后台顺序。
## 组内搜索
品牌、应用行业、材质等选项达到阈值后自动出现搜索框。
组内搜索：
- 只过滤当前页面中的选项；
- 不发送 AJAX；
- 不修改 URL；
- 不改变真正的产品筛选条件；
- 支持一键清空搜索；
- 无匹配时显示空状态。
## 桌面端吸顶摘要
桌面端新增简洁吸顶条：
```text
已筛选 3 项，共 12 个产品｜修改筛选｜清空
```
用户滚动到产品列表后仍可快速返回筛选器或清空条件。
## 骨架加载
AJAX 更新时显示产品卡片骨架屏，并保留结果区域高度，减少页面跳动。
分页请求期间：
- 产品区进入 `aria-busy`；
- 分页和产品链接暂时不可重复点击；
- 联动数量进入计算状态；
- 请求完成后滚动到结果顶部。
## AJAX 自动重试与降级入口
AJAX 请求失败后会：
1. 自动重试一次；
2. 仍然失败时显示错误提示；
3. 提供“重新请求”；
4. 提供“普通页面打开”，继续使用 GET 筛选。
## 界面状态本地保存
通过 `localStorage` 保存：
- 哪些筛选组处于展开状态；
- 哪些筛选组已经点击“显示更多”。
存储键按归档或分类区分：
```text
pfl_filter_ui_taxonomy_18
```
真正的筛选值仍然由 URL 管理，不保存在本地存储中。
---
# 完整功能
## 产品与属性
- `product` 自定义文章类型；
- 多层级产品分类；
- 品牌、电压、功能、材质、行业等 taxonomy；
- 价格、功率、转速、宽度、距离和速度 meta；
- 分类专属筛选组；
- 父分类筛选配置继承。
## 筛选
- taxonomy `IN`；
- taxonomy `AND`；
- 数值区间；
- AJAX 自动更新；
- AJAX 分页；
- GET 降级；
- 地址栏与浏览器历史记录；
- 联动候选数量；
- 零结果禁用；
- Transient 缓存；
- 移动端抽屉；
- 分组折叠；
- 更多展开；
- 组内搜索；
- 已选项置顶。
## SEO
- 分类 SEO 标题；
- Meta Description；
- Canonical；
- 参数页 `noindex, follow`；
- Product、BreadcrumbList、CollectionPage、ItemList JSON-LD。
---
# v1.6.0 重点文件
```text
wp-product-navigation-filter-lab/
├── functions.php
├── style.css
├── archive-product.php
├── taxonomy-product_category.php
├── template-parts/product/
│ ├── filter-form.php
│ └── results.php
└── assets/
├── css/product.css
└── js/product-filter.js
```
## 关键函数
```php
pfl_get_filter_ui_config()
pfl_get_faceted_filter_state()
pfl_ajax_filter_products()
```
## 前端关键能力
```javascript
openDrawer()
closeDrawer()
setGroupExpanded()
orderAndLimitGroupOptions()
requestProducts()
updateFacetState()
```
---
# 安装与升级
## 从 v1.5.0 升级
主题目录名保持不变，可以直接覆盖旧版本。
升级后建议：
```text
1. 清除浏览器缓存
2. 清除页面缓存与对象缓存
3. 设置 → 固定链接 → 保存更改
4. 外观 → 产品主题演示数据
5. 导入或更新演示数据
```
本版没有改变产品内容类型和已有数据结构。
---
# 推荐测试
## 桌面端
1. 折叠和展开多个筛选组；
2. 点击“显示更多”和“收起”；
3. 选择原本靠后的选项，确认已选项置顶；
4. 使用组内搜索；
5. 滚动页面，检查吸顶摘要；
6. 点击分页，确认滚动到结果顶部。
## 移动端
1. 点击“筛选产品”打开抽屉；
2. 点击遮罩和关闭按钮；
3. 使用 `Esc` 关闭；
4. 使用键盘 `Tab` 检查焦点限制；
5. 检查页面滚动是否锁定；
6. 检查底部“查看多少个产品”数量；
7. 点击查看产品，确认关闭抽屉并定位结果。
## AJAX 错误
可临时阻止 `admin-ajax.php` 请求，检查：
```text
自动重试
错误提示
重新请求
普通页面打开
```
## 本地状态
展开筛选组和更多选项后刷新页面，确认界面状态恢复；URL 中不应增加这些界面状态参数。
---
# 后续方向
## v1.7.0
建议增加产品对比、本地收藏和产品快速查看。
## v1.8.0
建议建立筛选索引表、索引重建工具、性能测试数据和查询监控页面。
## v2.0.0
将产品内容类型、属性、查询和后台管理迁移为独立插件，主题只保留展示模板。
---
# 版本记录
## v1.6.0
- 移动端筛选抽屉；
- 抽屉遮罩、滚动锁定和焦点管理；
- 移动端固定操作栏；
- 筛选组折叠；
- “显示更多 / 收起”；
- 已选项置顶；
- 组内搜索；
- 桌面端吸顶摘要；
- 产品骨架加载；
- AJAX 自动重试和 GET 降级入口；
- 界面展开状态本地保存。
## v1.5.0
- 联动筛选计数；
- 零结果选项禁用；
- Transient 缓存与版本失效。
## v1.4.0
- 分类内容管理；
- SEO 与结构化数据。
## v1.3.0
- 动态产品属性；
- 分类专属筛选配置。
## v1.2.0
- AJAX 无刷新筛选与分页。
## v1.1.0
- 筛选体验与查询优化。
## v1.0.0
- 产品分类导航和多条件筛选基础版。
## License
GPL-2.0-or-later