Angular Navigationsmenü-Komponente | ng-hub-ui-nav
Angular Navigationskomponente mit Dropdowns, Drill-down-Panels, responsivem Einklappen, Router-Integration und Theming über CSS-Variablen.
API-Referenz
Hier ist der vollständige Vertrag für nav: alles, was du binden, abhören, projizieren und gestalten kannst, an einem Ort gesammelt. Verdrahte, was du brauchst, und gestalte, was du willst — es ist standalone und Signals-freundlich.
Inputs
Stelle nav mit 40 Inputs ein. Binde sie wie jeden Angular-@Input.
| Name | Typ | Standard | Beschreibung |
|---|---|---|---|
itemsErforderlich | HubNavItem[] | — | Array von Navigationselementen, die gerendert werden. Jedes Element definiert seinen Typ (link, dropdown, header, separator, custom), label, route, icon, badge, children und mehr. |
config | Partial<HubNavConfig> | {} | Teilweise Konfigurationsüberschreibungen, die mit den globalen Standardwerten zusammengeführt werden. Steuert Ausrichtung, Dropdown-Trigger, Collapse-Modus, Breakpoint, Position und mehr. |
navClass | string | '' | Zusätzliche CSS-Klasse, die auf das nav-Container-Element angewendet wird. |
itemTemplate | TemplateRef<unknown> | null | null | Optionales benutzerdefiniertes Template zum Rendern von Nav-Elementen über Input-Bindung. Die hubNavItemTemplate-Direktive hat Vorrang vor diesem Input. |
iconTemplate | TemplateRef<HubNavItemIconContext> | null | null | Vorlage, die anstelle der Icon-Klasse gezeichnet wird, bei Einträgen mit icon. Erhält HubNavItemIconContext mit $implicit (dem Eintrag) und rail. Die Direktive hubNavItemIcon hat Vorrang vor diesem Input. |
autoOpenFromRoute | boolean | false | Wenn true, öffnet die Nav bei der Initialisierung und nach jeder Navigation automatisch die Dropdowns und Drill-down-Panels, die zur aktiven Router-URL passen. Nützlich für Sidebar-Navigationen, bei denen die URL den Offen-Zustand steuert. In einem Menü, dessen Wurzeln sich unterschiedlich ausklappen, bleibt nur ein Abschnitt offen: Beim Wechsel auf eine Accordion-Wurzel wird das Panel der verlassenen Panel-Wurzel geschlossen, und umgekehrt. |
color | 'primary' | 'success' | 'danger' | 'warning' | 'info' | string | undefined | Semantischer Akzent für Hover-/Aktiv-Affordanzen. Akzeptiert einen semantischen Namen (primary, success, danger, warning, info), einen registrierten Akzentnamen, eine benannte CSS-Farbe oder ein literales #hex / rgb() / oklch() / var(). Einfache Namen werden auf das Token --hub-sys-color-<name> aufgelöst; ohne Angabe gilt primary. |
rail | boolean (two-way: model) | false | Nur-Desktop-Icon-Leiste. Bei true rendert eine vertikale Navigation in Leistenbreite und zeigt nur Icons. Unterhalb von collapseBreakpoint wird sie ignoriert; dort gewinnt immer das Offcanvas-Verhalten. Bidirektional bindbar über [(rail)]. |
activeItemId | string | null (two-way: model) | null | Der Eintrag, der als aktiv markiert wird — benannt über seine `id` oder sein `fragment` —, wenn nicht der Router sagt, wo der Leser ist. Solange gesetzt, antwortet er für das ganze Menü: der Routenabgleich tritt zurück, und der markierte Eintrag meldet `aria-current="location"` statt `page`. Beidseitig bindbar — so bewegt der Scroll-Spy die Markierung. |
orientation (config) | 'horizontal' | 'vertical' | 'horizontal' | Ausrichtung der Navigation: horizontal rendert eine obere Leiste, vertical rendert eine Sidebar. |
verticalExpandMode (config) | 'accordion' | 'flyout' | 'panel' | 'accordion' | Wie sich Unterelemente in vertikaler Ausrichtung ausklappen: accordion klappt inline aus, flyout öffnet ein positioniertes seitliches Untermenü, panel öffnet gestapelte Drill-down-Panels. |
dropdownTrigger (config) | 'hover' | 'click' | 'both' | 'click' | Mechanismus, der Dropdown-Menüs öffnet: bei hover, bei click oder beides. |
dropdownRenderMode (config) | 'inline' | 'overlay' | 'inline' | Rendering-Strategie für Dropdown- und Flyout-Menüs: inline innerhalb des Nav-DOM oder overlay in einer Ebene auf body-Höhe, um Abschneiden zu vermeiden. Der panel-Drill-down-Modus ist nicht betroffen. |
position (config) | 'static' | 'sticky' | 'fixed' | 'static' | CSS-Positionierungsstrategie für den Nav-Container. Sticky-Positionierung wird nur bei vertikaler Navigation aktiviert. |
stickyTop (config) | string | '0px' | Oberer Versatz bei aktivierter Sticky-Positionierung. Akzeptiert jeden gültigen CSS-Längenwert. |
collapseMode (config) | 'offcanvas' | 'dropdown' | 'fullscreen' | 'offcanvas' | Anzeigemodus, wenn das Menü auf kleinen Viewports einklappt: offcanvas als hereingleitender Drawer, dropdown unterhalb des Togglers oder fullscreen als Overlay. |
collapseBreakpoint (config) | number | 992 | Viewport-Breite in Pixeln, unterhalb derer das Menü einklappt. Auf 0 setzen, um das responsive Einklappen zu deaktivieren. |
offcanvasPosition (config) | 'start' | 'end' | 'top' | 'bottom' | 'start' | Seite, von der das offcanvas-Panel hereingleitet. Gilt nur, wenn collapseMode auf offcanvas steht. |
ariaLabel (config) | string | 'Navigation' | Zugängliche Beschriftung, die auf das Nav-Element angewendet wird. |
panelMaxVisible (config) | number | 3 | Maximale Anzahl gleichzeitig sichtbarer Panels im panel-Ausklappmodus. Darüber hinaus navigiert das letzte Panel an Ort und Stelle in die Tiefe, mit Zurück-Navigation. |
sidebarSide (config) | 'left' | 'right' | 'left' | Physische Seite der Sidebar: left (Panels erstrecken sich nach rechts) oder right (Panels erstrecken sich nach links). |
panelWidth (config) | string | '16rem' | Breite jedes Drill-down-Panels. Akzeptiert jeden gültigen CSS-Breitenwert. |
railToggle (config) | boolean | true | Ob der eingebaute Randumschalter auf der Primärspalte einer vertikalen Desktop-Navigation gerendert wird. Deaktivieren, wenn die App einen eigenen Umschalter liefert. Vollständig über die --hub-nav-rail-toggle-*-Tokens themebar, inklusive austauschbarem SVG-Pfeil. |
followReplacedUrls (config) | boolean | number | true | Wie bereitwillig die Navigation einem Scroll-Spy folgt, der die Leseposition per URL-Ersetzung meldet: true folgt jeder Meldung, eine Zahl in Millisekunden erst nach Ruhe, false nie. |
activeIndicator (config) | boolean | false | Ob sich die Aktiv-Markierung zwischen Elementen bewegt, statt an Ort und Stelle zu erscheinen. Standardmäßig aus; berücksichtigt prefers-reduced-motion. |
labels (config) | Partial<HubNavLabels> | undefined | Instanzweise Überschreibungen der eingebauten barrierefreien Beschriftungen. Ausgelassene Beschriftungen werden über die gemeinsamen HUBUI.NAV.*-Schlüssel und danach über die englischen Standardwerte aufgelöst. |
enabled (hubNavScrollSpy) — bound as [hubNavScrollSpy] | boolean | true | Aktiviert oder deaktiviert die Abschnittsverfolgung. Wird über den Selektor selbst gebunden: [hubNavScrollSpy]="false" schaltet den Spy ab. |
offset (hubNavScrollSpy) | number | 120 | Oberer Versatz in Pixeln, der Sticky-Header bei der Berechnung des aktiven Abschnitts kompensiert. |
sectionSelector (hubNavScrollSpy) | string | '[data-hub-nav-scroll-spy-section]' | CSS-Selektor, der verfolgbare Abschnittselemente innerhalb des Host-Containers lokalisiert. |
nav (hubNavScrollSpy) | HubNavComponent | null | null | Das Menü, für das dieser Spy antwortet. Gebunden fügen sich beide Hälften zusammen: der Abschnitt unter dem Leser markiert den passenden Eintrag, und ein Klick auf einen Eintrag scrollt hierher. Es wird keine URL geschrieben und kein Verlaufseintrag erzeugt. Ungebunden meldet der Spy nur über `activeSectionChange`. |
scrollContainer (hubNavScrollSpy) | HTMLElement | null | null | Das Element, in dem diese Abschnitte tatsächlich scrollen, wenn es nicht jenes ist, das der Spy beim Hochlaufen fände. Es ist auch das, was `scrollTo` bewegt — und genau das verhindert, dass ein Sprung jeden scrollbaren Vorfahren mitzieht. |
clickSettleMs (hubNavScrollSpy) | number | 0 | Wie lange, in Millisekunden, die Antwort eines Klicks überdauert, wenn der Leser scheinbar übernimmt. In diesem Fenster werden Rad, Berührung und Taste ignoriert, damit ein noch laufender Sprung nicht mitten in der Animation überstimmt wird. `0`, der Standard, behält das bisherige Verhalten. |
sectionId (hubNavScrollSpySection) | string | null | null | Optionale Abschnitts-id für einen verfolgten Abschnitt. Ohne Angabe wird das id-Attribut des Host-Elements verwendet. |
item (hub-nav-item)Erforderlich | HubNavItem | — | Das Navigationselement, das vom internen hub-nav-item-Kind gerendert wird. Wird automatisch von hub-nav verwaltet; selten direkt gebunden. |
depth / isActive / isExpanded / forceAccordionMode (hub-nav-item; depth and forceAccordionMode also on hub-nav-item-list) | number / boolean / boolean / boolean | 0 / false / false / false | Interne Zustands-Inputs von hub-nav-item: Verschachtelungstiefe, Aktiv- und Ausklapp-Flags sowie erzwungenes accordion-Verhalten in Mobil- oder Panel-Kontexten. hub-nav-item-list trägt depth und forceAccordionMode ebenfalls, sodass sich eine ganze Ebene auf einmal erzwingen lässt. |
items (hub-nav-item-list)Erforderlich | HubNavItem[] | — | Elemente, die vom internen hub-nav-item-list-Kind gerendert werden. Werden automatisch von hub-nav verwaltet. |
panels (hub-nav-panel-container)Erforderlich | HubNavPanelState[] | — | Stapel offener Panel-Zustände, der vom internen hub-nav-panel-container im panel-Ausklappmodus gerendert wird. |
panel (hub-nav-panel)Erforderlich | HubNavPanelState | — | Zustand eines einzelnen Drill-down-Panels, das vom internen hub-nav-panel-Kind gerendert wird. |
itemTemplate / dropdownRenderMode / panelWidth / sidebarSide / showHeader / hideFirstPanelHeader / isLast (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container) | TemplateRef<unknown> | null / HubNavDropdownRenderMode / string / HubNavSidebarSide / boolean / boolean / boolean | — | Interne Verdrahtungs-Inputs, die das Wurzel-hub-nav an seine Kinder weiterreicht; jeder existiert auf der Teilmenge dieser Komponenten, die ihn benötigt, und isLast markiert das äußerste Panel eines Stapels, damit es dessen Kante schließt. Diese über den config-Input auf hub-nav konfigurieren, statt sie direkt zu binden. |
overlayOwnerClass / overlayOrientationClass (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container) | string / 'hub-nav--horizontal' | 'hub-nav--vertical' | '' / 'hub-nav--vertical' ('hub-nav--horizontal' on hub-nav-item-list) | Overlay-Verdrahtung, die das Wurzel-hub-nav weiterreicht, wenn Untermenüs in einem Overlay auf Body-Ebene gerendert werden: overlayOwnerClass ist die eindeutige Klasse, die ein Overlay für die Außenklick-Behandlung seiner Navigation zuordnet, und overlayOrientationClass trägt die Ausrichtung der Navigation, damit die Host-Kontext-Styles auch außerhalb des Komponentenbaums greifen. |
Outputs
Reagiere darauf, was nav tut — 12 Events, an die du deine Logik anknüpfen kannst.
| Name | Typ | Beschreibung |
|---|---|---|
itemClick | OutputEmitterRef<HubNavItem> | Wird ausgelöst, wenn auf ein Link-Element geklickt wird. Liefert den angeklickten HubNavItem. |
dropdownOpen | OutputEmitterRef<HubNavItem> | Wird ausgelöst, wenn ein Dropdown-Element geöffnet wird. |
dropdownClose | OutputEmitterRef<HubNavItem> | Wird ausgelöst, wenn ein Dropdown-Element geschlossen wird. |
mobileToggle | OutputEmitterRef<boolean> | Wird ausgelöst, wenn das mobile Panel umgeschaltet wird. Liefert true beim Öffnen, false beim Schließen. |
panelChange | OutputEmitterRef<HubNavPanelEvent> | Wird ausgelöst, wenn ein Panel geöffnet, geschlossen, hineingezoomt oder zurücknavigiert wird. Liefert das Element, den Panel-Index und den Aktionstyp. |
railChange | OutputEmitterRef<boolean> | Wird ausgelöst, wenn der rail-Modellwert wechselt; ermöglicht die bidirektionale Bindung [(rail)] und app-seitige Persistenz. |
activeItemIdChange | OutputEmitterRef<string | null> | Wird ausgelöst, wenn sich der markierte Eintrag ändert — das macht `activeItemId` beidseitig bindbar. Ein über `[nav]` gebundener Scroll-Spy meldet hierüber den Abschnitt, auf dem er landet. |
activeSectionChange (hubNavScrollSpy) | OutputEmitterRef<string> | Gibt die id des neu aktiven Abschnitts aus, wann immer sich der sichtbare Abschnitt ändert. |
clicked / toggleDropdown (hub-nav-item) | OutputEmitterRef<{ item: HubNavItem; event: Event }> / OutputEmitterRef<HubNavItem> | Interne hub-nav-item-Ereignisse: clicked gibt das Element samt dem ursprünglichen DOM-Ereignis aus, toggleDropdown gibt das umgeschaltete Dropdown-Element aus. Beide werden bis zu den hub-nav-Outputs durchgereicht. |
itemClick / dropdownToggle / panelOpen (hub-nav-item-list / hub-nav-panel / hub-nav-panel-container) | OutputEmitterRef<{ item: HubNavItem; event: Event }> / OutputEmitterRef<HubNavItem> / OutputEmitterRef<HubNavItem> | Element-Interaktionsereignisse, die von den internen Listen- und Panel-Kindern auf dem Weg nach oben zu hub-nav erneut ausgegeben werden: itemClick (Element samt DOM-Ereignis), dropdownToggle (umgeschaltetes Element) und panelOpen (Element, dessen Kinder ein Panel öffnen sollen). |
closePanel / backClick (hub-nav-panel) | OutputEmitterRef<string> | Wird vom internen hub-nav-panel mit der Panel-id ausgelöst, wenn die Schließen-Schaltfläche (closePanel) oder die Zurück-Schaltfläche (backClick) gedrückt wird. |
panelClose / panelBack (hub-nav-panel-container) | OutputEmitterRef<string> | Wird vom internen hub-nav-panel-container mit der Panel-id ausgelöst und reicht Schließen- (panelClose) und Zurück-Anfragen (panelBack) an hub-nav weiter. |
Templates
Mach es zu deinem — 4 Template-Slots lassen dich eigenes Markup projizieren.
| Name | Beschreibung | Beispiel |
|---|---|---|
hubNavStart | Projiziert benutzerdefinierten Inhalt in den start-Slot. Horizontal: visueller Anfang (links bei LTR, rechts bei RTL). Vertikal: oben in der primären Spalte. | <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 | Projiziert benutzerdefinierten Inhalt in den end-Slot. Horizontal: visuelles Ende (rechts bei LTR, links bei RTL). Vertikal: unten in der primären Spalte. | <hub-nav [items]="items">
<ng-template hubNavEnd>
<button type="button">Sign out</button>
</ng-template>
</hub-nav> |
hubNavItemTemplate | Überschreibt das Standard-Rendern von Elementen durch ein benutzerdefiniertes Template. Erhält HubNavItemTemplateContext mit den Eigenschaften $implicit (item), active, expanded und depth. | <hub-nav [items]="items">
<ng-template hubNavItemTemplate let-item let-active="active">
<span [class.fw-bold]="active">{{ item.label }}</span>
@if (item.badge) { <hub-badge shape="rounded">{{ item.badge }}</hub-badge> }
</ng-template>
</hub-nav> |
hubNavItemIcon | Ersetzt die Glyphe jedes Eintrags, der icon deklariert, und sonst nichts. Erhält HubNavItemIconContext mit $implicit (dem Eintrag) und rail, sodass eine Navigation ihre Icons mit ng-hub-ui-icons – oder einem beliebigen anderen Paket – zeichnen kann, ohne dass die Bibliothek von einem abhängt. Einträge ohne icon bleiben unberührt. | <hub-nav [items]="items">
<ng-template hubNavItemIcon let-item let-rail="rail">
<hub-icon [name]="item.icon" [size]="rail ? 'lg' : 'md'" />
</ng-template>
</hub-nav> |