路由

當使用者在您的網店網域做出要求時，將會由 pwa-kit-react-sdk/ssr/server/react-rendering 所定義、名為 render 的 Express.js 處理常式進行處理。處理常式會選擇一個元件作為回應來轉譯。這類型的元件稱為路由。可用於轉譯的路由都定義在 app/routes.jsx 名為 routes 的物件陣列中。

路由陣列遵循由 React Router 定義的路由設定圖形。routes 陣列中的每個物件都可以具有以下屬性：

鍵類型描述參考文件
pathExpress 樣式的字串、字串陣列或規則運算式此路徑與傳入要求路徑進行比較，尋求可能相符性React Router API → Route component → path
component函式 (匯入 routes.jsx)若路徑符合要求，則會轉譯的元件React Router API → Route component → component
exact布林決定路徑是否必須為精準相符React Router API → Route component → exact

新產生的專案已在 routes 陣列中，包含許多標準電子商務頁面 (如首頁、PLP、PDP) 的物件。

但是您的 React 應用程式是如何為任一要求選擇正確的元件來轉譯的呢？我們使用 React Router 資產庫，依序搜尋 routes 陣列中的路由設定物件，直到找到符合要求路徑的 path 字串。

React Router 提供許多選項來架構您的 path 字串。您可以為同一個元件指定多個路徑，並使用規則運算式來比對遵循某一模式的路徑。

React Router 也用在整個 Retail React App 上來實現導覽。比方說，所有超連結都使用 React Router 的 Link 元件。React Router 提供其他元件，讓您可存取瀏覽器記錄、查詢參數及更多內容。

想進一步瞭解如何使用 React Router，請參閱官方文件。(請瀏覽該文件的第 5 版本，因為其他版本使用不同的模式比對系統。)

routes 陣列中指定的每個元件都由 routeComponent 函式自動增強，這是 PWA Kit React SDK 中的高階元件。用於架構 routeComponent 的基本類別定義了幾個靜態方法，包括網店開發人員可自訂的兩個重要方法：getProps 和 shouldGetProps。

getProps 方法可透過 props 物件，將從 API 要求擷取的資料提供給 routeComponent。

當 routeComponent 增強來自 routes 陣列的元件時，它會在元件的屬性中尋找名為 getProps 的函式。若您定義該處的函式，它就會作為增強元件的方法而揭露。您不必為 routes 陣列中的每個元件定義函式，只需定義在轉譯前擷取資料的元件就好。

您定義的 getProps 函式應會傳回 Promise。當 Promise 完成時，它的解析值會在元件被轉譯之際，透過 props 物件傳遞給增強的元件。

當來自 routes 陣列的元件經過轉譯，該元件的 getProps 方法將以單一 JavaScript 物件提供。此物件擁有以下屬性，根據轉譯內容而定：

鍵類型描述可用性更多資訊
params物件包含與 Express 樣式路由字串中已命名路由參數相對應的物件屬性。範例：若您擁有路由 /user/:name，則要求路徑中 :name 的值會是 params.name。預設值：{}。用戶端和伺服器端雙方Express API → Request → req.params
req物件由 Express 增強的 Node 要求物件的一個版本。代表 HTTP 要求和查詢字串、參數、內文、HTTP 標頭及其他屬性。僅限伺服器端Express API → Request
res物件代表 Express 應用程式在獲得 HTTP 要求時傳送的 HTTP 回應。僅限伺服器端Express API → Response
location字串要求的 URL。用戶端和伺服器端雙方非 Express API 的一部分
  • 從 v3.0.0 開始，我們增加了一種名為 withReactQuery 的新資料擷取策略，您可以使用它來取代 getProps。
  • 您可以同時使用 withReactQuery 和 withLegacyGetProps。
  • getProps 和 shouldGetProps 已從 Retail React App 頁面的預設範本中移除，但未棄用。對這些方法的長期支援仍然存在。

請參閱升級至 v3。

若要在 getProps 函式中處理錯誤，您有兩種選擇。

第一種選擇是擲出 HTTPError 物件，可從 pwa-kit-react-sdk/ssr/universal/errors 匯入。當您擲出 HTTPError 時，將會轉譯專屬的 Error 元件。

第二種選擇是使用 Props 來向轉譯元件通知有錯誤，以便在自訂的錯誤處理邏輯中使用。

以下是使用這兩種錯誤處理方法的範例：

由 getProps 傳回的物件經過序列化，並透過頁面來源中稱為 __PRELOADED_STATE__ 的物件嵌入至轉譯的 HTML。

為了縮小轉譯的 HTML 大小，請謹慎選擇要在 getProps 中傳回哪些資料。比方說，請盡可能避免傳回 API 要求的完整回應。

若要在瀏覽器上預覽在伺服器端轉譯的頁面版本，請將 ?__server_only 附加至 URL。這個查詢參數會停止 Hydration 流程，這樣瀏覽器就不會接手轉譯，而頁面也會在伺服器端轉譯後保持不變。若要檢視清楚整理的 __PRELOADED_STATE__ 物件版本，請新增 ?__server_only&__pretty_print 至查詢字串。

當使用者在用戶端轉譯期間前往後續頁面，這些頁面將會立即轉譯。因為轉譯可在 getProps 仍在擷取資料時進行，請記得在您的元件中編寫條件式程式碼來處理未定義的 Props。也請記得在 Props 為未定義時，轉譯預留位置元件 (像是 Chakra UI 的 Skeleton)。

在用戶端，元件的 render 方法會在 getProps 解析之前和之後被呼叫。使用傳遞至您元件的 isLoading Prop 來決定是否要轉譯正在載入的畫面。

在 getProps 中發出多個 HTTP 要求時，盡量使它們平行進行。若您無法讓它們平行進行，可考慮將這些要求移至用戶端轉譯。

如果您只想在用戶端擷取資料，請在元件中使用 React Hook，而不是 getProps。

如果您想為所有路由執行相同的程式碼，可以定義一個屬於 App 元件的 getProps 函式，這是一種特殊元件。特殊元件用於新增在多個路由之間共用的功能。若要深入瞭解應用程式元件和其他特殊元件，請參閱我們的特殊元件指南。

shouldGetProps 方法可控制呼叫 getProps 方法的時機。在伺服器端轉譯期間，shouldGetProps 僅會被呼叫一次。在用戶端轉譯期間，每當 React 週期方法 componentDidUpdate 被呼叫，此方法也會被呼叫。

根據預設，getProps 在每次 location.pathname 的值變更時，都會呼叫 getProps。您可以覆寫 routes 陣列中每個元件的預設行為，方法為將名為 shouldGetProps 的自訂函式定義為元件的屬性。您可以自訂 shouldGetProps 來檢查要求，並僅為特定要求呼叫 getProps。

查看原始程式碼，深入瞭解路由。以下是您可在 Retail React App 中檢查的幾個重要檔案：

  • app/routes.jsx：展示用於路徑比對的 Express 樣式語法，包括已命名路由參數。
  • app/pages/product-detail/index.jsx：此 PDP 範例元件包含 getProps 和 shouldGetProps 兩者的自訂函式。
  • app/components/_app_config/index.jsx：包含廣泛的設定程式碼和全應用程式的 getProps 函式。

如需替代的路由方法，請查看 URL 解析。

當您閱讀 PWA Kit 文件時，別錯過 Retail React App 的架構指南。