manifest / unclassified / wem-breadcrumb

WEM Breadcrumb

🧭 一款面向企业 WordPress 网站的轻量级面包屑插件，支持 CPT、自定义分类法、主要/备用分类法映射及可配置分隔符。

by WEM · github.com/coowinit/wem-breadcrumb

★ 0stars

0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/coowinit/wem-breadcrumb/archive/refs/heads/main.zip

Readme github.com/coowinit/wem-breadcrumb ↗

WEM Breadcrumb 是一款面向企业 WordPress 网站的轻量级面包屑插件。

当前稳定版本：v1.0.0

它只负责一件事：根据 WordPress 当前内容结构生成稳定、清晰、可维护的面包屑路径。

插件重点支持企业站中常见的 Page、Post、CPT 与层级 Taxonomy 结构，并允许为自定义文章类型配置“主要分类法 + 备用分类法”。

Schema / BreadcrumbList、SEO Meta、Canonical、Sitemap 等 SEO 能力不属于本插件职责，应由独立 SEO 插件统一处理。

核心特点

支持普通文章、页面及父子页面
支持 Category、Tag、Author、日期归档、Search、404、分页等常见页面
支持自定义文章类型（CPT）
支持层级自定义分类法（Taxonomy）
CPT 可配置主要分类法和备用分类法
分类父子层级自动生成完整路径
中间分类保留链接，当前页面默认不链接
首页默认不显示面包屑
多分类时直接使用 WordPress 返回的第一个有效分类
后台提供简单的分隔符选择
同时兼容 <div class="breadcrumb"> 与 <ul class="breadcrumb"><li>...</li></ul> 两种常见主题结构
CSS 使用插件版本号加载，便于浏览器 / CDN 缓存更新
不包含 Schema、SEO、Block、REST API 等与核心目标无关的功能

安装与调用

安装并启用插件后，在主题模板需要显示面包屑的位置调用：

<?php wem_breadcrumb(); ?>

推荐结构：

<div class="breadcrumb">
    <?php wem_breadcrumb(); ?>
</div>

如果主题使用列表结构，也可以：

<ul class="breadcrumb justify-content-center text-button fw-4">
    <li><?php wem_breadcrumb(); ?></li>
</ul>

插件不会注册旧的 get_the_breadcrumb() 函数，避免和主题或其他插件中的同名函数发生 Cannot redeclare 冲突。

前端输出示例

插件内部会输出类似：

<a href="https://example.com/">Home</a>
<span class="breadcrumb-separator">&gt;</span>
<a href="https://example.com/product-cat/product/">Product</a>
<span class="breadcrumb-separator">&gt;</span>
<a href="https://example.com/product-cat/wpc-wall-panel/">WPC Wall Panel</a>
<span class="breadcrumb-separator">&gt;</span>
<span class="current">Current Product</span>

规则固定为：

首页
→ 不显示面包屑

中间路径
→ 显示
→ 保留链接

当前页面
→ 显示
→ 不添加链接

后台设置

后台位置：

设置
└── WEM 面包屑

插件列表中也提供“设置”快捷链接。

设置页主要包含两部分：

CPT / Taxonomy 映射
分隔符设置

插件会自动读取当前网站的公开自定义文章类型，并为每个 CPT 列出与其关联的公开层级分类法。

CPT / Taxonomy 映射

每个 CPT 可以设置：

主要分类法
备用分类法（可选）

例如：

内容类型	主要分类法	备用分类法
`products`	`product_cat`	—
`solutions`	`solution_region`	`solution_cat`
`videos`	`video_cat`	—
`downloads`	`download_cat`	—
`faqs`	`faq_cat`	—

什么是“备用分类法”？

备用分类法不是父分类，也不是第二层分类。

它的含义是：

先检查主要分类法
        ↓
有 Term
→ 使用主要分类法

没有 Term
        ↓
检查备用分类法
→ 使用备用分类法

父分类 / 子分类仍然由同一个层级 Taxonomy 自身的 parent 关系自动处理。

⚠️ Solutions 设置特别注意

当前项目中的 Solutions 同时存在两套实际使用的分类体系：

solution_region
→ 区域解决方案
→ 例如：Southeast Asia

solution_cat
→ 普通解决方案分类
→ 例如：3D Wall Panel & Veneer

后台推荐固定设置为：

内容类型	主要分类法	备用分类法
`solutions`	`solution_region`	`solution_cat`

记忆规则：

区域优先，普通分类兜底。

具体逻辑：

先找 solution_region
        ↓
有区域分类
→ 使用 solution_region 构建面包屑

没有区域分类
        ↓
再找 solution_cat
→ 使用 solution_cat 构建面包屑

区域 Solution 示例：

Home > Southeast Asia > 当前 Solution

普通 Solution 示例：

Home > 3D Wall Panel & Veneer > 当前 Solution

不要把主要分类法和备用分类法都设置成 solution_cat。

默认映射

为了让插件首次启用时即可工作，在管理员尚未保存后台设置之前，插件内置以下默认映射：

products  → product_cat
solutions → solution_region → solution_cat
videos    → video_cat

保存后台设置后，对应 CPT 使用保存后的配置。

多分类处理规则

本插件主要面向产品、Solution、Video 等企业站内容，这些内容通常只归属于一个分类。

因此采用最简单明确的规则：

没有分类
→ 不输出分类层级

只有一个分类
→ 使用该分类

存在多个分类
→ 使用 WordPress 返回的第一个有效分类

插件不提供：

Primary Term / 主分类
主分类 Meta Box
多分类优先级
特殊项目覆盖规则

这是有意的设计取舍，用于保持插件简单、稳定和易维护。

分隔符设置

后台可以直接选择：

符号	说明
`>`	大于号（默认）
`›`	单右尖括号
`/`	斜杠
`→`	右箭头
`»`	双右尖括号

无论选择哪一种，HTML 结构保持一致：

<span class="breadcrumb-separator">»</span>

只改变显示字符，不改变路径结构。

前端 CSS

插件自动加载：

assets/css/wem-breadcrumb.css

默认样式：

.breadcrumb,
.breadcrumb > li {
    display: flex;
    flex-wrap: wrap;
    align-items: center;
    gap: 0 5px !important;
}

这样可以同时兼容：

<div class="breadcrumb">...</div>

以及：

<ul class="breadcrumb">
    <li>...</li>
</ul>

gap: 0 5px 表示：

上下间距：0
左右间距：5px

分隔符不再额外设置左右 margin，避免间距重复叠加。

CSS 使用 WEM_BREADCRUMB_VERSION 作为 wp_enqueue_style() 的版本参数。v1.0.0 加载形式类似：

wem-breadcrumb.css?ver=1.0.0

插件升级后 URL 会随版本变化，可减少浏览器或 CDN 继续读取旧 CSS 的情况。

公共 API

直接输出面包屑

<?php wem_breadcrumb(); ?>

返回面包屑 HTML

$html = wem_get_breadcrumb();

获取路径数据

$items = wem_get_breadcrumb_items();

返回的路径数据与 HTML 渲染分离，方便后续维护，同时避免把路径判断和前端输出混写在同一个函数中。

支持的页面类型

当前支持：

首页（默认不输出）
Post / Category
Page / 父子 Page
CPT Single
CPT Archive
自定义层级 Taxonomy
Search
Tag
Author
年 / 月 / 日归档
404
Pagination
Attachment（基础支持）

项目边界

WEM Breadcrumb 坚持“一个插件解决一个核心问题”。

因此 v1.0.0 不包含：

Schema / BreadcrumbList
SEO Meta
Canonical
Sitemap
Gutenberg Block
Widget
REST API
Primary Term / 主分类选择
导入 / 导出
复杂模板系统

其中 BreadcrumbList Schema 如有需要，应由独立的 SEO / Schema 插件统一生成，而不是在本插件中重复输出。

从主题旧代码迁移

本项目最初由主题 functions.php 中的 get_the_breadcrumb() 演进而来。

正式迁移完成后，主题应统一调用：

<?php wem_breadcrumb(); ?>

并删除旧的：

function get_the_breadcrumb() {
    // ...
}

这样可以避免：

新旧面包屑逻辑同时存在
不同模板输出结果不一致
同名函数冲突
后续维护时无法确认页面实际使用哪套代码

当前 v1.0.0 发布前已完成该迁移和整站回归验证。

v1.0.0 验收状态

正式封板前已验证：

Products / product_cat 路径正常
Solutions / solution_region 路径正常
Solutions 无区域分类时可回退 solution_cat
Videos 等 CPT 映射正常
分类父子层级链接正常
当前页面显示但不链接
分隔符切换正常
首页不输出面包屑
<div class="breadcrumb"> 布局正常
<ul class="breadcrumb"><li>...</li></ul> 布局正常
长标题可自然换行
CSS 版本号缓存更新正常
主题旧 get_the_breadcrumb() 已删除
整站回归测试未发现新的路径或链接问题

版本历程

v1.0.0

首个正式稳定版。

完成核心路径生成、CPT / Taxonomy 后台映射、Solutions 主要 / 备用分类法、分隔符设置、前端样式兼容及整站迁移验证。

v0.3.x

完善分隔符设置与两种常见主题 Breadcrumb HTML 结构的 CSS 兼容。

v0.2.0

增加 CPT / Taxonomy 后台映射设置。

v0.1.x

完成 Breadcrumb Trail、HTML Renderer、分类链接、旧主题迁移与核心路径验证。

设计原则

WEM Breadcrumb 的核心原则是：

简单、稳定、可预测、容易维护。

默认解决企业 WordPress 网站中最常见的面包屑需求，不为了极少发生的边缘场景持续增加配置和复杂度。