@rei-standard/amsg-sw 1.2.1 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -10
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,12 +1,16 @@
|
|
|
1
1
|
# @rei-standard/amsg-sw
|
|
2
2
|
|
|
3
|
-
`@rei-standard/amsg-sw` 是 ReiStandard 主动消息标准的 Service Worker
|
|
3
|
+
`@rei-standard/amsg-sw` 是 ReiStandard 主动消息标准的 Service Worker 插件包，目标是让推送展示和离线重试“开箱即用”。
|
|
4
4
|
|
|
5
|
-
## 文档导航
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
-
|
|
6
|
+
## 功能概览
|
|
7
|
+
|
|
8
|
+
- 处理 `push` 事件：自动解析 payload 并展示通知
|
|
9
|
+
- 处理 `message` 事件：支持离线请求入队与主动冲刷队列
|
|
10
|
+
- 处理 `sync` 事件：在网络恢复后自动重试队列请求
|
|
11
|
+
- 使用 IndexedDB 存储待发送请求，避免页面关闭后丢失
|
|
12
|
+
|
|
13
|
+
> 注意：插件默认**不内置** `notificationclick` 逻辑，点击跳转策略由业务自行实现。
|
|
10
14
|
|
|
11
15
|
## 安装
|
|
12
16
|
|
|
@@ -14,7 +18,7 @@
|
|
|
14
18
|
npm install @rei-standard/amsg-sw
|
|
15
19
|
```
|
|
16
20
|
|
|
17
|
-
##
|
|
21
|
+
## 快速使用
|
|
18
22
|
|
|
19
23
|
```js
|
|
20
24
|
import { installReiSW } from '@rei-standard/amsg-sw';
|
|
@@ -23,14 +27,106 @@ installReiSW(self, {
|
|
|
23
27
|
defaultIcon: '/icon-192x192.png',
|
|
24
28
|
defaultBadge: '/badge-72x72.png'
|
|
25
29
|
});
|
|
30
|
+
|
|
31
|
+
// 业务侧自行实现点击跳转
|
|
32
|
+
self.addEventListener('notificationclick', (event) => {
|
|
33
|
+
event.notification.close();
|
|
34
|
+
event.waitUntil(self.clients.openWindow('/'));
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
离线入队（可选）：
|
|
39
|
+
|
|
40
|
+
```js
|
|
41
|
+
import { REI_SW_MESSAGE_TYPE } from '@rei-standard/amsg-sw';
|
|
42
|
+
|
|
43
|
+
export async function enqueueRequestToSW(requestPayload) {
|
|
44
|
+
const registration = await navigator.serviceWorker.ready;
|
|
45
|
+
if (!registration.active) {
|
|
46
|
+
throw new Error('No active service worker');
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
return new Promise((resolve, reject) => {
|
|
50
|
+
const channel = new MessageChannel();
|
|
51
|
+
channel.port1.onmessage = (event) => {
|
|
52
|
+
const result = event.data || {};
|
|
53
|
+
if (result.ok) {
|
|
54
|
+
resolve(result);
|
|
55
|
+
} else {
|
|
56
|
+
reject(new Error(result.error || 'Queue request failed'));
|
|
57
|
+
}
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
registration.active.postMessage(
|
|
61
|
+
{
|
|
62
|
+
type: REI_SW_MESSAGE_TYPE.ENQUEUE_REQUEST,
|
|
63
|
+
request: requestPayload
|
|
64
|
+
},
|
|
65
|
+
[channel.port2]
|
|
66
|
+
);
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## 消息协议
|
|
72
|
+
|
|
73
|
+
- `REI_SW_MESSAGE_TYPE.ENQUEUE_REQUEST`：添加请求到 outbox，并立即尝试发送
|
|
74
|
+
- `REI_SW_MESSAGE_TYPE.FLUSH_QUEUE`：主动触发一次队列发送
|
|
75
|
+
- `REI_SW_MESSAGE_TYPE.QUEUE_RESULT`：SW 返回入队结果（`ok` / `error` / `queueId`）
|
|
76
|
+
|
|
77
|
+
`request` 结构示例：
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"url": "/api/v1/schedule-message",
|
|
82
|
+
"method": "POST",
|
|
83
|
+
"headers": {
|
|
84
|
+
"content-type": "application/json",
|
|
85
|
+
"x-user-id": "550e8400-e29b-41d4-a716-446655440000",
|
|
86
|
+
"x-payload-encrypted": "true",
|
|
87
|
+
"x-encryption-version": "1"
|
|
88
|
+
},
|
|
89
|
+
"body": {
|
|
90
|
+
"iv": "...",
|
|
91
|
+
"authTag": "...",
|
|
92
|
+
"encryptedData": "..."
|
|
93
|
+
}
|
|
94
|
+
}
|
|
26
95
|
```
|
|
27
96
|
|
|
28
|
-
|
|
97
|
+
## 导出 API（Exports）
|
|
29
98
|
|
|
30
99
|
- `installReiSW`
|
|
31
100
|
- `REI_SW_MESSAGE_TYPE`
|
|
32
101
|
|
|
33
|
-
|
|
102
|
+
`REI_SW_MESSAGE_TYPE` 包含：
|
|
103
|
+
|
|
104
|
+
- `ENQUEUE_REQUEST`
|
|
105
|
+
- `FLUSH_QUEUE`
|
|
106
|
+
- `QUEUE_RESULT`
|
|
107
|
+
|
|
108
|
+
## 模块格式与类型（ESM/CJS/Types）
|
|
109
|
+
|
|
110
|
+
- ESM：`import { installReiSW } from '@rei-standard/amsg-sw'`
|
|
111
|
+
- CJS：`const { installReiSW } = require('@rei-standard/amsg-sw')`
|
|
112
|
+
- 类型：包内提供 `types` 入口（`dist/index.d.ts`）
|
|
113
|
+
|
|
114
|
+
## 运行环境与要求
|
|
115
|
+
|
|
116
|
+
- Service Worker 环境
|
|
117
|
+
- 需支持 `indexedDB`
|
|
118
|
+
- Background Sync 不可用时会降级为手动冲刷队列
|
|
119
|
+
- 建议项目可对 SW 文件做模块打包（支持包名 import）
|
|
120
|
+
|
|
121
|
+
## 常见坑
|
|
122
|
+
|
|
123
|
+
1. 本包不会自动添加 `notificationclick`，必须业务侧实现。
|
|
124
|
+
2. SW 文件如果不能解析包名 import，需要改走手动接入模板。
|
|
125
|
+
3. 请求入队 body 必须可序列化（JSON）。
|
|
126
|
+
|
|
127
|
+
## 相关链接（绝对 URL）
|
|
34
128
|
|
|
35
|
-
-
|
|
36
|
-
-
|
|
129
|
+
- [SDK Workspace 总览](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/README.md)
|
|
130
|
+
- [Server 包 README](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/README.md)
|
|
131
|
+
- [Client 包 README](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/client/README.md)
|
|
132
|
+
- [Service Worker 规范（第 0 章）](https://github.com/Tosd0/ReiStandard/blob/main/standards/service-worker-specification.md)
|