跳到主要內容
版本：3.5.2

📦 plugin-pwa

Docusaurus 外掛程式，使用 Workbox 新增對 PWA 的支援。此外掛程式只在生產環境組建時產生 Service Worker，並允許您建立完全支援 PWA 的技術文件網站，具有離線和安裝支援。

安裝​

npm install --save @docusaurus/plugin-pwa

組態​

在 ./static/manifest.json 建立 PWA 清單。

使用極簡的 PWA 組態，修改 docusaurus.config.js，例如：

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        debug: true,
        offlineModeActivationStrategies: [
          'appInstalled',
          'standalone',
          'queryString',
        ],
        pwaHead: [
          {
            tagName: 'link',
            rel: 'icon',
            href: '/img/docusaurus.png',
          },
          {
            tagName: 'link',
            rel: 'manifest',
            href: '/manifest.json', // your PWA manifest
          },
          {
            tagName: 'meta',
            name: 'theme-color',
            content: 'rgb(37, 194, 160)',
          },
        ],
      },
    ],
  ],
};

漸進式網路應用程式​

已安裝 Service Worker 並不表示應用程式已變成 PWA。您需要至少納入一個 網頁應用程式清單，並在 <head> 中具備正確的標籤（選項 > pwaHead）。

佈署後，您可以使用 Lighthouse 對您的網站執行稽核。

如果想要更詳盡地了解您的網站成為 PWA 的必要條件，請參閱 PWA 清單。

安裝應用程式的支援​

如果您的瀏覽器支援，您應該可以將 Docusaurus 網站安裝為應用程式。

A screen recording of the installation process. A button appears in the address bar of the browser, which displays a dialog asking &quot;install this application?&quot; when clicked. After clicking the &quot;Install&quot; button, a new application is opened in the operating system, opening to the Docusaurus homepage.

備註

安裝應用程式需要 HTTPS 協定和有效的清單。

離線模式（預快取）​

我們透過使用 Service Worker 預快取，讓使用者可以離線瀏覽 Docusaurus 網站。

workbox-precaching 網頁說明了此構想。

Service Worker 的其中一項功能是在 Service Worker 安裝時，將一組檔案儲存至快取中。這通常稱為「預快取」，因為您是在 Service Worker 使用前快取內容。

這樣做的主要原因是，它讓開發人員可以控制快取，這表示他們可以決定檔案的快取時間和方式，並將其提供給瀏覽器，而不必透過網路，換句話說，可以藉此建立離線運作的網頁應用程式。

Workbox 透過簡化 API 和確保資產經過有效率的下載，讓預快取變得很輕鬆。

預設情況下，當網站安裝為應用程式時，會啟用離線模式。詳細資訊請參閱 offlineModeActivationStrategies 選項。

網站預先快取後，服務工作人員會為之後的訪談提供快取回應。當新的組建隨著新的服務工作人員部署時，新的服務工作人員會開始安裝並最終移動到等待狀態。在這個等待狀態中，會顯示重新載入彈出視窗，並請使用者重新載入頁面以取得新內容。在使用者清除應用程式快取或按一下彈出視窗上的重新載入按鈕之前，服務工作人員將繼續提供舊內容。

警告

離線模式/預先快取需要事先下載網站的所有靜態資源，並且可能會消耗不必要的頻寬。對於所有類型的網站，啟用它可能是個糟糕的點子。

選項​

debug​

  • 類型：布林值
  • 預設值：false

開啟 debug 模式

  • Workbox 記錄
  • 額外的 Docusaurus 記錄
  • 未最佳化的 SW 檔案輸出
  • 原始碼對應

offlineModeActivationStrategies​

  • 類型：('appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always')[]
  • 預設值：['appInstalled', 'queryString', 'standalone']

用於開啟離線模式的策略

  • appInstalled：針對已安裝網站做為應用程式的使用者啟用（不完全可靠）
  • standalone：針對以獨立執行方式執行應用程式的使用者啟用（通常安裝 PWA 之後會發生）
  • queryString：如果 queryString 包含 offlineMode=true 則啟用（便於 PWA 除錯）
  • mobile：針對行動裝置使用者啟用（width <= 996px）
  • saveData：針對 navigator.connection.saveData === true 的使用者啟用
  • always：針對所有使用者啟用
警告

請小心使用：有些使用者可能不喜歡被迫使用離線模式。

危險

無法以可靠的方式偵測頁面是否是以 PWA 形式呈現。

appinstalled 事件已 從規格中移除，而 navigator.getInstalledRelatedApps() API 僅在近期 Chrome 版本中獲得支援，且要求在明細檔中宣告 related_applications。

standalone 策略 是啟用離線模式（至少在執行已安裝的應用程式時）的理想後備方案。

injectManifestConfig​

Workbox 選項可傳遞至 workbox.injectManifest()。這使您能控制預先快取哪些資產，以及哪些資產可於離線時使用。

  • 類型：InjectManifestOptions
  • 預設值：{}
docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        injectManifestConfig: {
          manifestTransforms: [
            //...
          ],
          modifyURLPrefix: {
            //...
          },
          // We already add regular static assets (HTML, images...) to be available offline
          // You can add more files according to your needs
          globPatterns: ['**/*.{pdf,docx,xlsx}'],
          // ...
        },
      },
    ],
  ],
};

pwaHead​

  • 類型：({ tagName: string; [attributeName: string]: string })[]
  • 預設值：[]

包含 tagName，以及用於注入至 <head> 標籤中之屬性的鍵值配對的物件陣列。技術上來說，您可以透過此方式注入任何標頭標籤，但最佳用途是將標籤注入您的網站，以使其符合 PWA 規範。下方列出讓您的應用程式完全符合規範的標籤清單

export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        pwaHead: [
          {
            tagName: 'link',
            rel: 'icon',
            href: '/img/docusaurus.png',
          },
          {
            tagName: 'link',
            rel: 'manifest',
            href: '/manifest.json',
          },
          {
            tagName: 'meta',
            name: 'theme-color',
            content: 'rgb(37, 194, 160)',
          },
          {
            tagName: 'meta',
            name: 'apple-mobile-web-app-capable',
            content: 'yes',
          },
          {
            tagName: 'meta',
            name: 'apple-mobile-web-app-status-bar-style',
            content: '#000',
          },
          {
            tagName: 'link',
            rel: 'apple-touch-icon',
            href: '/img/docusaurus.png',
          },
          {
            tagName: 'link',
            rel: 'mask-icon',
            href: '/img/docusaurus.svg',
            color: 'rgb(37, 194, 160)',
          },
          {
            tagName: 'meta',
            name: 'msapplication-TileImage',
            content: '/img/docusaurus.png',
          },
          {
            tagName: 'meta',
            name: 'msapplication-TileColor',
            content: '#000',
          },
        ],
      },
    ],
  ],
};

swCustom​

  • 類型：字串 | undefined
  • 預設值：undefined

對於其他 Workbox 規則非常有用。您可以在這裡進行服務工作人員可執行之任何作業，並使用 workbox 函式庫的所有功能。由於此程式碼會轉譯，因此您可以在此使用現代化的 ES6+ 語法。

例如，要從外部路由快取檔案

import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';

// default fn export receiving some useful params
export default function swCustom(params) {
  const {
    debug, // :boolean
    offlineMode, // :boolean
  } = params;

  // Cache responses from external resources
  registerRoute((context) => {
    return [
      /graph\.facebook\.com\/.*\/picture/,
      /netlify\.com\/img/,
      /avatars1\.githubusercontent/,
    ].some((regex) => context.url.href.match(regex));
  }, new StaleWhileRevalidate());
}

模組應該具有預設函式輸出，並且會收到某些參數。

swRegister​

  • 類型：字串 | false
  • 預設值：'docusaurus-plugin-pwa/src/registerSW.js'

在 Docusaurus 應用程式之前新增一個項目，以便在應用程式執行前就進行註冊。預設 registerSW.js 檔案已足以進行簡易註冊。

傳遞 false 會完全停用註冊。

明細檔範例​

Docusaurus 網站明細檔可作為靈感

{
  "name": "Docusaurus",
  "short_name": "Docusaurus",
  "theme_color": "#2196f3",
  "background_color": "#424242",
  "display": "standalone",
  "scope": "./",
  "start_url": "./index.html",
  "related_applications": [
    {
      "platform": "webapp",
      "url": "https://docusaurus.dev.org.tw/manifest.json"
    }
  ],
  "icons": [
    {
      "src": "img/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "img/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

自訂重新載入快顯視窗​

當新的服務工作人員等待安裝時會呈現 @theme/PwaReloadPopup 組件，且我們建議使用者重新載入。您可以變動此組件並實作自己的 UI。它會收到一個 onReload 回呼作為 props，當點擊reload 按鈕時應呼叫它。這會告知服務工作人員安裝等待的服務工作人員並重新載入頁面。

預設主題包含重新載入快顯視窗實作，並使用 Infima Alerts。

A screen recording of the reload process. An alert box shows in the bottom right of the window, saying &quot;New content available&quot;. After clicking the &quot;Refresh&quot; button, the page&#39;s main heading changes from &quot;Introduction&quot; to &quot;PWA :))&quot;.

組件可以呈現 null，但不建議如此：使用者將沒有辦法取得最新內容。

編輯此頁面
最後更新在 由 Sébastien Lorber 更新