Skip to content

Commit 4ae8a7d

Browse files
meteorlxymeteorlxy
committed
docs(plugin-pwa): add plugin reference (close #24)
1 parent 4523d2b commit 4ae8a7d

File tree

2 files changed

+318
-2
lines changed

2 files changed

+318
-2
lines changed

‎docs/reference/plugin/pwa.md

Lines changed: 159 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,161 @@
11
# pwa
22

3-
> TODO
3+
> @vuepress/plugin-pwa
4+
5+
Make your VuePress site a [Progressive Web Application (PWA)](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps).
6+
7+
This plugin uses [workbox-build](https://developers.google.com/web/tools/workbox/modules/workbox-build) to generate service worker file, and uses [register-service-worker](https://github.com/yyx990803/register-service-worker) to register service worker.
8+
9+
## Web App Manifests
10+
11+
To make your website fully compliant with PWA, you need to create a [Web app manifests](https://developer.mozilla.org/en-US/docs/Web/Manifest) file and set the icons, colors, etc. for your PWA.
12+
13+
You need to put your manifest file and icons into the [public files directory](../../guide/assets.md#public-files). In the following example, we assume that you are using the default public directory `.vuepress/public`.
14+
15+
1. Create manifest file
16+
17+
Typically `.vuepress/public/manifest.webmanifest`:
18+
19+
```json
20+
{
21+
"name": "VuePress",
22+
"short_name": "VuePress",
23+
"description": "Vue-powered Static Site Generator",
24+
"start_url": "/index.html",
25+
"display": "standalone",
26+
"background_color": "#fff",
27+
"theme_color": "#3eaf7c",
28+
"icons": [
29+
{
30+
"src": "/images/icons/android-chrome-192x192.png",
31+
"sizes": "192x192",
32+
"type": "image/png"
33+
},
34+
{
35+
"src": "/images/icons/android-chrome-384x384.png",
36+
"sizes": "384x384",
37+
"type": "image/png"
38+
}
39+
]
40+
}
41+
```
42+
43+
2. Generate PWA icons
44+
45+
To make your PWA more accessible, you need to generate some icons, and put them inside the public directory.
46+
47+
Make sure the path of icons matches the `icons` field in your manifest file:
48+
49+
- `.vuepress/public/images/icons/android-chrome-192x192.png`
50+
- `.vuepress/public/images/icons/android-chrome-384x384.png`
51+
52+
::: tip
53+
Some tools can help to do that. For example, [Favicon Generator](https://realfavicongenerator.net/) would help you to generate icons together with a sample manifest file.
54+
:::
55+
56+
3. Set tags in head
57+
58+
You also need to set some tags via [head](../config.md#head) option to [deploy the manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest#deploying_a_manifest_with_the_link_tag):
59+
60+
```js
61+
module.exports = {
62+
head: [
63+
['link', { rel: 'manifest', href: '/manifest.webmanifest' }],
64+
['meta', { name: 'theme-color', content: '#3eaf7c' }],
65+
// ...other tags
66+
]
67+
}
68+
```
69+
70+
## Options
71+
72+
This plugin accepts all parameters of workbox-build's [generateSW method](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.generateSW) in its options, except `globDirectory` and `swDest`.
73+
74+
For example, you can set `skipWaiting: true` to auto activate the new service worker once it is ready:
75+
76+
```js
77+
module.exports = {
78+
plugins: [
79+
[
80+
'@vuepress/pwa',
81+
{
82+
skipWaiting: true,
83+
},
84+
],
85+
],
86+
}
87+
```
88+
89+
But if you omit `skipWaiting` or set it to `false`, you have to activate the new service worker manually:
90+
91+
- For users, you can use our [pwa-popup](./pwa-popup.md) plugin together.
92+
- For developers, you can use our [composition API](#composition-api) to take control of the service worker behavior.
93+
94+
### serviceWorkerFilename
95+
96+
- Type: `string`
97+
98+
- Default: `'service-worker.js'`
99+
100+
- Details:
101+
102+
File path of the generated service worker file, which is relative to the [dest](../config.md#dest) directory.
103+
104+
The service worker file will only be generated in `build` mode.
105+
106+
## Composition API
107+
108+
### usePwaEvent
109+
110+
- Details:
111+
112+
Returns the event emitter of this plugin.
113+
114+
You can add listener function to events that provided by [register-service-worker](https://github.com/yyx990803/register-service-worker).
115+
116+
- Example:
117+
118+
```ts
119+
import { usePwaEvent } from '@vuepress/plugin-pwa/lib/composables'
120+
121+
export default {
122+
setup() {
123+
event = usePwaEvent()
124+
event.on('ready', (registration) => {
125+
console.log('Service worker is active.')
126+
})
127+
},
128+
}
129+
```
130+
131+
### useSkipWaiting
132+
133+
- Parameters:
134+
135+
| Parameter | Type | Description |
136+
| ------------ | --------------------------- | -------------------------------------------------------- |
137+
| registration | `ServiceWorkerRegistration` | The registration of the service worker you want activate |
138+
139+
- Details:
140+
141+
Call [skipWaiting()](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/skipWaiting) to activate the waiting service worker.
142+
143+
- Example:
144+
145+
```ts
146+
import {
147+
usePwaEvent,
148+
useSkipWaiting,
149+
} from '@vuepress/plugin-pwa/lib/composables'
150+
151+
export default {
152+
setup() {
153+
event = usePwaEvent()
154+
event.on('updated', (registration) => {
155+
console.log('The waiting service worker is available.')
156+
// activate the waiting service worker
157+
useSkipWaiting(registration)
158+
})
159+
},
160+
}
161+
```

‎docs/zh/reference/plugin/pwa.md

Lines changed: 159 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,161 @@
11
# pwa
22

3-
> TODO
3+
> @vuepress/plugin-pwa
4+
5+
使你的 VuePress 站点成为一个 [渐进式 Web 应用 (PWA)](https://developer.mozilla.org/zh-CN/docs/Web/Progressive_web_apps).
6+
7+
该插件使用 [workbox-build](https://developers.google.com/web/tools/workbox/modules/workbox-build) 来生成 Service Worker 文件，并通过 [register-service-worker](https://github.com/yyx990803/register-service-worker) 来注册 Service Worker 。
8+
9+
## Web App Manifests
10+
11+
为了使你的网站符合 PWA 的要求，你需要创建一个 [Web app manifests](https://developer.mozilla.org/zh-CN/docs/Web/Manifest) 文件，并且为你的 PWA 设置图标、颜色等信息。
12+
13+
你需要将你的 Manifest 文件和图标放置在 [Public 目录](../../guide/assets.md#public-文件) 下。在下述的示例中，我们假设你正在使用默认的 Public 目录 `.vuepress/public` 。
14+
15+
1. 创建 Manifest 文件
16+
17+
通常是 `.vuepress/public/manifest.webmanifest` ：
18+
19+
```json
20+
{
21+
"name": "VuePress",
22+
"short_name": "VuePress",
23+
"description": "Vue-powered Static Site Generator",
24+
"start_url": "/index.html",
25+
"display": "standalone",
26+
"background_color": "#fff",
27+
"theme_color": "#3eaf7c",
28+
"icons": [
29+
{
30+
"src": "/images/icons/android-chrome-192x192.png",
31+
"sizes": "192x192",
32+
"type": "image/png"
33+
},
34+
{
35+
"src": "/images/icons/android-chrome-384x384.png",
36+
"sizes": "384x384",
37+
"type": "image/png"
38+
}
39+
]
40+
}
41+
```
42+
43+
2. 生成 PWA 图标
44+
45+
为了提高你的 PWA 的可用性，你需要生成一些图标，并将它们放置在 Public 目录下。
46+
47+
确保图标的路径匹配 Manifest 文件中的 `icons` 字段：
48+
49+
- `.vuepress/public/images/icons/android-chrome-192x192.png`
50+
- `.vuepress/public/images/icons/android-chrome-384x384.png`
51+
52+
::: tip
53+
一些工具可以帮助你做这些事。比如 [Favicon Generator](https://realfavicongenerator.net/) 可以帮助你生成图片以及一个 Manifest 文件样例。
54+
:::
55+
56+
3. 设置 Head 中的标签
57+
58+
你还需要通过 [head](../config.md#head) 配置项来设置一些标签，用来 [部署你的 Manifest 文件](https://developer.mozilla.org/en-US/docs/Web/Manifest#deploying_a_manifest_with_the_link_tag) 。
59+
60+
```js
61+
module.exports = {
62+
head: [
63+
['link', { rel: 'manifest', href: '/manifest.webmanifest' }],
64+
['meta', { name: 'theme-color', content: '#3eaf7c' }],
65+
// ...其他标签
66+
]
67+
}
68+
```
69+
70+
## 配置项
71+
72+
该插件的配置项可以接收 workbox-build 中 [generateSW 方法](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.generateSW) 除了 `globDirectory` 和 `swDest` 以外的所有参数。
73+
74+
比如，你可以设置 `skipWaiting: true` ，这将在新的 Service Worker 就绪之后立即激活它：
75+
76+
```js
77+
module.exports = {
78+
plugins: [
79+
[
80+
'@vuepress/pwa',
81+
{
82+
skipWaiting: true,
83+
},
84+
],
85+
],
86+
}
87+
```
88+
89+
但是如果你不设置 `skipWaiting` 或设置为 `false` ，你就需要手动激活新的 Service Worker 。
90+
91+
- 对于用户，你可以配合我们提供的 [pwa-popup](./pwa-popup.md) 插件一起使用。
92+
- 对于开发者，你可以使用该插件提供的 [Composition API](#composition-api) 来控制 Service Worker 的行为。
93+
94+
### serviceWorkerFilename
95+
96+
- 类型： `string`
97+
98+
- 默认值： `'service-worker.js'`
99+
100+
- 详情：
101+
102+
生成的 Service Worker 文件路径，该路径是 [dest](../config.md#dest) 目录的相对路径。
103+
104+
Service Worker 文件只会在 `build` 模式下生成。
105+
106+
## Composition API
107+
108+
### usePwaEvent
109+
110+
- 详情：
111+
112+
返回该插件的 Event Emitter 。
113+
114+
你可以为 [register-service-worker](https://github.com/yyx990803/register-service-worker) 提供的事件添加事件监听器。
115+
116+
- 示例：
117+
118+
```ts
119+
import { usePwaEvent } from '@vuepress/plugin-pwa/lib/composables'
120+
121+
export default {
122+
setup() {
123+
event = usePwaEvent()
124+
event.on('ready', (registration) => {
125+
console.log('Service worker 已经生效。')
126+
})
127+
},
128+
}
129+
```
130+
131+
### useSkipWaiting
132+
133+
- 参数：
134+
135+
| 参数 | 类型 | 描述 |
136+
| ------------ | --------------------------- | ----------------------------------------- |
137+
| registration | `ServiceWorkerRegistration` | 你想要激活的 Service Worker 的 Registration |
138+
139+
- 详情：
140+
141+
调用 [skipWaiting()](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/skipWaiting) 来激活处于 Waiting 状态的 Service Worker 。
142+
143+
- 示例：
144+
145+
```ts
146+
import {
147+
usePwaEvent,
148+
useSkipWaiting,
149+
} from '@vuepress/plugin-pwa/lib/composables'
150+
151+
export default {
152+
setup() {
153+
event = usePwaEvent()
154+
event.on('updated', (registration) => {
155+
console.log('在 Waiting 状态的 Service Worker 已经就绪。')
156+
// 激活 Waiting 状态的 Service Worker
157+
useSkipWaiting(registration)
158+
})
159+
},
160+
}
161+
```

0 commit comments

Comments
 (0)