API 参考

这里是 nav 的完整契约：你可以绑定、监听、投影和设置主题的一切，都集中在一处。接入你需要的部分，自定义你想要的样式——它是 standalone 的，且对 signal 友好。

输入

通过 34 个输入项精细调校 nav。像绑定任意 Angular @Input 一样绑定它们。

名称	类型	默认值	描述
`items`必填	`HubNavItem[]`	—	要渲染的导航项数组。每一项定义其类型（link、dropdown、header、separator、custom）、label、route、icon、badge、children 等。
`config`	`Partial<HubNavConfig>`	`{}`	与全局默认值合并的部分配置覆盖。控制方向、下拉触发方式、折叠模式、断点、位置等。
`navClass`	`string`	`''`	应用于 nav 容器元素的额外 CSS 类。
`itemTemplate`	`TemplateRef<unknown> \| null`	`null`	通过输入绑定渲染导航项的可选自定义模板。hubNavItemTemplate 指令的优先级高于此输入。
`autoOpenFromRoute`	`boolean`	`false`	为 true 时，导航会在初始化及每次导航结束后，自动打开与当前激活路由 URL 匹配的下拉菜单和下钻面板。适用于由 URL 驱动展开状态的侧边栏导航。
`color`	`'primary' \| 'success' \| 'danger' \| 'warning' \| 'info' \| string`	`undefined`	应用于悬停/激活效果的语义强调色。接受语义名称（primary、success、danger、warning、info）、已注册的强调色名称、CSS 命名颜色，或字面的 #hex / rgb() / oklch() / var()。裸词会解析为 --hub-sys-color-<name> token；省略时默认为 primary。
`rail`	`boolean (two-way: model)`	`false`	仅桌面端的图标栏。为 true 时，垂直导航以栏宽渲染并仅显示图标。低于 collapseBreakpoint 时被忽略，始终由 offcanvas 行为优先。可通过 [(rail)] 双向绑定。
`orientation (config)`	`'horizontal' \| 'vertical'`	`'horizontal'`	导航的方向：horizontal 渲染为顶部栏，vertical 渲染为侧边栏。
`verticalExpandMode (config)`	`'accordion' \| 'flyout' \| 'panel'`	`'accordion'`	垂直方向下子项的展开方式：accordion 内联展开，flyout 打开定位的侧向子菜单，panel 打开堆叠的下钻面板。
`dropdownTrigger (config)`	`'hover' \| 'click' \| 'both'`	`'click'`	打开下拉菜单的机制：悬停（hover）、点击（click），或两者兼有。
`dropdownRenderMode (config)`	`'inline' \| 'overlay'`	`'inline'`	下拉菜单与 flyout 菜单的渲染策略：inline 在导航 DOM 内部渲染，overlay 在 body 层级的图层中渲染以避免被裁剪。panel 下钻模式不受影响。
`position (config)`	`'static' \| 'sticky' \| 'fixed'`	`'static'`	导航容器的 CSS 定位策略。sticky 定位仅在垂直导航中启用。
`stickyTop (config)`	`string`	`'0px'`	启用 sticky 定位时使用的顶部偏移量。接受任何有效的 CSS 长度值。
`collapseMode (config)`	`'offcanvas' \| 'dropdown' \| 'fullscreen'`	`'offcanvas'`	小视口下菜单折叠时的显示模式：offcanvas 滑入式抽屉、切换按钮下方的 dropdown，或 fullscreen 全屏遮罩层。
`collapseBreakpoint (config)`	`number`	`992`	视口宽度阈值（像素），低于该宽度时菜单折叠。设为 0 可禁用响应式折叠。
`offcanvasPosition (config)`	`'start' \| 'end' \| 'top' \| 'bottom'`	`'start'`	offcanvas 面板滑入的一侧。仅当 collapseMode 为 offcanvas 时生效。
`ariaLabel (config)`	`string`	`'Navigation'`	应用到 nav 元素上的无障碍标签。
`panelMaxVisible (config)`	`number`	`3`	panel 展开模式下同时可见面板的最大数量。超过后，最后一个面板会原地下钻并提供返回导航。
`sidebarSide (config)`	`'left' \| 'right'`	`'left'`	侧边栏所在的物理侧：left（面板向右延伸）或 right（面板向左延伸）。
`panelWidth (config)`	`string`	`'16rem'`	每个下钻面板的宽度。接受任何有效的 CSS 宽度值。
`railToggle (config)`	`boolean`	`true`	是否在桌面垂直导航的主列上渲染内置边缘切换按钮。当应用自带切换按钮时可禁用。可通过 --hub-nav-rail-toggle-* 令牌完全主题化，包括可替换的 SVG 箭头。
`followReplacedUrls (config)`	`boolean \| number`	`true`	导航跟随滚动监听的积极程度，后者通过替换 URL 报告读者位置：true 跟随每次报告，数字毫秒表示待其停止后再跟随，false 从不跟随。
`activeIndicator (config)`	`boolean`	`false`	激活标记是否在项目之间移动，而不是就地出现和消失。默认关闭，并遵循 prefers-reduced-motion。
`labels (config)`	`Partial<HubNavLabels>`	`undefined`	内置无障碍标签的实例级覆盖。省略的标签依次从共享的 HUBUI.NAV.* 键和英文默认值解析。
`enabled (hubNavScrollSpy) — bound as [hubNavScrollSpy]`	`boolean`	`true`	启用或禁用区块跟踪。通过选择器本身绑定：[hubNavScrollSpy]="false" 即可关闭跟踪。
`offset (hubNavScrollSpy)`	`number`	`120`	计算激活区块时用于补偿粘性头部的顶部偏移量（像素）。
`sectionSelector (hubNavScrollSpy)`	`string`	`'[data-hub-nav-scroll-spy-section]'`	用于在宿主容器内定位可跟踪区块元素的 CSS 选择器。
`sectionId (hubNavScrollSpySection) — bound as [hubNavScrollSpySection]`	`string \| null`	`null`	被跟踪区块的可选区块 id。省略时使用宿主元素的 id 属性。
`item (hub-nav-item)`必填	`HubNavItem`	—	由内部 hub-nav-item 子组件渲染的导航项。由 hub-nav 自动管理；很少直接绑定。
`depth / isActive / isExpanded / forceAccordionMode (hub-nav-item)`	`number / boolean / boolean / boolean`	`0 / false / false / false`	hub-nav-item 的内部状态输入：嵌套深度、激活与展开标志，以及在移动端或 panel 上下文中强制启用的 accordion 行为。
`items (hub-nav-item-list)`必填	`HubNavItem[]`	—	由内部 hub-nav-item-list 子组件渲染的条目。由 hub-nav 自动管理。
`panels (hub-nav-panel-container)`必填	`HubNavPanelState[]`	—	panel 展开模式下由内部 hub-nav-panel-container 渲染的已打开面板状态堆栈。
`panel (hub-nav-panel)`必填	`HubNavPanelState`	—	由内部 hub-nav-panel 子组件渲染的单个下钻面板的状态。
`itemTemplate / dropdownRenderMode / panelWidth / sidebarSide / showHeader / hideFirstPanelHeader (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container)`	`TemplateRef<unknown> \| null / HubNavDropdownRenderMode / string / HubNavSidebarSide / boolean / boolean`	—	根 hub-nav 转发给其子组件的内部接线输入（每个输入只存在于需要它的那部分组件上，连同深度以及 overlay 归属/方向类）。请通过 hub-nav 上的 config 输入进行配置，而不要直接绑定它们。

输出

响应 nav 的行为——有 11 个事件可供你挂接逻辑。

名称	类型	描述
`itemClick`	`OutputEmitterRef<HubNavItem>`	当 link 项被点击时触发。提供被点击的 HubNavItem。
`dropdownOpen`	`OutputEmitterRef<HubNavItem>`	当 dropdown 项被打开时触发。
`dropdownClose`	`OutputEmitterRef<HubNavItem>`	当 dropdown 项被关闭时触发。
`mobileToggle`	`OutputEmitterRef<boolean>`	当移动端面板被切换时触发。打开时提供 true，关闭时提供 false。
`panelChange`	`OutputEmitterRef<HubNavPanelEvent>`	当面板被打开、关闭、下钻或返回导航时触发。提供该项、面板索引和操作类型。
`railChange`	`OutputEmitterRef<boolean>`	当 rail 模型值切换时发出，支持 [(rail)] 双向绑定与应用端持久化。
`activeSectionChange (hubNavScrollSpy)`	`OutputEmitterRef<string>`	每当可见区块变化时，发出新激活区块的 id。
`clicked / toggleDropdown (hub-nav-item)`	`OutputEmitterRef<{ item: HubNavItem; event: Event }> / OutputEmitterRef<HubNavItem>`	hub-nav-item 的内部事件：clicked 发出该导航项及原始 DOM 事件，toggleDropdown 发出被切换的 dropdown 项。二者都会向上冒泡到 hub-nav 的输出。
`itemClick / dropdownToggle / panelOpen (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container)`	`OutputEmitterRef<{ item: HubNavItem; event: Event }> / OutputEmitterRef<HubNavItem> / OutputEmitterRef<HubNavItem>`	由内部列表和面板子组件在向 hub-nav 冒泡时重新发出的条目交互事件：itemClick（条目及 DOM 事件）、dropdownToggle（被切换的条目）和 panelOpen（其子项应打开面板的条目）。
`closePanel / backClick (hub-nav-panel)`	`OutputEmitterRef<string>`	由内部 hub-nav-panel 在按下关闭按钮（closePanel）或返回按钮（backClick）时发出，附带面板 id。
`panelClose / panelBack (hub-nav-panel-container)`	`OutputEmitterRef<string>`	由内部 hub-nav-panel-container 发出，附带面板 id，将关闭（panelClose）和返回（panelBack）请求转发给 hub-nav。

模板

打造你自己的样式——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>`