路由

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

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

類型描述參考文件
pathExpress 樣式的字串、字串陣列或規則運算式此路徑與傳入要求路徑進行比較,尋求可能相符性React Router API → <Route> → path
component函式 (匯入 routes.jsx)若路徑符合要求,則會轉譯的元件React Router API → <Route> → component
exact布林決定路徑是否必須為精準相符React Router API → <Route> → 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 的基本類別定義了幾個靜態方法,包括網店開發人員可自訂的兩個重要方法:getPropsshouldGetProps

getProps

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 的一部分

處理錯誤

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

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

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

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

編寫 getProps 函式

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

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 範例元件包含 getPropsshouldGetProps 兩者的自訂函式。
  • app/components/_app_config/index.jsx:包含廣泛的設定程式碼和全應用程式的 getProps 函式。

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