概览

团队为何搜索这个库

当路由上下文很重要，且你需要一个能配合 Angular Router、模板和结构化导航路径的导航辅助时，请使用这些 Angular 面包屑。

安装

npm install ng-hub-ui-breadcrumbs

跳转到

适用于

文档站点
管理后台
多层级应用
感知路由的导航

关于 breadcrumbs

ng-hub-ui-breadcrumbs 为 Angular 应用提供了一个感知路由的面包屑组件，适用于管理后台、文档站点和多层级产品。当导航深度增长、用户需要比返回按钮更多的方向感时，它会非常有用。

功能指南

核心功能

基础的 breadcrumbs 功能，支持自动路由检测和导航路径显示。

示例:

基础面包屑

直接从路由配置读取的路径，无需额外接线。

Items are generated from the data.breadcrumb configuration of active routes.

代码

导入:

模板:

组件:

路由之外的目标

指向 Angular 应用之外或指向下载文件的条目，渲染为普通链接。

Example.com leaves the app in a new tab, Handbook downloads a file, and Docs is an ordinary in-app crumb routed through routerLink. The last crumb is never a link, whatever it declares.

代码

导入:

模板:

组件:

作为信号的路径

页头的标题直接取自最后一段路径。`HubBreadcrumbsService.breadcrumbs` 是一个信号，组件之外的任何东西都能从它派生，无需订阅，也没有需要清理的东西。

INV-2026-0184

in Invoices · 5 levels deep

The heading and the crumbs are two readings of the same signal. Only the trail changes when you move; neither the header nor the component is told anything.

代码

导入:

模板:

组件:

动态内容

从路由数据和解析器动态解析 breadcrumbs 内容，并支持占位符。

示例:

动态面包屑

标签由路由中的占位符与其 resolver 返回的数据组合而成。

The last crumb comes from a route declaring breadcrumb: "Dynamic: {name}", resolved with that route's data. This page has no router tree, so the demo is handed the resulting trail — the route configuration is in the TS tab.

代码

导入:

模板:

组件:

模板与自定义

丰富的自定义选项，可为 breadcrumbs 项使用自定义模板并增强样式。

示例:

自定义模板

用 hubBreadcrumbItem 模板接管每一项的标记。

The hubBreadcrumbItem directive allows custom rendering of each element.

代码

导入:

模板:

组件:

高级功能

增强功能，包括图标支持、面向国际化应用的 RTL 布局兼容性、长路径折叠以及基于令牌的键盘焦点环。

示例:

路径中的图标

在路由数据中声明的图标，通过自定义项模板渲染。

代码

导入:

模板:

组件:

RTL 布局

从右到左的支持，分隔符位于路径来向的一侧。

代码

导入:

模板:

组件:

截断与工具提示

用省略号截断过长的标签，悬停时显示完整文本。

Each label is capped at --hub-breadcrumb-max-item-width (12rem). Only the items that overflow get a tooltip.

代码

导入:

模板:

组件:

折叠较长的路径

将较深路径的中间部分折叠到指示按钮之后，点击即可就地展开。

Six crumbs, no collapsing — the default

maxItems = 4 — one crumb each side of the indicator

maxItems = 4 with two crumbs kept on each side

Indicator opened 0 time(s) — that is the collapsedClick output. The trail expands on its own and collapses again on the next navigation.

代码

导入:

模板:

组件:

键盘焦点环

链接和折叠指示器上的设计系统焦点环，可通过 CSS 变量重新着色。

Default ring — press Tab to walk the trail

Re-tinted ring on the same markup

The ring reaches the collapsed indicator too, which is a button and therefore part of the tab order. Note where the overrides live: the focus tokens are declared on :host, so a value set on an ancestor never reaches them — put it on the <hub-breadcrumb> element or inside it. (The accent slot is the one exception, left undeclared on purpose so it does inherit.)

代码

导入:

模板:

组件:

核心特性

最近更改

Version 22.6.0 - 9/6/26, 12:00 AM

added: HubBreadcrumbsService.breadcrumbs exposes the trail as a signal. The service published only an Observable, so every consumer inside a signal-based component repeated the same toSignal(svc.breadcrumbs$, { initialValue: [] }) wrapper, the component in this library included. The wrapping now happens once inside the service, which also subscribes the route tree once for the whole application instead of once per breadcrumb on screen. breadcrumbs$ stays exactly as it was for code that composes with rxjs.

changed: HubBreadcrumbComponent no longer re-exports breadcrumbs$. The component carried the Observable of the service as a public field and a signal derived from it, so a single trail had two public surfaces on the same class and neither was the one the template rendered. It now reads HubBreadcrumbsService.breadcrumbs directly: anyone who was reading the field can inject the service, which is where the trail came from anyway, and anyone substituting the service must publish breadcrumbs. See BREAKING_CHANGES.md.

fixed: Opening a collapsed trail from the keyboard no longer leaves focus on the page body. Expanding removes the ellipsis indicator the reader just activated, and the browser answers that by focusing the body, so someone who had pressed Enter had to tab from the top of the page to reach the crumbs they asked for. Focus is now handed to the first crumb the gesture reveals, the one at itemsBeforeCollapse, which takes it through a temporary tabindex of -1 when it renders as plain text. Consumers who moved focus by hand in (collapsedClick) can drop that code.

fixed: The current crumb is announced as the current page even when the consumer renders it. aria-current="page" sat on the default span, the one branch a hubBreadcrumbItem template replaces, so a trail with a custom template reached assistive technology with nothing marking the current page while the docs promised the attribute unqualified. It now sits on the li, which wraps every branch. The attribute moved: a stylesheet or a test selecting .hub-breadcrumb__text[aria-current] should read .hub-breadcrumb__item[aria-current], while the hub-breadcrumb__item--active modifier is unchanged and is still the styling hook.

fixed: --hub-breadcrumb-accent set from the application reaches the component again. The slot was declared on :host, which under emulated encapsulation is a [_nghost] rule on the crumb element itself, so a consumer rule on hub-breadcrumb lost, one on .hub-breadcrumb tied and lost on source order, and a value inherited from an ancestor, the hub-breadcrumb-theme() mixin included, never reached the links at all. The slot is no longer declared on the host: it is read where it is consumed, as var(--hub-breadcrumb-accent, var(--hub-sys-color-primary, #0d6efd)), so the default look is byte-identical, variant still wins over a consumer rule, and a plain tag or class rule, or any ancestor, now recolours the links and everything derived from them. The remaining --hub-breadcrumb-* defaults still live on :host, so overriding those still means the crumb element itself or .hub-breadcrumb__list.

fixed: The built-in variant list in the component names the same nine accents its stylesheet emits. 22.2.0 grew the accent set from five to nine in the SCSS loop, but BUILT_IN_VARIANTS was left at the original five, so secondary, neutral, light and dark were treated as custom accents and got an inline --hub-breadcrumb-accent on the host on top of the stylesheet rule that already set them. Nothing rendered differently, since both paths resolve to the same token, but an inline style outranks anything a consumer writes in a sheet, so overriding the accent for those four took an !important it should never have needed. The variant JSDoc listed the same stale five and now names all nine.

fixed: The documentation described an API this library does not have, and taught a mixin selector that does not win. The README opened its reference announcing a single optional input above a table of seven inputs and one output, listed five built-in variants against the nine the stylesheet emits, never named HubBreadcrumbLabelDirective or the tooltip adapter contract although both are exported, promised truncation without saying that a hubBreadcrumbItem template renders its own elements, which the scoped styles cannot reach, so they get neither the ellipsis nor the tooltip, and still announced v21.1.0 as the latest release. The hub-breadcrumb-theme() snippet included the mixin on a bare class, which ties with :host and loses on source order, and now lands on the crumb element with a selector that outranks it. BREAKING_CHANGES.md was titled after v21.1.0 over a 22.4.0 section, FUNCTIONALITIES.md marked (collapsedClick) and the tooltip adapter as uncovered while the examples exercise both, and docs/css-variables-reference.md referenced the three derived accent tokens without documenting any of them. Documentation only, with no change to code, types or styles.

deprecated: HubBreadcrumbsModule is deprecated and will be removed in 23.0.0. It imports and exports HubBreadcrumbComponent and HubBreadcrumbItemDirective, both standalone and both already exported from the entry point, and provides nothing of its own, so importing them directly is the whole migration. HubBreadcrumbsService is providedIn: root and never travelled through the module. The class carried no @deprecated tag until now, so neither an editor nor the build could warn anyone. See BREAKING_CHANGES.md.

Version 22.5.2 - 9/2/26, 12:00 AM

fixed: A breadcrumb asked for before the first navigation no longer throws. breadcrumbs$ opens with startWith(undefined), so the route tree is walked the moment anything subscribes, and a page shell that draws its breadcrumb on the first paint subscribes while the initial navigation is still in flight. In that window a child route exists with no snapshot and child.snapshot.url threw — into the subscription drawing the shell, so what a consumer saw was the whole header gone rather than a missing breadcrumb. A route with no snapshot is skipped rather than guessed at: it has no segments and no resolved data, so there is nothing to name yet. Present in every release from 21.0.0 onwards.

Version 22.5.1 - 9/1/26, 12:00 AM

changed: The homepage in the manifest points at this library's own documentation page rather than at the site root. Metadata only.

Version 22.5.0 - 8/29/26, 12:00 AM

added: Collapsing for long trails: `maxItems`, `itemsBeforeCollapse` and `itemsAfterCollapse` fold the middle behind an indicator button that expands in place and emits `collapsedClick`.

added: Crumbs can point outside the router: `href`, `target`, `rel` and `download` on `BreadcrumbItem`, accepted both from the new object form of `data.breadcrumb` and from the new `items` input. A `_blank` crumb defaults to `rel="noopener noreferrer"`.

added: Keyboard focus ring on links and on the collapsed indicator, built on the design-system focus tokens and exposed as `--hub-breadcrumb-focus-*` / `--hub-breadcrumb-link-focus-color`.

changed: `BreadcrumbItem` and `BreadcrumbTemplateContext` are now exported from the public API, and `BreadcrumbItem.data` became optional.

Version 22.4.3 - 8/17/26, 12:00 AM

fixed: The package shipped without its licence notice. package.json declared MIT, but no LICENSE file travelled in the tarball — and MIT itself requires the copyright notice to be included in distributions. The notice ships now.

Version 22.4.2 - 8/8/26, 12:00 AM

fixed: Documentation links now point at the canonical localized URLs. The README linked to https://hubui.dev/<path> with no locale prefix and no trailing slash, and both forms are 301-redirected, so every reader arriving from npm or GitHub landed on a redirect instead of the canonical page.

Version 22.4.1 - 7/28/26, 12:00 AM

fixed: The active (last) crumb now declares aria-current=page so assistive technology announces the current position.

Version 22.4.0 - 7/7/26, 12:00 AM

changed: BREAKING (packaging) — the SCSS ships at ng-hub-ui-breadcrumbs/styles. The theme mixin now builds to dist/breadcrumbs/styles/… instead of dist/breadcrumbs/src/lib/styles/…, so @use 'ng-hub-ui-breadcrumbs/styles' resolves. Any @use that reached into src/lib/styles has to be updated.

Version 22.3.1 - 7/6/26, 12:00 AM

fixed: Docs: the default values in docs/css-variables-reference.md were resynchronized with the actual declarations (--hub-breadcrumb-item-padding-x, --hub-breadcrumb-accent, --hub-breadcrumb-link-hover-color), now guarded by the repo-level tokens-parity check.

Version 22.3.0 - 6/29/26, 12:00 AM

added: Opt-in per-item truncation via the `truncateItems` input + `--hub-breadcrumb-max-item-width`.

added: `HubBreadcrumbLabelDirective` showing a tooltip only when a label overflows.

added: Optional hub-ui tooltip integration via `provideHubBreadcrumbTooltip(hubTooltipAdapter)` (native `title` fallback).

Version 22.2.0 - 6/26/26, 12:00 AM

changed: The accent moved to the open-set "local accent slot" pattern: variant re-bases a single --hub-breadcrumb-accent and the link hover is derived locally as --hub-breadcrumb-accent-emphasis with color-mix, mirroring the ds engine. The built-in list grew from five accents to the nine canonical ones (primary · secondary · success · danger · warning · info · neutral · light · dark), and a bare [data-variant] block re-derives the family from the slot, so any custom accent the host app adds recolours the links with one CSS rule and no recompilation.

added: Tokens --hub-breadcrumb-accent-emphasis (link hover), --hub-breadcrumb-accent-subtle and --hub-breadcrumb-accent-on, all derived locally from the accent slot.

Version 22.1.2 - 6/26/26, 12:00 AM

fixed: The Angular peer dependency range was corrected to >=18.0.0. The library uses APIs whose real minimum is Angular 17.3, so the previous >=17.0.0 range let it install on incompatible versions.

Version 22.1.1 - 6/25/26, 12:00 AM

fixed: Design-token consistency pass: inline fallback defaults aligned with the canonical ng-hub-ui-ds values, and hardcoded literals (z-index, font-weight, line-height, radii, theme-aware colours) routed through their --hub-sys-* / --hub-ref-* tokens so they follow the active theme. No visual change when the ds tokens are loaded.

Version 22.1.0 - 6/24/26, 12:00 AM

added: The variant input on <hub-breadcrumb>, selecting a semantic accent for the links and their hover while the current item stays muted. Any string outside the built-in set is also accepted and read as --hub-sys-color-<variant>. New token --hub-breadcrumb-accent.

added: The hub-breadcrumb-theme() Sass mixin — surface, spacing, divider, current-item colour, links and accent in one call. Every parameter is optional, so only the ones passed are emitted as --hub-breadcrumb-* overrides.

Version 22.0.0 - 6/17/26, 12:00 AM

changed: Aligned with Angular 22, and the README standardized.

Version 21.1.0 - 3/17/26, 12:00 AM

changed: The selector was renamed from hub-breadcrumbs to hub-breadcrumb, and the styles are bundled within the component — a manual style import is no longer required.

Version 21.0.0 - 3/9/26, 12:00 AM

changed: BREAKING — the service, module, components and directives were renamed for consistency across the library family.