SharePoint MegaMenu

Barrierearme, dreistufige Portalnavigation auf Basis von SharePoint Managed Metadata für SharePoint Server Subscription Edition und SharePoint Server 2019.

Eigenschaft	Wert
Version	1.1.1
SharePoint Framework	SPFx 1.4.1
Node.js	8.17.0
Zieloberfläche	Moderne SharePoint-Seiten
Paket	sharepoint/solution/mega-menu.sppkg

Funktionen

• Dreistufige Navigation aus einem Managed-Metadata-Termset
• Auswahl des Termsets per GUID oder, abwärtskompatibel, per Name
• Benutzerdefinierte Sortierung aus dem Term Store
• Unterstützung der Navigations-Eigenschaften _Sys_Nav_SimpleLinkUrl, _Sys_Nav_TargetUrl und _Sys_Nav_HoverText
• Auflösung von ~sitecollection in Navigations-URLs
• Markierung des aktuellen Menüpunktes und seiner übergeordneten Einträge
• Bedienung mit Maus, Tastatur und Touch
• Responsive Darstellung
• Optionales zusätzliches Stylesheet
• Taxonomy-Cache mit konfigurierbarer Ablaufzeit
• Bereinigter SPFx-Lifecycle ohne verbleibende globale Event Listener
• Deutsche und englische Statusmeldungen

Architektur

UserCustomAction.ClientSideComponentProperties
                  │
                  ▼
MegaMenuApplicationCustomizer
                  │
                  ├── TaxonomyNavigationService
                  │       └── SPTermStorePickerService
                  │               └── Default Site Collection Term Store
                  │
                  └── MegaMenuRenderer
                          ├── semantische Navigation
                          ├── Fokus- und Tastatursteuerung
                          └── responsive Darstellung

Das MegaMenu liest seine Laufzeitkonfiguration aus der site-scoped UserCustomAction. Es enthält keine eigene Administrationsoberfläche. Die zentrale Pflege soll über die separate Solution PortalSettings erfolgen.

Voraussetzungen

• SharePoint Server Subscription Edition oder SharePoint Server 2019
• konfigurierter App Catalog
• konfigurierter App Management Service
• ein Termset im Standard-Term-Store der Site Collection
• Leseberechtigung der Benutzer auf den Managed-Metadata-Service
• für Entwicklung und Build: Node.js 8.17.0 und eine zu SPFx 1.4.1 passende npm-Version

Konfiguration

Die UserCustomAction unterstützt folgende ClientSideComponentProperties:

{
  "termSetId": "6f36a1a8-7bd8-4ed0-a22f-e219f4d2eacc",
  "termSetName": "Global Navigation",
  "cacheMinutes": 15,
  "cssUrl": "/SiteAssets/megamenu/megamenu-custom.css",
  "debug": false
}

Eigenschaft	Typ	Standard	Beschreibung
termSetId	GUID	leer	Bevorzugte, eindeutige Identifikation des Termsets
termSetName	String	leer	Rückwärtskompatibler Fallback, wenn keine gültige termSetId vorhanden ist
cacheMinutes	Zahl	15	Gültigkeit des Session-Caches, zulässig sind 1 bis 1440 Minuten
cssUrl	String	leer	Relatives/same-origin Stylesheet oder externe HTTPS-Adresse
debug	Boolean	false	Aktiviert zusätzliche Konsolenausgaben

termSetId hat Vorrang vor termSetName. Für neue Installationen wird die GUID empfohlen, weil Termset-Namen nicht zwingend eindeutig sind.

Kompatibilität mit PortalSettings

Die bisherige PortalSettings-Version verwaltet termSetName, cssUrl und debug. Das MegaMenu 1.1.0 bleibt damit vollständig lauffähig und verwendet für nicht vorhandene cacheMinutes automatisch 15 Minuten.

Damit auch termSetId und cacheMinutes zentral bearbeitet werden können, muss das MegaMenu-Formular in PortalSettings um diese beiden Eigenschaften ergänzt werden. Bis dahin können sie über das Deployment-Skript gesetzt werden. Speichert eine ältere PortalSettings-Version anschließend erneut, werden die beiden noch unbekannten Eigenschaften entfernt; das MegaMenu fällt dann kontrolliert auf termSetName und den Standard-Cache zurück.

Termset-Aufbau

Die Darstellung unterstützt drei Ebenen:

Ebene 1: Hauptnavigation
├── Ebene 2: Kategorie
│   ├── Ebene 3: Link
│   └── Ebene 3: Link
└── Ebene 2: Kategorie

Für Zieladressen werden die lokalen benutzerdefinierten Eigenschaften des Terms ausgewertet:

1. _Sys_Nav_SimpleLinkUrl
2. _Sys_Nav_TargetUrl

Optional kann _Sys_Nav_HoverText als ergänzender Hilfetext verwendet werden. Veraltete Terms werden nicht angezeigt. Terms, die nicht für Tagging verfügbar sind, bleiben für Navigationsszenarien sichtbar.

Build

SPFx 1.4.1 verwendet die Legacy-Gulp-Toolchain. Neuere Node-Versionen sind nicht kompatibel.

npm install
npm run package

Alternativ einzeln:

gulp clean
gulp bundle --ship
gulp package-solution --ship

Das fertige Paket befindet sich anschließend unter:

sharepoint/solution/mega-menu.sppkg

Deployment

1. mega-menu.sppkg in den App Catalog laden.
2. Die Solution freigeben.
3. Die App im Root Web der gewünschten Site Collection installieren. Der MegaMenu Application Customizer wird dabei automatisch web-scoped registriert und von PortalSettings erkannt.
4. Das Termset in PortalSettings konfigurieren.

Das folgende Skript ist nur erforderlich, wenn ausdrücklich eine site-scoped Registrierung oder eine vollständig skriptbasierte Vorkonfiguration gewünscht ist.

Empfohlen mit Termset-GUID:

.\deployment\add-megamenu.ps1 `
  -SiteUrl 'https://sharepoint/sites/portal' `
  -TermSetId '6f36a1a8-7bd8-4ed0-a22f-e219f4d2eacc' `
  -TermSetName 'Global Navigation' `
  -CacheMinutes 15 `
  -CssUrl '/SiteAssets/megamenu/megamenu-custom.css'

Abwärtskompatibel nur mit Namen:

.\deployment\add-megamenu.ps1 `
  -SiteUrl 'https://sharepoint/sites/portal' `
  -TermSetName 'Global Navigation'

Das Skript entfernt ältere web-scoped Registrierungen derselben Komponente und erstellt beziehungsweise aktualisiert eine site-scoped UserCustomAction mit dem Description-Tag MSFT-Custom-Solution:MegaMenu. Dieses Tag wird von PortalSettings zur Erkennung verwendet.

Zusätzliches CSS

Zulässig sind:

• serverrelative oder relative Pfade derselben SharePoint-Origin,
• absolute URLs derselben Origin,
• externe URLs ausschließlich über HTTPS.

Nicht-HTTP(S)-Schemes und unverschlüsselte externe HTTP-Adressen werden zur Laufzeit verworfen.

Die wichtigsten CSS-Klassen sind:

#CustomNavigation { }
#Mega-Menu { }
.mega-menu-top-level { }
.mega-menu-top-item { }
.mega-menu { }
.mega-menu-grid { }
.mega-menu-category { }
.mega-menu-links { }

Viele Farben und Abstände können über CSS Custom Properties überschrieben werden, beispielsweise:

:root {
  --megaMenuNavBackground: #5f6f74;
  --megaMenuNavTextColor: #ffffff;
  --megaMenuPanelWidth: 1280px;
  --megaMenuZIndex: 6000;
}

Cache

Das geladene Termset wird im sessionStorage des Browsers gespeichert. Der Schlüssel ist mit MegaMenu:TermSet: namensräumlich getrennt. Nach Ablauf von cacheMinutes wird das Termset automatisch neu geladen.

Für einen sofortigen administrativen Test kann der Session-Cache in den Browser-Entwicklertools gelöscht oder ein neues privates Browserfenster verwendet werden.

Barrierefreiheit

• semantisches <nav aria-label="Hauptnavigation">
• native Listen- und Linksemantik
• aria-expanded und aria-haspopup für aufklappbare Einträge
• aria-current="page" für den aktuellen Navigationspfad
• Öffnen über Leertaste oder Pfeil nach unten
• Schließen über Escape
• sichtbare Fokusindikatoren
• Unterstützung von prefers-reduced-motion und kontrastreichen Darstellungen

Bewusst wird kein role="menubar" verwendet: Eine Portalnavigation ist eine normale Navigation und kein Desktop-Menü-Widget. Dadurch bleiben native Browser- und Screenreader-Erwartungen erhalten.

Fehlerdiagnose

„Die Navigation ist nicht konfiguriert“

Weder eine gültige termSetId noch ein termSetName ist gesetzt. UserCustomAction beziehungsweise PortalSettings-Konfiguration prüfen.

„Die Navigation konnte nicht geladen werden“

• Existiert das Termset im Standard-Term-Store der Site Collection?
• Ist die GUID korrekt?
• Haben Benutzer Zugriff auf den Managed-Metadata-Service?
• Enthält das Termset mindestens einen sichtbaren Term?
• Ist der App-Catalog-Eintrag aktuell?

Für weitere technische Details kann vorübergehend debug: true gesetzt werden.

Änderungen am Termset erscheinen verzögert

Die Navigation wird bis zu cacheMinutes im Session-Cache gehalten. Cache leeren oder Ablaufzeit abwarten.

Zusätzliches CSS wird nicht geladen

• URL und Dateiberechtigungen prüfen.
• Für externe Quellen HTTPS verwenden.
• Browser-Konsole bei aktiviertem Debug-Modus prüfen.

Upgrade von 1.0.x

• Bestehende termSetName-Konfigurationen funktionieren unverändert.
• Der alte unversionierte Session-Cache wird nicht weiterverwendet.
• cacheMinutes verwendet ohne Konfiguration den Wert 15.
• Die eigene, nicht verwendete MegaMenu-Einstellungsseite wurde entfernt; PortalSettings ist der zentrale Konfigurationsweg.
• Globale Event Listener werden beim Dispose der Extension entfernt.
• Paket-, npm- und Dokumentationsversion wurden auf 1.1.0 vereinheitlicht.

Classic Pages

Unter classic/ befindet sich eine separate Kompatibilitätsimplementierung für klassische SharePoint-Seiten. Sie wird nicht vom SPFx-Bundle ausgeführt und besitzt einen eigenen Deploymentweg. Neue Funktionen sollten zuerst in der modernen SPFx-Variante umgesetzt und anschließend bewusst in die Classic-Variante übernommen werden.

Projektstruktur

MegaMenu/
├── config/                         SPFx-Build- und Paketkonfiguration
├── deployment/                     Farm-/Site-Registrierung
├── src/
│   ├── extensions/megaMenu/        Application Customizer und Renderer
│   └── services/                    Taxonomy- und Datenmodelle
├── classic/                        optionale Classic-Kompatibilität
├── build-classic.ps1               Classic-Build
├── gulpfile.js
└── package.json

Versionshistorie

1.1.1

• automatische Registrierung des MegaMenu Application Customizers bei der App-Installation
• direkte Erkennung durch PortalSettings ohne vorherigen Skriptaufruf

1.1.0

• konsistente Verwendung des Default Site Collection Term Store
• optionale Konfiguration per Termset-GUID
• Cache-TTL und namensräumlich getrennter Session-Cache
• korrekte Anwendung der Deprecated-/Availability-Filter
• Prüfung der Taxonomy-HTTP-Antworten
• Lifecycle-Cleanup für globale Event Listener
• korrigierte Navigationssemantik und aktive Screenreader-Statusmeldungen
• Validierung externer CSS-URLs
• sichtbare Konfigurations- und Ladefehler
• Entfernung des ungenutzten lokalen Settings-Panels
• vereinheitlichte Projektversion und neue Build-/Deployment-Dokumentation