Skip to main content
Version: 3.0.1

📦 插件-PWA

Docusaurus 插件，用于使用 Workbox 添加 PWA 支持。此插件仅在生产构建中生成 Service Worker，并允许您创建完全符合 PWA 标准的文档站点，支持离线和安装功能。

安装​

npm install --save @docusaurus/plugin-pwa

配置​

在 ./static/manifest.json 创建一个 PWA manifest。

修改 docusaurus.config.js 使用最小的 PWA 配置，例如：

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)',
          },
        ],
      },
    ],
  ],
};

渐进式网络应用​

安装服务工作者不足以使您的应用程序成为PWA。您至少需要包含一个Web App Manifest并在 中具有正确的标签（选项 > pwaHead）。

部署后，您可以使用Lighthouse对您的网站进行审核。

有关您的网站成为PWA所需条件的更详尽列表，请参阅PWA清单

应用程序安装支持​

如果您的浏览器支持，您应该能够将Docusaurus站点安装为应用程序。

安装过程的屏幕录制。浏览器的地址栏中出现一个按钮，点击后会显示一个对话框，询问“安装此应用程序？”。点击“安装”按钮后，操作系统中会打开一个新应用程序，显示Docusaurus主页。

note

应用程序安装需要HTTPS协议和有效的清单。

离线模式（预缓存）​

我们通过使用service-worker预缓存，使用户能够离线浏览Docusaurus站点。

workbox-precaching 页面解释了这一概念：

服务工作者的一项功能是能够在安装服务工作者时将一组文件保存到缓存中。这通常被称为“预缓存”，因为您在使用服务工作者之前缓存内容。

这样做的主要原因是它让开发者能够控制缓存，这意味着他们可以决定文件何时以及被缓存多长时间，并且可以在不访问网络的情况下将其提供给浏览器，这意味着它可以用来创建可以离线工作的网络应用程序。

Workbox 通过简化 API 并确保资源高效下载，减轻了预缓存的许多繁重工作。

默认情况下，当站点作为应用程序安装时，离线模式是启用的。详情请参见offlineModeActivationStrategies选项。

在站点被预缓存之后，服务工作者将为后续访问提供缓存的响应。当新的构建与新的服务工作者一起部署时，新的服务工作者将开始安装并最终进入等待状态。在此等待状态期间，将显示重新加载弹出窗口，并要求用户重新加载页面以获取新内容。在用户清除应用程序缓存或点击弹出窗口上的reload按钮之前，服务工作者将继续提供旧内容。

warning

离线模式/预缓存需要提前下载网站的所有静态资源，可能会消耗不必要的带宽。对于所有类型的网站来说，激活它可能不是一个好主意。

选项​

debug​

  • 类型: boolean
  • 默认值：false

开启调试模式：

  • Workbox 日志
  • 额外的 Docusaurus 日志
  • 未优化的SW文件输出
  • 源映射

offlineModeActivationStrategies​

  • 类型: ('appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always')[]
  • 默认值: ['appInstalled', 'queryString', 'standalone']

用于开启离线模式的策略：

  • appInstalled: 为已将网站安装为应用程序的用户激活（并非100%可靠）
  • standalone: 当用户以独立模式运行应用程序时激活（通常在PWA安装后出现这种情况）
  • queryString: 如果queryString包含offlineMode=true则激活（方便PWA调试）
  • mobile: 为移动用户激活 (width <= 996px)
  • saveData: 当用户的 navigator.connection.saveData === true 时激活
  • always: 为所有用户激活
warning

请谨慎使用：有些用户可能不喜欢被迫使用离线模式。

danger

无法以可靠的方式检测页面是否作为PWA呈现。

appinstalled事件已从规范中移除，而navigator.getInstalledRelatedApps() API仅在最近的Chrome版本中受支持，并且需要在清单中声明related_applications。

standalone策略是一个很好的后备方案，用于激活离线模式（至少在运行已安装的应用程序时）。

injectManifestConfig​

Workbox options 传递给 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和键值对的对象数组，用于注入到 标签中的属性。从技术上讲，你可以通过这个注入任何头部标签，但理想情况下，它用于使你的网站符合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​

  • 类型: string | 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());
}

模块应该有一个default函数导出，并接收一些参数。

swRegister​

  • 类型：string | 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.io/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组件，并向用户建议重新加载。您可以swizzle此组件并实现自己的用户界面。它将接收一个onReload回调作为props，当点击reload按钮时应调用此回调。这将告诉服务工作者安装等待的服务工作者并重新加载页面。

默认主题包含重新加载弹出窗口的实现，并使用Infima Alerts。

重新加载过程的屏幕录制。窗口右下角显示一个警告框，内容为“新内容可用”。点击“刷新”按钮后，页面的主标题从“介绍”变为“PWA :))”。

您的组件可以渲染null，但不建议这样做：用户将无法获取最新内容。