特殊元件

這份指南假設您熟悉路由在 PWA Kit 網店中的運作方式。若要深入瞭解,請參閱路由指南。

PWA Kit React SDK 包含以下特殊元件:AppConfigAppErrorDocument

每個特殊元件的預設實作可被您的自訂版本覆寫,這樣您就可以跨多個頁面設定、自訂網店的行為。

讓我們來看看每個特殊元件:

AppConfig 元件位置靠近 React 應用程式元件階層的頂端。從這個位置,此元件允許您插入程式碼來設定和支援整個應用程式的功能,例如狀態管理或元件主題設定。在 Retail React App 中,ChakraProvider 元件插入 AppConfig 中,以讓所有 Chakra UI 元件可使用主題值 (顏色、空間等)。

AppConfig 元件也讓您延伸傳遞給透過 getProps 函式、由 routeComponent 增強的所有元件的引數組合。若要新增這些引數,請將名為 extraGetPropsArgs 的函式定義為 AppConfig 元件的屬性。

Retail React App 使用 extraGetPropsArgs 函式,為透過 routeComponent 增強的所有元件授予對物件的存取權限,以便與 Salesforce Commerce API 互動:

PWA Kit React SDK 中 AppConfig 元件的版本沒有多少作用,除非您覆寫掉它。若要覆寫 AppConfig 的 SDK 版本,請在 app/_app-config/index.jsx 中定義一個檔案。新產生的 PWA Kit 專案已經包含這個檔案,讓您可開始使用。

App 元件是 AppConfig 元件的子代。其主要目的是包含 React 應用程式中持續存在的版面和 UI 元件,像是頁首、頁尾和側邊欄。

App 元件也透過 routeComponent 函式得到增強。如果將 getProps 函式定義為 App 元件的屬性,則在轉譯 routes 陣列中的_任何_元件時都會呼叫它。請將它用於您希望在每個頁面上執行的任何邏輯。

就像 AppConfig 一樣,PWA Kit React SDK 中存在 App 元件的預設版本,我們鼓勵您將之覆寫。若要覆寫 App 的 SDK 版本,請在 app/_app/index.jsx 中定義一個檔案。新產生的 PWA Kit 專案已經包含這個檔案,讓您可開始使用。

部分功能已在 App 中為新產生的專案實施,包括:分析追蹤、離線偵測和 SkipNavLink 無障礙存取元件。

在下列情況中,Error 元件會代替 App 元件出現:

  • 使用者要求一個在 routes 陣列中找不到的路徑。
  • routes 陣列的元件在其 getProps 函式中擲回錯誤。
  • routes 陣列的元件在轉譯時擲回錯誤。

傳回 Error 元件時,回應標頭也包含了 HTTP 404 狀態。

就像其他特殊元件一樣,PWA Kit React SDK 包含 Error 元件的預設版本,我們鼓勵您將之覆寫。若要覆寫 Error 的 SDK 版本,請在 app/_error/index.jsx 中定義一個檔案。新產生的 PWA Kit 專案已經包含這個檔案,讓您可開始使用。

透過覆寫 Error 元件,您可以進行許多工作,如自訂品牌錯誤頁面、新增重新導向,以及將錯誤視為分析事件來追蹤。

Document 元件定義了圍繞您的應用程式的 HTML,例如 <html><head><body> 標記。

就像其他特殊元件一樣,PWA Kit React SDK 包含 Document 元件的預設版本,可以加以覆寫。但是,在這種情況下,我們_不建議_您將之覆寫。但若您需要精密控制您的應用程式,可以在 app/_document/index.jsx 中定義一個檔案來覆寫 Document。新產生的 PWA Kit 專案將_不_包含這個檔案。

與其覆寫 Document 元件,我們建議使用 React Helmet 資產庫來修改 Document 中的 HTML 標記,如 <head>