Zum Hauptinhalt springen

AppNav

In ChatGPT öffnen
Schatten dwc-app-nav dwc-app-nav-item 24.12
Java API

Die AppNav-Komponente erstellt ein seitliches Navigationsmenü aus AppNavItem-Einträgen. Elemente können auf interne Ansichten oder externe Ressourcen verlinken, unter übergeordneten Elementen für hierarchische Menüs geschachtelt werden und Icons, Abzeichen oder andere Komponenten mitführen, um den Benutzern auf einen Blick mehr Kontext zu geben.

Hinzufügen und Verschachteln von Elementen​

AppNavItem-Instanzen werden verwendet, um die AppNav-Struktur zu füllen. Diese Elemente können einfache Links oder Gruppenüberschriften sein, die untergeordnete Elemente enthalten. Gruppenüberschriften ohne Links fungieren als erweiterbare Container.

Verwenden Sie addItem(), um Elemente in die Navigation einzufügen:

AppNavItem dashboard = new AppNavItem("Dashboard", "/dashboard");
AppNavItem admin = new AppNavItem("Admin");
admin.addItem(new AppNavItem("Users", "/admin/users"));
admin.addItem(new AppNavItem("Settings", "/admin/settings"));

AppNav nav = new AppNav();
nav.addItem(dashboard);
nav.addItem(admin);
Gruppenartikel verlinken

Elemente der obersten Ebene in einem Navigationsbaum sind in der Regel nicht zum Klicken gedacht, sondern zum Erweitern. Das Setzen eines path auf solchen Elementen kann Benutzer verwirren, die erwarten, dass sie untergeordnete Elemente anzeigen, anstatt woanders zu navigieren.

Wenn Sie wünschen, dass die Gruppenüberschrift eine benutzerdefinierte Aktion (wie das Öffnen externer Dokumente) auslöst, lassen Sie den Gruppenpfad leer und fügen Sie stattdessen ein interaktives Steuerelement wie einen IconButton zum Suffix des Elements hinzu. Dies hält die Benutzererfahrung konsistent und klar.

Code anzeigen

Elemente verlinken​

Jedes AppNavItem kann zu einer internen Ansicht oder einem externen Link navigieren. Sie können dies mithilfe von statischen Pfaden oder registrierten Sichtklassen definieren.

Statische Pfade​

Verwenden Sie Zeichenfolgenpfade, um Links direkt zu definieren:

AppNavItem docs = new AppNavItem("Docs", "/docs");
AppNavItem help = new AppNavItem("Help", "https://support.example.com");

Registrierte Ansichten​

Wenn Ihre Ansichten beim Router registriert sind, können Sie anstelle einer fest codierten URL die Klasse übergeben:

AppNavItem settings = new AppNavItem("Settings", SettingsView.class);

Wenn Ihre annotierte Route Routenparameter unterstützt, können Sie auch eine ParametersBag übergeben:

ParametersBag params = ParametersBag.of("id=123");
AppNavItem advanced = new AppNavItem("User", UserView.class, params);

Mit Abfrageparametern​

Übergeben Sie eine ParametersBag, um Abfragezeichenfolgen einzuschließen:

ParametersBag params = ParametersBag.of("param1=value1&param2=value2");
AppNavItem advanced = new AppNavItem("Advanced", SettingsView.class, params);
advanced.setQueryParameters(params);

Zielverhalten​

Steuern Sie, wie Links geöffnet werden, mit setTarget(). Dies ist besonders nützlich für externe Links oder Pop-out-Ansichten.

  • SELF (Standard): Wird in der aktuellen Ansicht geöffnet.
  • BLANK: Wird in einem neuen Tab oder Fenster geöffnet.
  • PARENT: Wird im übergeordneten Browsing-Kontext geöffnet.
  • TOP: Wird im übergeordneten Browsing-Kontext der obersten Ebene geöffnet.
AppNavItem help = new AppNavItem("Help", "https://support.example.com");
help.setTarget(AppNavItem.NavigationTarget.BLANK);

Präfix und Suffix​

AppNavItem unterstützt Präfix- und Suffixkomponenten. Verwenden Sie diese, um visuelle Klarheit mit Icons, Abzeichen oder Buttons zu bieten.

  • Präfix: erscheint vor dem Label, nützlich für Icons.
  • Suffix: erscheint nach dem Label, großartig für Abzeichen oder Aktionen.
AppNavItem notifications = new AppNavItem("Alerts");
notifications.setPrefixComponent(TablerIcon.create("alert"));
notifications.setSuffixComponent(TablerIcon.create("link"));

Automatisches Öffnen von Gruppen​

Verwenden Sie setAutoOpen(true) an der AppNav-Komponente, um geschachtelte Gruppen automatisch zu erweitern, wenn die App aktualisiert wird.

nav.setAutoOpen(true);

Anheften 26.01​

Anheften ermöglicht es einem Benutzer, die Elemente, die er am häufigsten erreicht, in eine Gruppe oben in der Navigation zu heben, sodass ein tiefes Menü dennoch eine kurze Liste von Favoriten innerhalb eines Klicks behält. Es ist standardmäßig deaktiviert. Aktivieren Sie es über die Anheftkonfiguration:

AppNav nav = new AppNav();
nav.getPinning().setEnabled(true);

Sobald es aktiviert ist, zeigt jedes navigierbare Blattobjekt einen Anheft-Umschalter. Der Umschalter wird beim Hover und beim Tastaturfokus angezeigt, sodass er ohne Maus erreichbar bleibt. Durch Aktivieren wird das Element in die angeheftete Gruppe oben in der Navigation verschoben.

Einige Regeln bestimmen, was angeheftet werden kann und wie sich die Gruppe verhält:

  • Nur navigierbare Blattobjekte sind anheftbar. Gruppenüberschriften (Elemente mit Kindern) sind niemals anheftbar.
  • Die angeheftete Gruppe erscheint nur, wenn etwas angeheftet ist, und verschwindet wieder, wenn das letzte Element losgelöst wird.
  • Das Loslösen bringt ein Element an seine genaue ursprüngliche Position zurück, einschließlich Elemente, die sich mehrere Ebenen tief innerhalb von Gruppen befinden.
  • Das Element wird verschoben, nicht kopiert, sodass alle Präfix- oder Suffixinhalte und alle daran angehängten Listener weiterhin funktionieren, während es sich in der angehefteten Gruppe befindet.

Die folgende Demo hat das Anheften aktiviert mit einem benutzerdefinierten Gruppentitel und Dashboard, das beim Laden angeheftet ist. Bewegen Sie den Mauszeiger über oder fokussieren Sie ein Blattobjekt, um dessen Anheft-Umschalter zu zeigen.

Code anzeigen

Ein Element standardmäßig angeheftet starten​

Starten Sie ein Element in der angehefteten Gruppe, indem Sie seinen angehefteten Zustand festlegen. Verwenden Sie isPinned(), um den aktuellen Zustand zu lesen.

AppNavItem reports = new AppNavItem("Reports", "/reports");
reports.setPinned(true);
Anheften muss aktiviert sein

setPinned(true) hat nur dann Wirkung, wenn Anheften an der AppNav über getPinning().setEnabled(true) aktiviert ist. Ohne dies hat der Aufruf keine Wirkung.

Titel der angehefteten Gruppe​

Die angeheftete Gruppe wird standardmäßig mit Angeschnallt bezeichnet. Ändern Sie es, um zu Ihrem App zu passen:

nav.getPinning().setTitle("Favoriten");

Anheftschlüssel​

Jedes anheftbare Element trägt einen Schlüssel, der es zur Persistenz und für das Anheftereignis identifiziert. Wenn Sie keinen festlegen, fällt der Schlüssel auf den Pfad des Elements zurück, sodass getPinKey() immer einen verwendbaren Wert zurückgibt.

AppNavItem reports = new AppNavItem("Reports", "/reports");
reports.setPinKey("reports");

Setzen Sie einen expliziten Schlüssel, wenn der Pfad zur Laufzeit ändern kann. Ein stabiler Schlüssel hält einen Pin mit dem richtigen Element über Neuladevorgänge hinweg maschen, selbst wenn sich die URL verschiebt.

Automatische Speicherung im lokalen Speicher​

Pins leben nur für die aktuelle Seitenansicht, es sei denn, Sie persistieren sie. Automatische Speicherung ist die einfachste Option: sie speichert die Menge an angehefteten Elementen im lokalen Speicher des Browsers und stellt sie beim Neuladen wieder her. Sie ist standardmäßig deaktiviert. Sie benötigt eine stabile id (oder einen Namen) für die Komponente für den Speicher-Schlüssel, und der AppNav(String id)-Konstruktor ist der praktische Weg, einen festzulegen:

AppNav nav = new AppNav("main-nav"); // gibt der automatischen Speicherung einen stabilen Speicher-Schlüssel
nav.getPinning().setAutosave(true);
Automatische Speicherung benötigt eine id

Ohne id (oder Namen) an der Komponente tut die automatische Speicherung heimlich nichts, da es keinen stabilen Schlüssel zum Speichern gibt. Die Persistenz erfolgt pro Browser, sodass Pins den Benutzer nicht zu einem anderen Gerät oder Browser begleiten.

Benutzerdefinierte Persistenz​

Für Persistenz, die Sie steuern, zum Beispiel pro Benutzer auf dem Server, deaktivieren Sie die automatische Speicherung und steuern Sie es selbst über das Anheftereignis und setPinned:

nav.getPinning().setAutosave(false);

// speichern Sie die aktuelle Menge der angehefteten Schlüssel, wann immer sie geändert wird
nav.onPin(event -> savePins(event.getKeys()));

// beim Laden, stellen Sie jeden gespeicherten Schlüssel wieder her
restoredKeys.forEach(key -> findItem(key).setPinned(true));

Auf Anheftänderungen reagieren​

Das Anheftereignis wird immer dann ausgelöst, wenn ein Element angeheftet oder losgelöst wird. Es enthält das Element, das sich geändert hat, seinen Schlüssel, den neuen angehefteten Zustand und die vollständige geordnete Menge angehefteter Schlüssel:

nav.onPin(event -> {
  AppNavItem item = event.getItem(); // das Element, das sich verändert hat, oder null, wenn es nicht mehr in der Navigation vorhanden ist
  boolean pinned = event.isPinned();
  String key = event.getKey();
  List<String> all = event.getKeys(); // jeder angeheftete Schlüssel, in angehefteter Reihenfolge
});

getItem() löst das Element auf, indem es seinen Anheftschlüssel abgleicht und gibt null zurück, wenn das Element nicht mehr Teil der Navigation ist.

Anheftsymbole​

Der Umschalter verwendet das integrierte dwc:pin-Symbol, während ein Element nicht angeheftet ist, und dwc:pinned-off, während es angeheftet ist. Tauschen Sie Ihr eigenes durch setUnpinnedIcon und setPinnedIcon aus, die jede IconDefinition akzeptieren:

nav.getPinning()
   .setUnpinnedIcon(TablerIcon.create("pin"))
   .setPinnedIcon(TablerIcon.create("pinned-off"));

Anheftumschalter auf Touchscreens​

Touchscreens haben keinen Hover, um das Pin zu offenbaren, sodass der Umschalter dort standardmäßig verborgen ist. Halten Sie ihn sichtbar und tippbar auf Touchscreens mit setTouchVisible(true):

nav.getPinning().setTouchVisible(true);

Das Suchfeld filtert das Menü nach Elementbezeichnung, während der Benutzer tippt. Es ist standardmäßig deaktiviert. Sie können es anzeigen und ihm einen Platzhalter über die Suchkonfiguration geben:

nav.getSearch().setFieldVisible(true);
nav.getSearch().setPlaceholder("Suchen");

Während der Benutzer tippt, filtert die Navigation die Elemente nach Bezeichnung, öffnet jede Gruppe, die einen Treffer enthält, und zeigt eine leere Nachricht, wenn nichts übereinstimmt. Angeheftete Verknüpfungen bleiben während der Suche sichtbar, sodass die Favoriten eines Benutzers auch während des Filterns innerhalb eines Klicks erreichbar bleiben.

Code anzeigen

Leere Nachricht​

Legen Sie die Nachricht fest, die angezeigt wird, wenn eine Suche keine Ergebnisse zurückgibt. Klarer Text wird als Text gerendert:

nav.getSearch().setEmptyMessage("Keine Elemente gefunden");

Blenden Sie das integrierte Feld aus und füttern Sie den Filter von einem eigenen Eingabefeld aus. Drücken Sie den aktuellen Begriff über setTerm:

nav.getSearch().setFieldVisible(false);

myField.onModify(event -> nav.getSearch().setTerm(event.getText()));

Um auf das zu reagieren, was der Benutzer im integrierten Feld eingibt, hören Sie auf das Suchereignis:

nav.onSearch(event -> log(event.getTerm()));

Stylisierung von AppNavItem​

Loading...