Angular 导航菜单组件 | ng-hub-ui-nav
Angular 导航组件，支持下拉菜单、逐级深入面板、响应式折叠、Router 集成和 CSS 变量主题。
API 参考
这里是 nav 的完整契约：你可以绑定、监听、投影和设置主题的一切，都集中在一处。接入你需要的部分，自定义你想要的样式——它是 standalone 的，且对 signal 友好。
输入
通过 4 个输入项精细调校 nav。像绑定任意 Angular @Input 一样绑定它们。
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
items必填 | HubNavItem[] | — | 要渲染的导航项数组。每一项定义其类型（link、dropdown、header、separator、custom）、label、route、icon、badge、children 等。 |
config | Partial<HubNavConfig> | {} | 与全局默认值合并的部分配置覆盖。控制方向、下拉触发方式、折叠模式、断点、位置等。 |
navClass | string | '' | 应用于 nav 容器元素的额外 CSS 类。 |
itemTemplate | TemplateRef<HubNavItemTemplateContext> | null | null | 通过输入绑定渲染导航项的可选自定义模板。hubNavItemTemplate 指令的优先级高于此输入。 |
输出
响应 nav 的行为——有 5 个事件可供你挂接逻辑。
| 名称 | 类型 | 描述 |
|---|---|---|
itemClick | OutputEmitterRef<HubNavItem> | 当 link 项被点击时触发。提供被点击的 HubNavItem。 |
dropdownOpen | OutputEmitterRef<HubNavItem> | 当 dropdown 项被打开时触发。 |
dropdownClose | OutputEmitterRef<HubNavItem> | 当 dropdown 项被关闭时触发。 |
mobileToggle | OutputEmitterRef<boolean> | 当移动端面板被切换时触发。打开时提供 true，关闭时提供 false。 |
panelChange | OutputEmitterRef<HubNavPanelEvent> | 当面板被打开、关闭、下钻或返回导航时触发。提供该项、面板索引和操作类型。 |
模板
打造你自己的样式——3 个模板插槽让你可以投影自定义标记。
| 名称 | 描述 | 示例 |
|---|---|---|
hubNavStart | 在 start 插槽中投影自定义内容。水平方向：视觉起始处（LTR 中为左侧，RTL 中为右侧）。垂直方向：主列的顶部。 | <hub-nav [items]="items">
<ng-template hubNavStart let-collapsed="collapsed">
<img src="logo.svg" alt="Brand" />
@if (!collapsed) { <span>App Name</span> }
</ng-template>
</hub-nav> |
hubNavEnd | 在 end 插槽中投影自定义内容。水平方向：视觉结束处（LTR 中为右侧，RTL 中为左侧）。垂直方向：主列的底部。 | <hub-nav [items]="items">
<ng-template hubNavEnd>
<button type="button">Sign out</button>
</ng-template>
</hub-nav> |
hubNavItemTemplate | 使用自定义模板覆盖默认的项渲染。接收 HubNavItemTemplateContext，其包含 $implicit（item）、active、expanded 和 depth 属性。 | <hub-nav [items]="items">
<ng-template hubNavItemTemplate let-item let-active="active">
<span [class.fw-bold]="active">{{ item.label }}</span>
@if (item.badge) { <span class="badge">{{ item.badge }}</span> }
</ng-template>
</hub-nav> |
CSS 变量
用 42 个 CSS 变量为每一个像素设置主题。在 :root 处覆盖它们，或将其限定到某个容器范围内。
布局
控制 nav 的整体尺寸、内边距和间距。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-height | 3.5rem | length | 导航栏的高度。 3rem4remauto |
--hub-nav-padding-x | 1rem | length | nav 容器的水平内边距。 0.5rem1.5rem2rem |
--hub-nav-padding-y | 0.5rem | length | nav 容器的垂直内边距。 0.25rem0.75rem1rem |
--hub-nav-gap | 0.25rem | length | nav 项之间的间隙。 00.5rem1rem |
颜色与背景
控制 nav 的配色方案和边框。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-bg | #fff | color | 导航栏的背景颜色。 #f8f9fatransparentvar(--hub-sys-surface-page) |
--hub-nav-color | #212529 | color | 导航的基础文本颜色。 #333#fffvar(--hub-sys-text-primary) |
--hub-nav-border-color | #dee2e6 | color | 导航栏的边框颜色。 transparent#cccvar(--hub-sys-border-color-default) |
Items
各种状态下单个导航项的样式。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-item-padding-x | 1rem | length | nav 项内部的水平内边距。 0.5rem1.25rem1.5rem |
--hub-nav-item-padding-y | 0.5rem | length | nav 项内部的垂直内边距。 0.25rem0.75rem1rem |
--hub-nav-item-color | #212529 | color | nav 项的文本颜色。 #495057#fffinherit |
--hub-nav-item-border-radius | 0.25rem | length | nav 项的边框半径。 00.375rem50rem |
--hub-nav-item-hover-bg | rgba(0, 0, 0, 0.04) | color | 悬停时的背景颜色。 #e9ecefrgba(255, 255, 255, 0.1)transparent |
--hub-nav-item-hover-color | #0d6efd | color | 悬停时的文本颜色。 #0a58ca#fffvar(--hub-sys-color-primary) |
--hub-nav-item-active-bg | #0d6efd | color | 项处于激活状态时的背景颜色。 #0a58catransparentvar(--hub-sys-color-primary) |
--hub-nav-item-active-color | #fff | color | 项处于激活状态时的文本颜色。 #0d6efd#212529var(--hub-sys-text-inverse) |
--hub-nav-item-disabled-color | #6c757d | color | 禁用项的文本颜色。 #adb5bdvar(--hub-sys-text-muted) |
--hub-nav-item-disabled-opacity | 0.65 | number | 禁用项的不透明度。 0.50.41 |
Dropdown
自定义下拉面板的外观和定位。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-dropdown-bg | #fff | color | 下拉面板的背景颜色。 #f8f9fa#343a40var(--hub-sys-surface-elevated) |
--hub-nav-dropdown-border-color | #dee2e6 | color | 下拉面板的边框颜色。 transparent#ccc |
--hub-nav-dropdown-border-radius | 0.375rem | length | 下拉面板的边框半径。 00.25rem0.5rem |
--hub-nav-dropdown-shadow | 0 0.5rem 1rem rgba(0, 0, 0, 0.15) | shadow | 下拉面板的阴影。 none0 4px 8px rgba(0,0,0,0.1)0 1rem 3rem rgba(0,0,0,0.175) |
--hub-nav-dropdown-min-width | 12rem | length | 下拉面板的最小宽度。 10rem15rem200px |
Brand
品牌插槽区域的样式。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-brand-font-size | 1.25rem | length | 品牌文本的字号。 1rem1.5rem2rem |
--hub-nav-brand-font-weight | 600 | number | 品牌文本的字重。 400700800 |
--hub-nav-brand-color | #212529 | color | 品牌的文本颜色。 #fff#0d6efdinherit |
移动端面板
响应式移动端导航面板的配置。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-mobile-bg | #fff | color | 移动端面板的背景颜色。 #f8f9fa#212529var(--hub-sys-surface-page) |
--hub-nav-mobile-width | 18rem | length | offcanvas 移动端面板的宽度。 15rem20rem80vw |
--hub-nav-mobile-backdrop-bg | rgba(0, 0, 0, 0.5) | color | 移动端面板后方的背景遮罩颜色。 rgba(0, 0, 0, 0.3)rgba(0, 0, 0, 0.75)transparent |
--hub-nav-mobile-transition | 300ms ease | transition | 移动端面板开关动画的过渡时序。 200ms ease-in-out400ms ease150ms linear |
Accordion 与图标
垂直 accordion 的缩进和图标尺寸。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-accordion-indent | 1rem | length | 垂直 accordion 模式下每个嵌套层级的左侧缩进。 0.5rem1.5rem2rem |
--hub-nav-icon-size | 1.25rem | length | 导航项图标的尺寸。 1rem1.5rem2rem |
--hub-nav-icon-gap | 0.5rem | length | 图标与标签文本之间的间隙。 0.25rem0.75rem1rem |
Panel
堆叠面板逐级下钻导航的样式。
| 变量 | 默认值 | 类型 | 描述 |
|---|---|---|---|
--hub-nav-panel-width | 16rem | length | 每个面板的默认宽度。 14rem18rem20rem |
--hub-nav-panel-zindex | 100 | number | 面板的堆叠顺序（应低于 dropdown 的 z-index）。 50100200 |
--hub-nav-panel-bg | var(--hub-sys-surface-page, #fff) | color | 面板的背景颜色。 #f8f9fa#fffvar(--hub-sys-surface-elevated) |
--hub-nav-panel-color | var(--hub-sys-text-primary, #212529) | color | 面板内部的文本颜色。 #333#fffinherit |
--hub-nav-panel-border-color | var(--hub-sys-border-color-default, #dee2e6) | color | 面板之间的边框颜色。 transparent#ccc |
--hub-nav-panel-shadow | inset 4px 0 8px -4px rgba(0, 0, 0, 0.1) | shadow | 面板的阴影。 none2px 0 4px rgba(0,0,0,0.05) |
--hub-nav-panel-header-height | 3rem | length | 面板头部的高度。 2.5rem3.5rem4rem |
--hub-nav-panel-header-bg | var(--hub-sys-surface-elevated, #f8f9fa) | color | 面板头部的背景颜色。 #fff#e9eceftransparent |
--hub-nav-panel-back-color | var(--hub-sys-text-secondary, #6c757d) | color | 面板头部返回按钮的颜色。 #212529#0d6efdinherit |
--hub-nav-panel-back-hover-bg | rgba(0, 0, 0, 0.04) | color | 面板头部按钮的悬停背景。 #e9ecefrgba(0,0,0,0.08) |
样式与主题
尚未记录任何样式示例。本节将包含自定义方案和主题示例。