WP Manifestindependent plugin directory
manifest / seo / wem-breadcrumb

WEM Breadcrumb

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

★ 0stars
v1.0.0latest · 1mo ago

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/coowinit/wem-breadcrumb/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

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 面包屑

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

设置页主要包含两部分:

  1. CPT / Taxonomy 映射
  2. 分隔符设置

插件会自动读取当前网站的公开自定义文章类型,并为每个 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 网站中最常见的面包屑需求,不为了极少发生的边缘场景持续增加配置和复杂度。

Releases

1 release.

Tag
Published
v1.0.0 latest
Sep 24, 2026 1mo ago

These releases are tags only. The author does not attach a packaged zip, so there are no download counts to report.