Routing

Wenn ein Benutzer über Ihre Storefront-Domain eine Anfrage stellt, wird diese von einem Express.js-Handler namens render bearbeitet, der in pwa-kit-react-sdk/ssr/server/react-rendering definiert ist. Der Handler wählt daraufhin eine Komponente für das Rendering aus. Dieser Komponententyp wird als Route bezeichnet. Die für das Rendering verfügbaren Routen werden in routes in einem Array von Objekten namens app/routes.jsx definiert.

Das Routen-Array entspricht der von React Router definierten Routenkonfigurationsform. Jedes Objekt im routes-Array kann die folgenden Eigenschaften besitzen:

Schlüssel	Typ	Beschreibung	Referenzdokumente
path	Eine Zeichenfolge im Express-Stil, ein Array von Zeichenfolgen oder ein regulärer Ausdruck	Der Pfad, der mit dem Pfad der eingehenden Anfrage auf eine mögliche Übereinstimmung verglichen wird	React Router API → Route component → path
component	Funktion (importiert in `routes.jsx`)	Komponente, die gerendert wird, wenn Pfad und Anfrage übereinstimmen	React Router API → Route component → component
exact	Boolesch	Legt fest, ob der Pfad eine exakte Übereinstimmung sein muss oder nicht	React Router API → Route component → exact

Bei einem neu generierten Projekt sind für viele E-Commerce-Standardseiten wie Startseite, PLP und PDP bereits Objekte im routes-Array vorhanden.

Aber wie wählt Ihre React App die richtige Komponente für das Rendering einer bestimmten Anfrage aus? Wir verwenden die React Router-Bibliothek, um die Routenkonfigurationsobjekte im routes-Array sequentiell zu durchsuchen, bis eine mit dem angeforderten Pfad übereinstimmende path-Zeichenfolge gefunden wird.

React Router gibt Ihnen eine ganze Reihe von Optionen für die Konstruktion Ihrer path-Zeichenfolgen. Sie können für dieselbe Komponente mehr als einen Pfad angeben und mithilfe von regulären Ausdrücken einem bestimmten Muster folgende Pfade finden.

React Router wird in der Retail React App auch für die Implementierung der Navigation verwendet. So verwenden beispielsweise alle Hyperlinks die Link-Komponente von React Router. Mit anderen React Router-Komponenten erhalten Sie Zugriff auf den Browserverlauf, Abfrageparameter und mehr.

Näheres zur Verwendung von React Router finden Sie in der offiziellen Dokumentation. (Halten Sie sich an die Dokumentation für Version 5, da andere Versionen ein anderes Mustervergleichssystem verwenden.)

Jede im routes-Array spezifizierte Komponente wird automatisch durch die Funktion routeComponent, eine übergeordnete Komponente des PWA Kit React SDKs, erweitert. Die Grundklasse, die zur Erstellung von routeComponent verwendet wird, definiert mehrere statische Methoden, darunter zwei wichtige, die von Storefront-Entwicklern angepasst werden können: getProps und shouldGetProps.

Die getProps-Methode wird verwendet, um aus API-Anfragen abgerufene Daten über das props-Objekt an routeComponent zu liefern.

Wenn routeComponent eine Komponente aus dem routes-Array erweitert, sucht die Funktion in den Eigenschaften der Komponente nach einer Funktion namens getProps. Wenn Sie dort eine Funktion definieren, wird diese als Methode der erweiterten Komponente angezeigt. Sie müssen die Funktion nicht für jede Komponente des routes-Arrays definieren, nur für diejenigen, für die Sie vor dem Rendering Daten abrufen.

Von der von Ihnen definierten getProps-Funktion wird erwartet, dass sie ein Versprechen (auch Promise genannt) zurückgibt. Sobald dieses Versprechen erfüllt ist, wird sein aufgelöster Wert über das props-Objekt an die erweiterte Komponente weitergegeben, wenn diese gerendert wird.

Wenn eine Komponente aus dem routes-Array gerendert wird, wird für die getProps-Methode der Komponente ein einziges JavaScript-Objekt bereitgestellt. Je nach dem Rendering-Kontext besitzt dieses Objekt die folgenden Eigenschaften:

Schlüssel	Typ	Beschreibung	Verfügbarkeit	Weitere Informationen
`params`	Objekt	Enthält Objekteigenschaften, die den benannten Routenparametern in einer Routenzeichenfolge im Express-Stil entsprechen. Beispiel: Bei der Route `/user/:name` ist der Wert von `:name` im Anfragepfad als params.name verfügbar. Standardwert: `{}`.	Client- und Serverseite	Express API → Request → req.params
`req`	Objekt	Eine mit Express erweiterte Version des Node-Anfrageobjekts. Entspricht der HTTP-Anfrage mit Eigenschaften für die Abfrage-String, Parameter, Haupttext, HTTP-Headern und mehr.	nur Serverseite	Express API → Request
`res`	Objekt	Entspricht der HTTP-Antwort, die eine Express App auf eine HTTP-Anfrage sendet.	nur Serverseite	Express API → Response
`location`	String	Die URL der Anfrage.	Client- und serverseitig	Nicht Teil der Express API

Ab Version 3.0.0 haben wir eine neue Strategie zum Abrufen von Daten namens withReactQuery eingeführt, die Sie anstelle von getProps verwenden können.
Sie können withReactQuery und withLegacyGetProps gleichzeitig verwenden.
getProps und shouldGetProps wurden aus der Standardvorlage von Seiten der Retail React App entfernt, sind aber nicht veraltet. Die langfristige Unterstützung dieser Methoden bleibt bestehen.

Siehe Upgrade auf v3.

Für die Behandlung von Fehlern in einer getProps-Funktionen stehen Ihnen zwei Optionen zur Wahl.

Option 1: Sie können ein HTTPError-Objekt werfen, das aus pwa-kit-react-sdk/ssr/universal/errors importiert werden kann. Beim Werfen von HTTPError wird eine dedizierte Error-Komponente gerendert.

Option 2: Sie können mithilfe von Props die gerenderte Komponente über den Fehler informieren, damit diese Informationen in der benutzerdefinierten Fehlerbehandlungslogik verwendet werden können.

Hier ist ein Beispiel, in dem beide Fehlerbehandlungsansätze eingesetzt werden:

Das von getProps zurückgegebene Objekt wird serialisiert und über ein Objekt namens __PRELOADED_STATE__ in die Seitenquelle eingebettet.

Um die Größe des gerenderten HTML-Codes gering zu halten, sollten Sie sorgfältig auswählen, welche Daten in getProps zurückgeben werden sollen. Vermeiden Sie beispielsweise sofern möglich die Rückgabe der gesamten Antwort einer API-Anfrage.

Um die serverseitig gerenderte Version der Seite in Ihrem Browser als Vorschau anzuzeigen, hängen Sie der URL ?__server_only an. Dieser Abfrageparameter stoppt den Prozess der Hydration, sodass der Browser die Rendering-Aufgabe nicht übernimmt und die Seite nach dem serverseitigen Rendering unverändert bleibt. Um eine Pretty-Print-Version des __PRELOADED_STATE__-Objekts anzuzeigen, fügen Sie ?__server_only&__pretty_print zur Abfrage-String hinzu.

Wenn Benutzer während des clientseitigen Renderings zu nachfolgenden Seiten navigieren, wird die Seite sofort gerendert. Da das Rendering bereits erfolgen kann, während getProps noch Daten abruft, sollten Sie zur Handhabung von nicht definierten Props in Ihre Komponenten immer Bedingungscode einfügen. Vergessen Sie auch nicht, eine Platzhalter-Komponente (wie Skeleton aus Chakra UI) zu rendern, solange Props nicht definiert sind.

Auf der Client-Seite wird die render-Methode Ihrer Komponente aufgerufen, bevor und nachdem getProps aufgelöst wird. Verwenden Sie die an Ihre Komponente weitergeleitete isLoading-Prop, um zu entscheiden, ob ein Ladebildschirm gerendert werden soll.

Wenn mehrere HTTP-Anfragen in getProps erfolgen, versuchen Sie diese parallel zu gestalten. Können Sie sie nicht parallel gestalten, erwägen Sie, sie für das Rendering auf die Client-Seite zu verschieben.

Wenn Sie Daten nur auf der Client-Seite abrufen möchten, verwenden Sie in Ihrer Komponente React-Hooks anstelle von getProps.

Wenn Sie den gleichen Code für alle Routen ausführen möchten, können Sie eine getProps-Funktion definieren, die zur App-Komponente gehört. Dabei handelt es sich um eine der besonderen Komponenten. Besondere Komponenten werden verwendet, um Funktionen für mehrere Routen hinzuzufügen. Mehr über die App-Komponente und weitere Sonderkomponenten erfahren Sie in unserer Anleitung Besondere Komponenten.

Die shouldGetProps-Methode steuert, wann die getProps-Methode aufgerufen werden soll. Während des serverseitigen Renderings wird shouldGetProps nur ein einziges Mal aufgerufen. Während des clientseitigen Renderings wird diese Methode jedes Mal aufgerufen, wenn die React-Lebenszyklus-Methode componentDidUpdate aufgerufen wird.

Standardmäßig ruft getProps jedes Mal getProps auf, wenn sich der Wert von location.pathname ändert. Sie können dieses Standardverhalten für jede Komponente im routes-Array überschreiben, indem Sie Ihre eigene Funktion namens shouldGetProps als Eigenschaft der Komponente definieren. Sie können shouldGetProps so anpassen, dass diese Methode die Anfrage inspiziert und nur für bestimmte Anfragen getProps aufruft.

Sehen Sie sich die Werbeträgernummer näher an, um ein tieferes Verständnis zu entwickeln. Dies sind einige wichtige Dateien in der Retail React App, die Sie sich ansehen sollten:

app/routes.jsx: Demonstriert die Express-Stil-Syntax für den Pfadvergleich, einschließlich benannter Routenparameter.
app/pages/product-detail/index.jsx: Diese Beispielkomponente für die PDP enthält benutzerdefinierte Funktionen für sowohl getProps als auch shouldGetProps.
app/components/_app_config/index.jsx: Enthält umfangreichen Konfigurationscode und eine appweite getProps-Funktion.

Einen alternativen Routing-Ansatz finden Sie unter URL-Auflösung.

Vergessen Sie beim Durchlesen der PWA Kit-Dokumentation nicht die Architekturanleitung für die Retail React App.