uni-webview-rpc 0.0.0-stage → 0.1.0
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/LICENSE +21 -0
- package/README.md +213 -2
- package/browser/uni-webview-rpc.js +979 -0
- package/browser/uni.webview.js +1 -0
- package/lib/auto.cjs +976 -0
- package/lib/context.cjs +181 -0
- package/lib/defaults.cjs +173 -0
- package/lib/h5.cjs +972 -0
- package/lib/host.cjs +937 -0
- package/lib/index.cjs +1170 -0
- package/lib/transports.cjs +436 -0
- package/package.json +81 -4
- package/src/auto.js +17 -0
- package/src/config.js +18 -0
- package/src/context.js +174 -0
- package/src/core.js +312 -0
- package/src/defaults.js +146 -0
- package/src/h5.js +350 -0
- package/src/host.js +99 -0
- package/src/index.js +16 -0
- package/src/protocol.js +210 -0
- package/src/transports/app.js +91 -0
- package/src/transports/h5.js +16 -0
- package/src/transports/index.js +69 -0
- package/src/transports/mp.js +90 -0
- package/src/transports/postmessage.js +106 -0
- package/types/index.d.ts +213 -0
- package/vendor/uni.webview.js +1 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ISee
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,214 @@
|
|
|
1
|
-
#
|
|
1
|
+
# uni-webview-rpc
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
零依赖的跨端 web-view **双向 Promise RPC**。`uni-app` 外壳(宿主)和被嵌入的 H5 网站引入同一个包后,两端 API 完全对称:任意一方 `call()` 都返回 Promise,对端 `register()` 的方法可以同步或 `async`,返回值和抛出的错误都会跨端还原成 `resolve` / `reject`。
|
|
4
|
+
|
|
5
|
+
一套协议,三种通道:
|
|
6
|
+
|
|
7
|
+
| 目标端 | 宿主 → H5 | H5 → 宿主 | 实时双向 |
|
|
8
|
+
| --- | --- | --- | --- |
|
|
9
|
+
| uni-app App | 子 webview `evalJS` 注入 | `uni.postMessage` | ✅ 原生实时 |
|
|
10
|
+
| uni-app H5 | `window.postMessage` + origin 白名单 | 同左 | ✅ 原生实时 |
|
|
11
|
+
| 微信小程序 | `wx.miniProgram.postMessage` | 同左 | ⚠️ 只在后退/销毁/分享/复制链接时攒批送达,只能降级 |
|
|
12
|
+
| 普通浏览器直开 | — | — | standalone 模式,API 仍在,`call()` 明确抛 `BRIDGE_UNAVAILABLE`,不影响网站 |
|
|
13
|
+
|
|
14
|
+
## 安装
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
yarn add uni-webview-rpc
|
|
18
|
+
# 或 npm install uni-webview-rpc
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
本地 monorepo 开发可直接用相对路径:
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{ "dependencies": { "uni-webview-rpc": "link:../packages/uni-webview-rpc" } }
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 宿主侧(uni-app)
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
import { createHostBridge } from 'uni-webview-rpc/host'
|
|
31
|
+
|
|
32
|
+
const host = createHostBridge({
|
|
33
|
+
site, // { id, origin, allowedOrigins, bridge: { uniWebviewPath } }
|
|
34
|
+
sessionId: 'session-123',
|
|
35
|
+
platform: 'h5', // 'app' | 'mp' | 'h5';不传则自动探测
|
|
36
|
+
getIframe: () => iframeRef.value, // H5 端
|
|
37
|
+
getWebview: () => currentWebview, // App 端(有 evalJS)
|
|
38
|
+
onLog: ({ dir, frame }) => console.log(dir, frame),
|
|
39
|
+
})
|
|
40
|
+
|
|
41
|
+
// 调 H5 注册的方法
|
|
42
|
+
const info = await host.call('page.getInfo')
|
|
43
|
+
await host.call('page.notify', { message: '来自外壳' })
|
|
44
|
+
|
|
45
|
+
// 注册方法给 H5 调
|
|
46
|
+
host.register('host.getToken', async () => ({ token: await readToken() }))
|
|
47
|
+
|
|
48
|
+
// 单向事件
|
|
49
|
+
host.emit('host/tick', { at: Date.now() })
|
|
50
|
+
host.on('page/ready', (p) => console.log(p))
|
|
51
|
+
|
|
52
|
+
// web-view 的 @message 事件直接喂进来
|
|
53
|
+
// <web-view @message="e => host.receive(e.detail.data)" />
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## H5 侧(被嵌入的网站)
|
|
57
|
+
|
|
58
|
+
**方式 A:一行 import,自动就绪**(推荐给 Vite / Webpack 项目)
|
|
59
|
+
|
|
60
|
+
```js
|
|
61
|
+
import 'uni-webview-rpc/auto' // 副作用入口,会挂 window.WebViewBridge
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**方式 B:`<script>` 静态引入**(无需构建工具,把 `browser/uni-webview-rpc.js` 复制到站点静态目录)
|
|
65
|
+
|
|
66
|
+
```html
|
|
67
|
+
<script src="/uni-webview-rpc.js"></script>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**方式 C:手动创建、完全定制**
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
import { createH5Bridge } from 'uni-webview-rpc/h5'
|
|
74
|
+
|
|
75
|
+
const bridge = createH5Bridge({
|
|
76
|
+
paramPrefix: '__myapp_', // URL 参数前缀,两端必须一致;默认是中性的 '__wvrpc_'
|
|
77
|
+
useDefaultHandlers: false, // 不要内置的 page.* 方法
|
|
78
|
+
autoProbe: false, // 关闭启动时对 host.getEnv 的主动探测
|
|
79
|
+
handlers: { 'page.getCart': async () => ({ count: 3 }) },
|
|
80
|
+
attachGlobals: true,
|
|
81
|
+
})
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
引入之后:
|
|
85
|
+
|
|
86
|
+
```js
|
|
87
|
+
const bridge = window.WebViewBridge
|
|
88
|
+
await bridge.ready()
|
|
89
|
+
|
|
90
|
+
// H5 → 宿主
|
|
91
|
+
const env = await bridge.call('host.getEnv')
|
|
92
|
+
await bridge.call('host.toast', { message: '来自网页' })
|
|
93
|
+
|
|
94
|
+
// 注册方法给宿主调
|
|
95
|
+
const off = bridge.register('page.getCart', async ({ uid }) => ({ list: await loadCart(uid) }))
|
|
96
|
+
|
|
97
|
+
// 事件
|
|
98
|
+
bridge.emit('page/routeChange', { path: location.hash })
|
|
99
|
+
bridge.on('host/network', ({ type }) => console.log(type))
|
|
100
|
+
|
|
101
|
+
// 错误与超时
|
|
102
|
+
try { await bridge.call('host.fail', {}, { timeout: 3000 }) }
|
|
103
|
+
catch (err) { console.log(err.code) } // HANDLER_ERROR / METHOD_NOT_FOUND / BRIDGE_TIMEOUT ...
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
> 主全局名是 `window.WebViewBridge`;`window.IseeBridge`、`window.__ISEE_BRIDGE_RECEIVE__`
|
|
107
|
+
> 以及 `IseeBridgeReady` / `IseeBridgeHostEnv` 事件都是 0.1.0 之前的历史兼容别名,
|
|
108
|
+
> 与中性主名指向同一个实例,老页面不必改名。详见「命名与升级兼容」。
|
|
109
|
+
|
|
110
|
+
## 生成站点 URL
|
|
111
|
+
|
|
112
|
+
H5 侧靠 URL 参数判断宿主类型与白名单,宿主用同一个函数拼 URL,两端不会漂移:
|
|
113
|
+
|
|
114
|
+
```js
|
|
115
|
+
import { buildSiteUrl } from 'uni-webview-rpc/context'
|
|
116
|
+
|
|
117
|
+
const url = buildSiteUrl(site, {
|
|
118
|
+
host: 'h5',
|
|
119
|
+
sessionId: 'session-123',
|
|
120
|
+
parentOrigin: location.origin, // H5 端必填,用于 postMessage origin 校验
|
|
121
|
+
})
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
参数一律放在 **hash 之前的 search**(hash 路由站点里 hash 被路由占用,绝不能碰)。
|
|
125
|
+
|
|
126
|
+
## 平台支持
|
|
127
|
+
|
|
128
|
+
两端都不必写平台判断,创建桥时按目标端自动选通道:
|
|
129
|
+
|
|
130
|
+
| 宿主 | 通道 | 实时双向 | 备注 |
|
|
131
|
+
|---|---|---|---|
|
|
132
|
+
| App(APP-PLUS) | `uni.postMessage` 上行 + `evalJS` 下行 | 是 | 原生通道,延迟 1 个 RTT |
|
|
133
|
+
| H5(iframe) | `window.postMessage` | 是 | 带 origin 白名单 |
|
|
134
|
+
| 微信小程序 | `wx.miniProgram.postMessage` | **否** | 只在后退 / 销毁 / 分享 / 复制链接时攒批送达 |
|
|
135
|
+
| 浏览器直接打开 | 无 | — | 桥停用,网站功能不受影响 |
|
|
136
|
+
|
|
137
|
+
本包**不内置任何中转服务**:App 与 H5 的通道都是 webview / 浏览器原生能力,不需要额外进程、数据库表或域名。所以:
|
|
138
|
+
|
|
139
|
+
- 只做 App + H5 的项目,站点配置里只需要 `bridge.uniWebviewPath`,运行时零网络请求;
|
|
140
|
+
- 小程序端 `call()` 会**立即** reject `BRIDGE_UNAVAILABLE`,绝不假装成功。要在小程序里做实时 RPC,只能自建中转(WebSocket 服务或轮询一张表),那属于业务侧的后端,不在本包范围内。
|
|
141
|
+
|
|
142
|
+
实际走的是哪条通道,看 `window.WebViewBridge.capabilities` 里的 `transport` / `realtime` / `unavailableReason`。
|
|
143
|
+
|
|
144
|
+
## API
|
|
145
|
+
|
|
146
|
+
两端共用的实例方法:
|
|
147
|
+
|
|
148
|
+
| 方法 | 说明 |
|
|
149
|
+
| --- | --- |
|
|
150
|
+
| `call(method, params?, { timeout? })` | 调用**对端**注册的方法,返回 Promise,默认超时 10s |
|
|
151
|
+
| `register(method, fn)` / `registerMany(map)` | 注册供对端调用的方法,可 `async`;返回取消函数 |
|
|
152
|
+
| `unregister` / `hasMethod` / `listMethods` | 管理方法表 |
|
|
153
|
+
| `emit(method, params?)` / `on` / `off` | 单向广播,无响应、不保证送达 |
|
|
154
|
+
| `ping(timeoutMs?)` | 探测对端在线 |
|
|
155
|
+
| `waitReady()`(宿主)/ `ready()`(H5) | 等握手;`call()` 内部已自动排队等 ready |
|
|
156
|
+
| `isReady` / `pendingCount` | 状态 |
|
|
157
|
+
| `destroy()` | 页面卸载时调用,清定时器并 reject 所有悬着的 Promise |
|
|
158
|
+
|
|
159
|
+
错误码:`BRIDGE_TIMEOUT`、`METHOD_NOT_FOUND`、`HANDLER_ERROR`、`BRIDGE_UNAVAILABLE`、`TRANSPORT_CLOSED`、`PAYLOAD_TOO_LARGE`、`PROTOCOL_ERROR`。
|
|
160
|
+
|
|
161
|
+
## 规则与限制
|
|
162
|
+
|
|
163
|
+
- `call()` 只能调**对端**注册的方法;自己注册的方法本地不会自动执行。`host.*` / `page.*` 只是命名约定。
|
|
164
|
+
- 返回值必须可 JSON 序列化;单帧上限 64KB。
|
|
165
|
+
- 同一时刻可以有多个并发请求,靠帧 `id` 配对,响应不会串;重复投递会被去重。
|
|
166
|
+
- H5 端 `postMessage` 做了 `event.source` + `event.origin` 白名单校验,首帧后自动锁定 origin。
|
|
167
|
+
- 小程序端没有实时通道,`call()` 立即抛 `BRIDGE_UNAVAILABLE`;App 端 H5 需要站点上放一份 `browser/uni.webview.js`(`__wvrpc_uniwebview__` 可改路径)。
|
|
168
|
+
|
|
169
|
+
## 命名与升级兼容
|
|
170
|
+
|
|
171
|
+
从 0.1.0 起所有默认值都是中性的,不带任何业务品牌:
|
|
172
|
+
|
|
173
|
+
| 用途 | 默认值 |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| 协议频道 `ch` | `webview.rpc` |
|
|
176
|
+
| URL 参数前缀 | `__wvrpc_`(如 `__wvrpc_host__`、`__wvrpc_session__`) |
|
|
177
|
+
| `uni.postMessage` 帧字段 | `__wvrpc_frame__` |
|
|
178
|
+
| 全局对象 / 接收函数 | `WebViewBridge` / `__WEBVIEW_BRIDGE_RECEIVE__` |
|
|
179
|
+
|
|
180
|
+
0.1.0 之前的值(`isee.bridge` / `__isee_` / `__isee_frame__` / `IseeBridge`)作为**兼容别名**保留,用于平滑升级已部署的页面:
|
|
181
|
+
|
|
182
|
+
- 解码时同时接受新旧频道与新旧帧字段,新版 H5 发出去的帧会双写两种字段名;
|
|
183
|
+
- `readH5Context()` 在新参数缺失时自动回退读旧前缀;
|
|
184
|
+
- 全局名与 ready / host-env 事件双写,中性名与旧名指向同一实例。
|
|
185
|
+
|
|
186
|
+
如果宿主升级后仍需打开**尚未升级**的旧网页,给 `buildSiteUrl()` 多传一个 `legacyParamPrefix`,它会把桥接参数再写一套旧前缀:
|
|
187
|
+
|
|
188
|
+
```js
|
|
189
|
+
buildSiteUrl(site, { host: 'app', legacyParamPrefix: '__isee_' })
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
等线上页面全部升级完就可以去掉这个选项。新项目不需要任何兼容配置;两端也可以用 `paramPrefix` / `config.channel` 完全自定义。
|
|
193
|
+
|
|
194
|
+
## 与已有库的关系
|
|
195
|
+
|
|
196
|
+
`penpal` / `postmate` / `comlink` / `birpc` 等解决的是 `window.postMessage` 或 Worker 的 Promise RPC,无法用于 uni-app App 的 `uni.postMessage + evalJS`,也绕不开微信小程序 `postMessage` 攒批的限制;`@dcloudio/uni-webview-js` 只是官方 H5 侧 SDK(提供导航和发消息,没有请求/响应配对、超时和错误回传)。本包把「同构 Promise 内核」和「各端 transport」一起封装,transport 是可插拔的,需要时也能把 penpal 之类的库接成新通道。
|
|
197
|
+
|
|
198
|
+
## 开发
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
yarn install # 只装 esbuild(构建期),运行时零依赖
|
|
202
|
+
yarn build # 生成 lib/*.cjs 与 browser/*
|
|
203
|
+
yarn test # node:test,覆盖协议、RPC、各 transport、浏览器 IIFE 产物
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
ESM 直接发布 `src/`,不二次打包;CJS 与浏览器 IIFE 由 esbuild 生成。
|
|
207
|
+
|
|
208
|
+
## 第三方代码
|
|
209
|
+
|
|
210
|
+
`browser/uni.webview.js`(源文件 `vendor/uni.webview.js`)是 DCloud uni-app 官方 web-view SDK 的原样副本,版权归 DCloud 所有,本包仅在构建时复制到 `browser/` 供 App 端 H5 动态加载;本包自身的 MIT 许可不覆盖该文件。若你的项目已引入该 SDK,可直接忽略 `browser/uni.webview.js`,并通过 `__wvrpc_uniwebview__` 参数指向自己的副本。
|
|
211
|
+
|
|
212
|
+
## License
|
|
213
|
+
|
|
214
|
+
MIT
|