mobile-web-bridge 0.1.4 → 0.1.5

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 CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  MWB 为 iOS 和 Android 的 Web 容器提供统一 JS API。原生通信由 DSBridge 3.x 完成。
4
4
 
5
- 当前版本为 `0.1.4`,与同一 Git Tag 下的 iOS/Android 源码配套。下方安装命令固定为 `0.1.4`;分发状态见 [版本说明](https://github.com/gaoxiao228/MobileWebBridge/blob/main/docs/versioning.md),需要本地构建时可按 [源码构建与安装](https://github.com/gaoxiao228/MobileWebBridge#从源码构建-js-sdk) 使用。
5
+ 当前版本为 `0.1.5`,与同一 Git Tag 下的 iOS/Android 源码配套。下方安装命令固定为 `0.1.5`;分发状态见 [版本说明](https://github.com/gaoxiao228/MobileWebBridge/blob/main/docs/versioning.md),需要本地构建时可按 [源码构建与安装](https://github.com/gaoxiao228/MobileWebBridge#从源码构建-js-sdk) 使用。
6
6
 
7
7
  正式仓库:[gaoxiao228/MobileWebBridge](https://github.com/gaoxiao228/MobileWebBridge)。建议固定精确版本;Git Tag 与 npm 分发标签独立,原生接入与支持范围见 [项目 README](https://github.com/gaoxiao228/MobileWebBridge#readme)。
8
8
 
@@ -10,7 +10,7 @@ MWB 为 iOS 和 Android 的 Web 容器提供统一 JS API。原生通信由 DSBr
10
10
 
11
11
  ```bash
12
12
  # 固定项目版本;原生端也使用配套版本。
13
- npm install mobile-web-bridge@0.1.4
13
+ npm install mobile-web-bridge@0.1.5
14
14
  ```
15
15
 
16
16
  ```ts
@@ -42,7 +42,7 @@ await mwb.setNavigationBarTheme({
42
42
 
43
43
  当前源码新增 `await mwb.basic.notifyPageReady()`(也可用根入口 `mwb.notifyPageReady()`),用于 H5 主动通知当前原生容器首屏准备完成。无需注册业务插件,重复调用幂等。成功表示原生接受通知,不代表宿主已完成展示。
44
44
 
45
- 此能力请配套使用 JS、iOS 和 Android `0.1.4`。此方法走文档身份网关,等待上限 30000ms;旧原生和普通浏览器明确失败。调用时机、原生回调和重载规则见 [接入说明](https://github.com/gaoxiao228/MobileWebBridge/blob/main/docs/page-lifecycle.md)。
45
+ 此能力请配套使用 JS、iOS 和 Android `0.1.5`。此方法走文档身份网关,等待上限 30000ms;旧原生和普通浏览器明确失败。调用时机、原生回调和重载规则见 [接入说明](https://github.com/gaoxiao228/MobileWebBridge/blob/main/docs/page-lifecycle.md)。
46
46
 
47
47
  ## 同步与异步调用
48
48
 
@@ -76,7 +76,7 @@ try {
76
76
 
77
77
  ### basic 异步方法
78
78
 
79
- 既有 21 个 basic 异步原生入口(例如 `toast`、`navigateTo`、`chooseImage`、`scanCode`)返回 `Promise<GenericAsyncResult<T>>`。成功为 `{errCode: 0, result?: T}`;失败拒绝 Promise,不应只在 `.then` 中检查 errCode。
79
+ 当前源码的 22 个 basic 异步原生入口(例如 `toast`、`navigateTo`、`redirectTo`、`chooseImage`、`scanCode`)返回 `Promise<GenericAsyncResult<T>>`。成功为 `{errCode: 0, result?: T}`;失败拒绝 Promise,不应只在 `.then` 中检查 errCode。
80
80
 
81
81
  ```ts
82
82
  import { mwb, MWBBridgeError } from "mobile-web-bridge";
@@ -97,11 +97,13 @@ Promise 完成仅表示该方法约定的操作完成:`navigateTo` 默认在
97
97
 
98
98
  当前 iOS 源码可传 `await mwb.navigateTo({ url: childURL, waitForReady: true })`,由 SDK 自动等待主文档加载及 WebKit 绘制准备后再发起原系统转场;无需 H5 报告 ready。参数默认 `false`,Android 应省略此参数。总等待 3000 ms,加载/绘制失败或超时拒绝为 `-1002`,源页离开或后台取消为 `-1005`,同源已有准备请求为 `-1004`,非布尔值为 `-1001`。源文档失效后旧回复丢弃。成功不表示动画结束或异步业务数据完成,详见 [iOS 接入说明](../MWB-iOS/README.md)。
99
99
 
100
+ 当前源码另新增 `redirectTo`,与 `mwb.basic.redirectTo` 共用函数:替换当前容器,返回时跳过旧页。两端可立即替换;`waitForReady` 仅 iOS 支持,Android 必须省略。旧页成功替换后会销毁,后续业务在目标页初始化,不依赖旧页成功回调继续运行;完整参数和平台边界见[页面打开与替换](https://github.com/gaoxiao228/MobileWebBridge/blob/main/docs/navigation.md)。此方法自 `0.1.5` 提供,需同步升级 JS 与原生 SDK。
101
+
100
102
  除新增 `notifyPageReady()` 外,既有 basic 异步调用没有统一超时及文档失效兜底;原生未回调时可能持续等待。业务添加等待超时只会停止自己的等待,不代表原生操作已取消;支付等操作尤其不能据超时推断业务失败或直接重试。
101
103
 
102
104
  ### 事件与自定义插件
103
105
 
104
- 18 个 JS 句柄/事件方法不属于上述 30 个原生入口。`onAppShow`、`registerHandler` 等注册方法立即返回,回调后续触发;`await mwb.onAppShow(handler)` 不会等待应用进入前台。使用对应 `off` / `unRegister` 方法解绑;插件 `.on()` 返回解绑函数。
106
+ 18 个 JS 句柄/事件方法不属于上述 31 个原生入口。`onAppShow`、`registerHandler` 等注册方法立即返回,回调后续触发;`await mwb.onAppShow(handler)` 不会等待应用进入前台。使用对应 `off` / `unRegister` 方法解绑;插件 `.on()` 返回解绑函数。
105
107
 
106
108
  通过 `defineNativePlugin` 声明的业务方法**只支持 `Promise<GenericAsyncResult<T>>`**。即便原生立即调用 `responder.success`,JS 仍应使用异步契约;不能声明普通对象返回值,也没有 `sync: true` 配置。`hasPlugin` 同样返回 Promise。
107
109
 
@@ -109,7 +111,7 @@ Promise 完成仅表示该方法约定的操作完成:`navigateTo` 默认在
109
111
 
110
112
  ## 插件组合与构建
111
113
 
112
- 当前源码默认提供 basic 的 49 个方法;已发布包为原有 48 个。源码分为 `container`、`device`、`media`、`storage` 四组;事件和 JS 句柄始终包含在 SDK 内。`basicPlugin` 为完整组合,`--plugins=basic` 可构建全量 basic;与旧分组混用时去重。原有 `createMWB(legacyPlugins)` 数组裁剪入口保留,只在 basic 下映射选中的方法。重复方法或覆盖 Core/事件入口的配置直接报错。
114
+ 当前源码默认提供 basic 的 50 个方法;已发布包为原有 48 个。源码分为 `container`、`device`、`media`、`storage` 四组;事件和 JS 句柄始终包含在 SDK 内。`basicPlugin` 为完整组合,`--plugins=basic` 可构建全量 basic;与旧分组混用时去重。原有 `createMWB(legacyPlugins)` 数组裁剪入口保留,只在 basic 下映射选中的方法。重复方法或覆盖 Core/事件入口的配置直接报错。
113
115
 
114
116
  ```bash
115
117
  pnpm install
@@ -150,7 +152,7 @@ if (await sdk.hasPlugin("network")) {
150
152
 
151
153
  调用参数、成功结果和事件只接受 JSON:拒绝循环、函数、undefined 字段、非有限数字、非普通对象或 getter/setter。省略参数按 null 处理;显式结果 null 保留。超时默认 30000ms,允许整数 1..120000ms,超时以 `MWBBridgeError(-1103)` 拒绝。缺插件/方法分别为 `-1100/-1101`,旧壳无网关为 `-1106`,完整错误表见接入文档。
152
154
 
153
- 名称采用 `[a-z][a-zA-Z0-9_]*`。插件名不得占用当前 49 个根方法、basic/version/hasPlugin、pluginSession/pluginInfo/invokePlugin/pluginEvent、dispatchEvent/backBtnPressed 或以下探测名。业务方法和事件禁止 `on/then/catch/finally/toJSON/inspect/constructor/prototype/__proto__`;`on` 专用于订阅。读取方法属性不发请求,Proxy 的 Promise/JSON/Symbol 探测不会调用原生。不要通过 `typeof sdk.network.someMethod` 判断原生是否支持该方法,原生才会根据标记方法返回 `-1101`。
155
+ 名称采用 `[a-z][a-zA-Z0-9_]*`。插件名不得占用当前 50 个根方法、basic/version/hasPlugin、pluginSession/pluginInfo/invokePlugin/pluginEvent、dispatchEvent/backBtnPressed 或以下探测名。业务方法和事件禁止 `on/then/catch/finally/toJSON/inspect/constructor/prototype/__proto__`;`on` 专用于订阅。读取方法属性不发请求,Proxy 的 Promise/JSON/Symbol 探测不会调用原生。不要通过 `typeof sdk.network.someMethod` 判断原生是否支持该方法,原生才会根据标记方法返回 `-1101`。
154
156
 
155
157
  ## 接口约定
156
158
 
@@ -1 +1 @@
1
- export declare const apiMethods: readonly ["notifyPageReady", "setEnableDebug", "openAppAuthorizeSetting", "toast", "getAppInfoSync", "setBadgeCount", "navigateTo", "navigateBack", "navigateBackToRoot", "openExternalBrowser", "setNavigationBarTheme", "getDeviceInfoSync", "getClipboardDataSync", "setClipboardData", "makePhoneCall", "getNetworkTypeSync", "getNotificationSwitchStatus", "cleanWebviewCache", "compressImage", "scanCode", "saveImageToPhotosAlbum", "chooseImage", "setStorageSync", "getStorageSync", "removeStorageSync", "clearStorageSync", "openFile", "exitApp", "checkRequestCameraPermissions", "convertImagePathToBase64", "openNativePage", "registerHandler", "unRegisterHandlers", "unRegisterHandler", "checkHandlerExist", "onNetworkStatusChange", "offNetworkStatusChange", "onAppShow", "offAppShow", "onAppHide", "offAppHide", "onRemoteNotificationReceive", "offRemoteNotificationReceive", "onPageShow", "offPageShow", "onPageHide", "offPageHide", "onBackBtnPressed", "offBackBtnPressed"];
1
+ export declare const apiMethods: readonly ["notifyPageReady", "setEnableDebug", "openAppAuthorizeSetting", "toast", "getAppInfoSync", "setBadgeCount", "navigateTo", "redirectTo", "navigateBack", "navigateBackToRoot", "openExternalBrowser", "setNavigationBarTheme", "getDeviceInfoSync", "getClipboardDataSync", "setClipboardData", "makePhoneCall", "getNetworkTypeSync", "getNotificationSwitchStatus", "cleanWebviewCache", "compressImage", "scanCode", "saveImageToPhotosAlbum", "chooseImage", "setStorageSync", "getStorageSync", "removeStorageSync", "clearStorageSync", "openFile", "exitApp", "checkRequestCameraPermissions", "convertImagePathToBase64", "openNativePage", "registerHandler", "unRegisterHandlers", "unRegisterHandler", "checkHandlerExist", "onNetworkStatusChange", "offNetworkStatusChange", "onAppShow", "offAppShow", "onAppHide", "offAppHide", "onRemoteNotificationReceive", "offRemoteNotificationReceive", "onPageShow", "offPageShow", "onPageHide", "offPageHide", "onBackBtnPressed", "offBackBtnPressed"];
package/dist/index.js CHANGED
@@ -222,7 +222,7 @@ var require_dsbridge = __commonJS({
222
222
  var import_dsbridge = __toESM(require_dsbridge(), 1);
223
223
 
224
224
  // src/types.ts
225
- var version = "0.1.4";
225
+ var version = "0.1.5";
226
226
 
227
227
  // src/eventHub.ts
228
228
  var hubs = /* @__PURE__ */ new WeakMap();
@@ -433,6 +433,7 @@ var apiMethods = [
433
433
  "getAppInfoSync",
434
434
  "setBadgeCount",
435
435
  "navigateTo",
436
+ "redirectTo",
436
437
  "navigateBack",
437
438
  "navigateBackToRoot",
438
439
  "openExternalBrowser",
@@ -708,6 +709,10 @@ var containerPlugin = {
708
709
  navigateTo(param) {
709
710
  return callAsync("navigateTo", param);
710
711
  },
712
+ // 替换由原生一次完成,JS 不拼接打开和关闭操作。
713
+ redirectTo(param) {
714
+ return callAsync("redirectTo", param);
715
+ },
711
716
  navigateBack(callbackInfo) {
712
717
  return callAsync("navigateBack", callbackInfo);
713
718
  },
package/dist/mwb.iife.js CHANGED
@@ -224,7 +224,7 @@ SOFTWARE.
224
224
  var import_dsbridge = __toESM(require_dsbridge(), 1);
225
225
 
226
226
  // src/types.ts
227
- var version = "0.1.4";
227
+ var version = "0.1.5";
228
228
 
229
229
  // src/eventHub.ts
230
230
  var hubs = /* @__PURE__ */ new WeakMap();
@@ -435,6 +435,7 @@ SOFTWARE.
435
435
  "getAppInfoSync",
436
436
  "setBadgeCount",
437
437
  "navigateTo",
438
+ "redirectTo",
438
439
  "navigateBack",
439
440
  "navigateBackToRoot",
440
441
  "openExternalBrowser",
@@ -702,6 +703,10 @@ SOFTWARE.
702
703
  navigateTo(param) {
703
704
  return callAsync("navigateTo", param);
704
705
  },
706
+ // 替换由原生一次完成,JS 不拼接打开和关闭操作。
707
+ redirectTo(param) {
708
+ return callAsync("redirectTo", param);
709
+ },
705
710
  navigateBack(callbackInfo) {
706
711
  return callAsync("navigateBack", callbackInfo);
707
712
  },
@@ -26,6 +26,7 @@ export declare const basicPlugin: {
26
26
  readonly setEnableDebug: (enabled: boolean) => void;
27
27
  readonly toast: (param: import("..").ParamToast) => Promise<import("..").GenericAsyncResult<undefined>>;
28
28
  readonly navigateTo: (param: import("..").ParamNavigateTo) => Promise<import("..").GenericAsyncResult<undefined>>;
29
+ readonly redirectTo: (param: import("..").ParamRedirectTo) => Promise<import("..").GenericAsyncResult<undefined>>;
29
30
  readonly navigateBack: (callbackInfo: Record<string, any> | undefined) => Promise<import("..").GenericAsyncResult<undefined>>;
30
31
  readonly navigateBackToRoot: () => Promise<import("..").GenericAsyncResult<undefined>>;
31
32
  readonly openExternalBrowser: (param: import("..").ParamExternalBrowse) => Promise<import("..").GenericAsyncResult<undefined>>;
@@ -7,6 +7,7 @@ export declare const containerPlugin: {
7
7
  setEnableDebug(enabled: boolean): void;
8
8
  toast(param: import("..").ParamToast): Promise<import("..").GenericAsyncResult<undefined>>;
9
9
  navigateTo(param: import("..").ParamNavigateTo): Promise<import("..").GenericAsyncResult<undefined>>;
10
+ redirectTo(param: import("..").ParamRedirectTo): Promise<import("..").GenericAsyncResult<undefined>>;
10
11
  navigateBack(callbackInfo: Record<string, any> | undefined): Promise<import("..").GenericAsyncResult<undefined>>;
11
12
  navigateBackToRoot(): Promise<import("..").GenericAsyncResult<undefined>>;
12
13
  openExternalBrowser(param: import("..").ParamExternalBrowse): Promise<import("..").GenericAsyncResult<undefined>>;
package/dist/types.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export declare const version = "0.1.4";
1
+ export declare const version = "0.1.5";
2
2
  type TYPE_VERSION = typeof version;
3
3
  export type GenericAsyncResult<T = any> = {
4
4
  errCode: number;
@@ -31,6 +31,17 @@ export type ReturnStorageResult = {
31
31
  export type ParamStorageClear = {
32
32
  groupName?: string;
33
33
  };
34
+ /** 替换当前原生容器;Android 必须省略 waitForReady,不支持创建新弹窗。 */
35
+ export type ParamRedirectTo = {
36
+ /** 目标地址,沿用容器的可信来源限制。 */
37
+ url: string;
38
+ /** 新容器标题。 */
39
+ title?: string;
40
+ /** 是否隐藏导航栏,默认 true。 */
41
+ hidden?: boolean;
42
+ /** 仅 iOS:等待主文档加载和绘制准备,默认 false;最多 3000ms,失败保留当前页。 */
43
+ waitForReady?: boolean;
44
+ };
34
45
  export type ParamNavigateTo = {
35
46
  /** 仅 iOS:SDK 等待主文档加载与绘制准备后转场,默认 false;最长等待 3000ms,不代表业务数据就绪。 */
36
47
  waitForReady?: boolean;
@@ -366,6 +377,8 @@ export interface MWBJSSDK {
366
377
  * 打开新页面
367
378
  **/
368
379
  navigateTo(param: ParamNavigateTo): Promise<GenericAsyncResult<undefined>>;
380
+ /** 替换当前容器,返回时跳过被替换页;不要依赖旧页在成功后继续执行 JS。 */
381
+ redirectTo(param: ParamRedirectTo): Promise<GenericAsyncResult<undefined>>;
369
382
  /**
370
383
  * 返回上一级
371
384
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mobile-web-bridge",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Mobile Web Bridge JavaScript SDK",
5
5
  "author": "gaoxiao228",
6
6
  "repository": {