跳到主要内容
版本:3.8.1

📦 plugin-pwa

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

安装

npm install --save @docusaurus/plugin-pwa

配置

./static/manifest.json 创建 PWA 清单

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

渐进式 Web 应用

仅仅安装了 Service Worker 并不足以使您的应用程序成为 PWA。您至少需要包含一个 Web 应用清单 并在 <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 被使用之前就缓存了内容。

这样做的主要原因是它使开发者能够控制缓存,这意味着他们可以决定何时以及缓存文件多久,以及在不通过网络的情况下将其提供给浏览器,这意味着它可以用于创建可以离线工作的 Web 应用程序。

Workbox 通过简化 API 和确保高效下载资产,大大减轻了预缓存的繁重工作。

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

网站预缓存后,Service Worker 将为后续访问提供缓存响应。当部署了新的构建和新的 Service Worker 时,新的 Service Worker 将开始安装并最终进入等待状态。在此等待状态期间,将显示一个重新加载弹出窗口,要求用户重新加载页面以获取新内容。除非用户清除应用程序缓存或点击弹出窗口上的 reload 按钮,否则 Service Worker 将继续提供旧内容。

警告

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

选项

debug

  • 类型:boolean
  • 默认值:false

打开调试模式

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

offlineModeActivationStrategies

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

用于开启离线模式的策略

  • appInstalled:为已将网站安装为应用程序的用户激活(并非 100% 可靠)
  • standalone:为以独立模式运行应用程序的用户激活(通常是 PWA 安装后的情况)
  • queryString:如果查询字符串包含 offlineMode=true 则激活(方便 PWA 调试)
  • mobile:为移动用户激活(宽度 <= 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> 标签中。从技术上讲,您可以通过它注入任何 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

  • 类型:string | undefined
  • 默认值:undefined

对于额外的 Workbox 规则很有用。您可以在此处执行 Service Worker 可以做的任何事情,并充分利用 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.org.cn/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"
}
]
}

自定义重新加载弹出窗口

当新的 Service Worker 正在等待安装时,会渲染 @theme/PwaReloadPopup 组件,我们建议用户重新加载。您可以 swizzle 此组件并实现自己的 UI。它将接收一个 onReload 回调作为 prop,该回调应在点击 reload 按钮时调用。这将告诉 Service Worker 安装等待的 Service Worker 并重新加载页面。

默认主题包含重新加载弹出窗口的实现,并使用 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,但不建议这样做:用户将无法获得最新内容。