Angular Portal- und Overlay-Rendering | ng-hub-ui-portal
Angular Portal-Bibliothek zum dynamischen Rendern von Komponenten, Templates und Overlays außerhalb des aktuellen DOM-Baums mit Positionierungssteuerung.
Zuletzt aktualisiert 20.09.2026
Übersicht
Warum Teams nach dieser Bibliothek suchen
Diese Angular Portal-Bibliothek hilft dir, Inhalte in Overlays oder individuelle Container zu rendern und dabei Datenfluss und Angular-Integration vorhersehbar zu halten.
Installieren
npm install ng-hub-ui-portalSpringen zu
Ideal für
- Drawer
- schwebende Panels
- Overlay-Oberflächen
- dynamische Container
Über portal
ng-hub-ui-portal ist nützlich, wenn Angular-Oberflächen das Rendering vom aktuellen DOM-Baum entkoppeln müssen: Drawer, schwebende Panels, dynamische Container oder Overlay-basierte UI. Es gibt Teams eine sauberere Grundlage für projizierte Inhalte und positioniertes Rendering.
Funktionsleitfäden
Inhalts-Rendering
Unterstützung für das Rendern verschiedener Inhaltstypen (Component, TemplateRef, String) mit DatenInjektions- und Projektionsfähigkeiten.
Beispiele:
Komponenten-Rendering
Ein Portal mit einer Komponentenklasse öffnen und über die zurückgegebene Referenz auf die Instanz zugreifen.
Code
Import:
Template:
Component:
TemplateRef-Rendering
Ein ng-template als Portalinhalt rendern, wobei close und dismiss im Template-Kontext bereitstehen.
Code
Import:
Template:
Component:
String-Inhalt
Eine einfache Zeichenkette als Inhalt übergeben, für ein Portal mit nur einer Aussage.
Code
Import:
Template:
Component:
Datenübergabe
Daten über einen eigenen Injector an die Inhaltskomponente reichen und die Antwort aus dem Schließwert lesen.
Code
Import:
Template:
Component:
Öffnungsstrategien
Steuern Sie, wie Portale geöffnet werden: progressiver (gestapelter) oder exklusiver (Umschalt-) Modus.
Beispiele:
Progressives Öffnen (gestapelt)
Portale mit open() stapeln, eines über dem anderen, und den Service fragen, wie viele noch offen sind.
Code
Import:
Template:
Component:
Umschalten (exklusiv)
toggle() verwirft das Geöffnete, wartet, bis es verborgen ist, und zeigt erst dann das neue Portal.
Code
Import:
Template:
Component:
Ziel-Container
Bestimmen Sie, wohin das Portal-Fenster angehängt wird: standardmäßig der Body des Dokuments, oder jedes Element, das ein CSS-Selektor benennt oder das als HTMLElement übergeben wird.
Beispiele:
Eigener Container (alt)
Das Fenster in einen anderen Container schicken und über windowClass gestalten. Die Platzierung stammt aus dem CSS dieser Demo — die Bibliothek hängt an, sie positioniert nicht.
Configuración de Posicionamiento
Elementos de Referencia
Targets de Portal
Configuración Actual
Code
Import:
Template:
Component:
Overlay-Verwaltung
Solange ein Portal geöffnet ist, scrollt die Seite dahinter nicht mehr, der Fokus bleibt im obersten Fenster gefangen, und alles außerhalb wird mit aria-hidden markiert.
Beispiele:
Grundlegende Verwendung (alt)
Der Alltagsfall des Service: ein Portal öffnen, auf result warten und es mit einem Wert schließen.
Portal Controls
Content is rendered dynamically into the DOM (typically body) using the HubPortal service, completely detaching it from this component's DOM hierarchy while preserving Angular context.
Code
Import:
Template:
Component:
Interaktion
Schließen/Verwerfen Sie Portale mit Ergebnissen, Tastaturunterstützung und benutzerdefinierten Trigger-Selektoren.
Beispiele:
Content Projection
Den Inhalt mit headerSelector und footerSelector in Kopf, Rumpf und Fuß aufteilen.
Code
Import:
Template:
Component:
Komponenten-Rendering
Ein Portal mit einer Komponentenklasse öffnen und über die zurückgegebene Referenz auf die Instanz zugreifen.
Code
Import:
Template:
Component:
Lebenszyklus
Lifecycle-Hooks und Event-Abonnements für die Verwaltung des Portalzustands.
Beispiele:
Service & Injektion (alt)
Portale aus einem Service heraus steuern: Toasts, Dialoge und Drawer, dazu dismissAll, hasOpenPortals und activeInstances.
Gestión Programática de Portales
Notificaciones Toast
Modales Dinámicos
Overlays Complejos
Gestión Global
Estado del Sistema de Portales
Code
Import:
Template:
Component:
Progressives Öffnen (gestapelt)
Portale mit open() stapeln, eines über dem anderen, und den Service fragen, wie viele noch offen sind.
Code
Import:
Template:
Component:
Hauptfunktionen
Letzte Änderungen
Version 22.2.2 - 9/20/26, 12:00 AM
changed: The npm keywords declare ng-hub-ui, the family name somebody searching for the ecosystem types. Metadata only: no code, types or styles change.
Version 22.2.1 - 9/16/26, 12:00 AM
changed: Repository, issue and README links follow the move to the hub-env organization. Issues for every Hub UI package are now gathered in hub-env/hub-ui, and the repository and bugs fields of the manifest point at the new addresses. No code, types or styles change.
Version 22.2.0 - 9/8/26, 12:00 AM
fixed: HubPortal.open() with a plain string opened an empty dialog. Every other kind of content is split into the three slots the window destructures, header, body and footer, but the string path returned a single slot: the text landed in the header and the body arrived undefined, which Angular projects as nothing, so the reader saw a blank box. The string now goes into the body slot like everything else, and four specs pin it. Worth stating plainly, because the same defect behaved worse in ng-hub-ui-modal, where it also took the keyboard down with it: here Escape never stopped working, because this window arms its listeners in ngOnInit rather than at the tail of the entry transition.
changed: The body mark is hub-portal-open. The old portal-open claimed a name in the application namespace rather than in the library one, the same defect ng-hub-ui-utils retired from the bare [tooltip] attribute in 22.14.0, and nothing warns a host whose own .portal-open rule is silently joined by ours. Both classes are written for now, so a stylesheet matching the old name keeps working; portal-open is removed in 23.0.0. See BREAKING_CHANGES.md.
changed: scrollable is delivered by the dialog rather than by a class on the content component host. That host is only a query root: its children are handed to the window and the host itself never enters the document, so component-host-scrollable, and the only rule this library shipped for it, matched nothing and asking for scrollable did nothing at all. The option now reaches the dialog through portal-dialog-scrollable, which the window already set, and the stylesheet dresses that class: the content box is pinned and the body scrolls inside it, or, where the content brings no .portal-body of its own, the content box is what scrolls.
changed: The slot split is one documented function instead of three inline expressions. Both declared slots are taken out of the container before the body is captured, and the body is captured as a static array. The old code read the body between the two extractions and got away with it only because what it captured was the live childNodes list, which Angular snapshots later, once both markers are already gone: correct by accident, disagreeing with the Node[][] ContentRef declares, and going empty the moment the nodes are projected out. No behaviour changes, and a spec now guards the contract.
added: Both READMEs state where this library stands on server-side rendering. The honest answer is not verified: a portal window only exists after a gesture, so the site prerender, which is the running proof for the libraries that render markup on the page, never draws one.
Version 22.1.0 - 9/6/26, 12:00 AM
changed: Dropped the angular16 keyword from the package manifest. The peer range has required Angular 18 or newer since 22.0.1, so the keyword was advertising the package to exactly the searchers whose install it would refuse.
changed: HubPortalRef is generic, so opening a portal no longer costs you the types. HubPortal.open<C, R>() and toggle<C, R>() infer C from the class handed to them, which is what makes componentInstance the component instead of any, while R types the value that travels through close(), result and closed. Until now the README answered this with a hand-written cast that claims a type nobody checks. Both parameters default to any, but componentInstance narrows from any to C | void, so a call site that reached straight through it stops compiling: see BREAKING_CHANGES.md. content is now typed Type<C> | TemplateRef<any> | string, which is what the stack already accepted, and the whole shape mirrors what ng-hub-ui-modal settled on in 22.5.0. Dismiss reasons stay untyped on purpose, because they carry either an internal PortalDismissReasons value or whatever the consumer passed.
removed: Removed the unused BACKDROP_ATTRIBUTES constant, a commented-out import in portal-config.ts and two commented-out lines of an older toggle() implementation. None of it was reachable, and backdropClass, the option that constant named, is not part of HubPortalOptions, so leaving it in suggested a backdrop API the library does not have. No behaviour changes.
fixed: Escape now dismisses the portal, as the keyboard option has always promised. The option was declared, defaulted to true in HubPortalConfig and documented in the README and on the docs site, but no key listener existed anywhere in the library: the close button was the only way out of a focus-trapped role=dialog, which left keyboard and screen-reader users stuck and forced every consumer to wire their own listener inside the projected component. The window now rejects its result promise with PortalDismissReasons.ESC, the reason the library exported without ever emitting it, honours keyboard: false per portal, steps aside when another handler has already consumed the key, and reacts only in the window holding focus, so a stack dismisses one dialog at a time from the top.
fixed: scrollable was declared a string on the portal window while HubPortalOptions declares it a boolean. Nothing misbehaved, because the template only tests the input for truthiness and the option reaches it through the name-based setInput, which no compiler ever checks, so the two had been free to disagree since the input was written. They now agree, which is what stops the next reader from believing the window and passing a string.
deprecated: HubPortalModule is deprecated and will be removed in 23.0.0. Its whole body is providers: [HubPortal], and HubPortal is providedIn: root, so importing the module never enabled the service; it only added a redundant second instance in whichever injector declared the import, delegating to the same root HubPortalStack and HubPortalConfig. Inject HubPortal and drop the import. The class carried no @deprecated tag until now, so neither an editor nor the build could warn anyone it was on its way out. See BREAKING_CHANGES.md.
Version 22.0.5 - 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. It is the link a registry shows beside the package and the one a reader clicks from it, and landing on a front page they then have to search is a worse answer than landing on the reference for the package they were already looking at. Metadata only — no code, no types, no styles change, and nothing a consumer imports is affected.
Version 22.0.4 - 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.0.3 - 7/28/26, 12:00 AM
fixed: Removed the invalid aria-portal attribute from the portal window host (not a real ARIA attribute); role=dialog and the aria-labelledby/describedby wiring stay.
Version 22.0.2 - 7/26/26, 12:00 AM
fixed: Declared the real ng-hub-ui-utils peer range (>=22.0.0); the previous >=1.0.0 floor allowed resolving an incompatible utils major.
Version 22.0.1 - 6/26/26, 12:00 AM
fixed: Corrected the Angular peer dependency range to >=18.0.0. The library uses APIs introduced in Angular 17 (signal input()/output(), the @if control flow and signal queries), so the previous >=16.0.0 range let it install on versions it cannot run on.
fixed: Corrected the ng-hub-ui-utils peer range. The previous caret range resolved to >=1 <2, which excluded the current utils (22.x) and made the peer impossible to satisfy.
Version 22.0.0 - 6/17/26, 12:00 AM
changed: Aligned with Angular 22.
changed: README documentation standardized.
Version 0.3.4 - 6/14/26, 12:00 AM
fixed: Portal window options (animation, windowClass, portalDialogClass, …) are applied through ComponentRef.setInput instead of being assigned onto the instance. Since HubPortalWindow declares them as signal inputs, the direct assignment replaced the read-only signal function and threw TypeError: ctx.animation is not a function on every open().
fixed: Guarded parentNode when removing the window element during teardown, which threw when the element had already been detached.
Verwandte Bibliotheken
Häufig gestellte Fragen
Wofür ist ng-hub-ui-portal gedacht?
Dafür, eine Komponente, ein TemplateRef oder einen einfachen String aus dem Code heraus an einer anderen Stelle im DOM einzuhängen. Injizieren Sie HubPortal, rufen Sie open() auf, und Sie bekommen ein HubPortalRef, dessen result ein Promise ist: Es löst mit dem auf, was Sie an close() geben, und lehnt mit dem Grund ab, den Sie dismiss() übergeben; closed, dismissed, shown und hidden sind die Observable-Entsprechungen. Im Inhalt injizieren Sie HubActivePortal, um von innen zu schließen, ohne eine Referenz auf den Aufrufer zu halten.
Wie lege ich fest, wo der Inhalt eingehängt wird?
Die Option container nimmt einen CSS-Selektor als String oder ein HTMLElement und steht standardmäßig auf document.body. Sie wird genau einmal aufgelöst, im Moment des open()-Aufrufs, das Ziel muss also bereits im Dokument stehen: Trifft der Selektor auf nichts, wirft der Aufruf einen Fehler, statt zu warten. Der Inhalt wird am Ende dieses Containers angehängt, und windowClass, portalDialogClass und portalContentClass sind die Haken für Ihr eigenes Styling.
Was ist der Unterschied zwischen portal und ng-hub-ui-modal?
ng-hub-ui-modal ist der Dialog, mit Backdrop, Stapelung, Größen und Platzierung bereits entschieden. Portal ist der Einhängemechanismus ohne diese Vorgaben: Es zeichnet keinen Backdrop und wendet keine Positionierung an, wie es aussieht, schreiben also Sie. Es umschließt den Inhalt aber in einem eigenen Fenster mit role=dialog, und es kümmert sich weiterhin um Escape über die Option keyboard, um den Fokus beim Öffnen und seine Wiederherstellung beim Schließen, um beforeDismiss als Guard und darum, den Rest der Seite vor assistiven Technologien zu verbergen.
Kann ich es deklarativ im Template verwenden, wie beim Angular CDK?
Nein. Es gibt weder eine Direktive noch ein Outlet: Die öffentliche Oberfläche sind der Service HubPortal, sein Ref und das Options-Objekt. Zwei Folgen sind abzuwägen. Inputs werden durch Zuweisung an componentInstance gesetzt, nicht über setInput, eine auf Signal Inputs gebaute Komponente wird also nicht so versorgt, wie Sie es erwarten würden. Und open() greift sofort auf document zu, es gehört also in den Browser: Server-Side Rendering ist nicht verifiziert, und der Aufruf braucht einen Guard von Ihnen.