mobile-web-bridge 0.0.0-stage → 0.1.1-beta.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mobile Web Bridge contributors
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,127 @@
1
- # Temporary Holding Version
1
+ # Mobile Web Bridge JavaScript SDK
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ MWB 为 iOS 和 Android 的 Web 容器提供统一 JS API。原生通信由 DSBridge 3.x 完成。
4
+
5
+ 当前为未公开发布的 0.1 预览版。以下 npm 包名用于接入示意;当前可用的本地源码安装方式见根 README。
6
+
7
+ ## 安装和使用
8
+
9
+ ```bash
10
+ npm install mobile-web-bridge
11
+ ```
12
+
13
+ ```ts
14
+ import { mwb } from "mobile-web-bridge";
15
+
16
+ const info = mwb.getAppInfoSync();
17
+ await mwb.toast({ msg: `App: ${info.appId}` });
18
+ // basic 命名空间与根兼容入口共享函数;同步方法仍同步返回。
19
+ const sameInfo = mwb.basic.getAppInfoSync();
20
+ ```
21
+
22
+ 右上角文字按钮由当前 Web 页面设置,点击回调仍在当前页面执行:
23
+
24
+ ```ts
25
+ await mwb.setNavigationBarTheme({
26
+ actionTxt: "保存",
27
+ actionExt: "draft-42",
28
+ onActionClick: ({ actionExt }) => console.log("保存按钮被点击", actionExt)
29
+ });
30
+ ```
31
+
32
+ 再次设置会替换原回调;传入 `actionTxt: ""` 可移除按钮。`onActionClick` 不会序列化传给原生,原生点击时只回传 `actionExt`。目前 iOS、Android 均支持文字按钮,`actionIcon` 尚不支持。
33
+
34
+ 网页也可直接引入发布包中的 `dist/mwb.iife.js`,通过 `window.mwb` 调用。应在 MWB 原生容器内加载;普通浏览器中的原生调用会给出“桥未就绪”错误。
35
+
36
+ 完整的 H5 方法示例由相邻的 [`MWB-Demo-Web`](../MWB-Demo-Web/README.md) 维护,可构建为静态站点并同步到 iOS、Android 示例 App。
37
+
38
+ ## 插件组合与构建
39
+
40
+ 默认包提供 basic 的 48 个方法。源码分为 `container`、`device`、`media`、`storage` 四组;事件和 JS 句柄始终包含在 SDK 内。`basicPlugin` 为完整组合,`--plugins=basic` 可构建全量 basic;与旧分组混用时去重。原有 `createMWB(legacyPlugins)` 数组裁剪入口保留,只在 basic 下映射选中的方法。重复方法或覆盖 Core/事件入口的配置直接报错。
41
+
42
+ ```bash
43
+ pnpm install
44
+ pnpm build
45
+ pnpm build:composition --plugins=container,device
46
+ npm pack --dry-run
47
+ ```
48
+
49
+ 组合脚本在 `dist` 输出 `mwb.container-device.iife.js`。组合产物只暴露选中的功能方法,适合按应用需求自行部署;npm 默认入口仍提供全量接口。`npm pack` 会通过 prepack 自动重新构建并检查入口、声明和许可,防止空包或旧产物。构建和打包命令不执行公开发布。
50
+
51
+ ## 指定版本发布 npm
52
+
53
+ 在 `MWB-JS` 目录安装依赖后执行。版本必须是完整版本号,如 `0.1.1` 或 `0.2.0-beta.1`,不接受 `patch` 等隐式递增参数,也不接受 npm 发布时会移除的 `+build` 构建元数据。
54
+
55
+ ```bash
56
+ pnpm install --frozen-lockfile
57
+
58
+ # 先预演:执行检查、构建、真实打包和 npm publish --dry-run,不公开发布。
59
+ npm run release -- 0.2.0-beta.1 --dry-run
60
+
61
+ # 使用有该包发布权限的 npm 账号登录,按 npm 提示完成身份验证。
62
+ npm login --registry=https://registry.npmjs.org/
63
+
64
+ # 发布预览版:默认使用 next 标签。
65
+ npm run release -- 0.2.0-beta.1
66
+
67
+ # 发布正式版:显式使用 latest 标签。
68
+ npm run release -- 0.2.0 --tag latest
69
+
70
+ # 也支持 beta 等自定义标签;查看参数说明。
71
+ npm run release -- 0.2.0-beta.2 --tag beta
72
+ npm run release -- --help
73
+ ```
74
+
75
+ 脚本同步 `package.json` 和 `src/types.ts` 的版本,使发布包的版本与 `mwb.version` 一致;依次运行类型检查、完整 SDK 测试、带 prepack 保护的打包,再将同一个 tgz 以 public 权限发布到 `https://registry.npmjs.org/`。预发布版本不能使用 `latest`。先核实包名和账号权限,npm 不允许覆盖已发布的同名同版本。
76
+
77
+ `--dry-run` 完成或发布前检查失败、收到 Ctrl-C/SIGTERM 时,恢复两个源码版本文件;生成的 `dist` 属于忽略的构建产物,下次打包会重新构建。真实发布开始后保留目标版本,即使 npm 返回错误,也应先查询平台状态再决定是否重试,以免网络异常造成误判。可用 `npm view mobile-web-bridge@<版本号> version --registry=https://registry.npmjs.org/` 核实。
78
+
79
+ 脚本不自动安装依赖、登录、修改原生 SDK 版本、提交 Git、创建 Tag 或推送。发布成功后应检查版本差异,更新变更记录并提交;详细验收要求见 [发布说明](../docs/releasing.md)。
80
+
81
+ ## 自定义原生插件
82
+
83
+ 原生 App 必须先安装对应 Swift/Kotlin 插件;JS 描述不会生成原生业务代码。`createMWB({plugins: [...]})` 默认包含完整 basic,并增加插件命名空间:
84
+
85
+ ```ts
86
+ import { createMWB, defineNativePlugin, type GenericAsyncResult } from "mobile-web-bridge";
87
+
88
+ interface NetworkMethods {
89
+ // 实际请求由宿主原生网络服务执行。
90
+ request(params: { url: string; method: "GET" | "POST"; headers?: Record<string, string>; body?: string }):
91
+ Promise<GenericAsyncResult<{ status: number; headers: Record<string, string>; body: string }>>;
92
+ }
93
+ type NetworkEvents = { requestFinished: { url: string; status: number } };
94
+
95
+ const network = defineNativePlugin<NetworkMethods, NetworkEvents>()({
96
+ name: "network", timeoutMs: 30000
97
+ });
98
+ const sdk = createMWB({ plugins: [network] });
99
+ if (await sdk.hasPlugin("network")) {
100
+ const off = sdk.network.on("requestFinished", event => console.log(event));
101
+ const response = await sdk.network.request({ url: "https://example.com", method: "GET" });
102
+ console.log(response.result); // 保留统一 envelope,不自动解包。
103
+ off(); // 组件卸载时也应解绑。
104
+ }
105
+ ```
106
+
107
+ 没有 `version` 或运行时 `methods` 数组。两阶段 builder 保留插件名字面量及方法/事件类型。新插件只支持异步 Promise;`hasPlugin` 查询原生注册且不创建实例,不代表所有方法都存在;首版不提供 hasMethod。默认 ESM/IIFE 仍只含 basic,使用业务插件时应构建自己的入口脚本。完整 Swift/Kotlin 接入、生命周期及浏览器构建见 [接入文档](../docs/native-plugins.md);可运行入口见 Demo 的 `src/plugins-sdk.ts`。
108
+
109
+ 调用参数、成功结果和事件只接受 JSON:拒绝循环、函数、undefined 字段、非有限数字、非普通对象或 getter/setter。省略参数按 null 处理;显式结果 null 保留。超时默认 30000ms,允许整数 1..120000ms,超时以 `MWBBridgeError(-1103)` 拒绝。缺插件/方法分别为 `-1100/-1101`,旧壳无网关为 `-1106`,完整错误表见接入文档。
110
+
111
+ 名称采用 `[a-z][a-zA-Z0-9_]*`。插件名不得占用 48 个根方法、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`。
112
+
113
+ ## 接口约定
114
+
115
+ - 异步方法返回 `{ errCode, errorMsg?, result? }`;`errCode === 0` 表示成功,非零错误通过 Promise 拒绝并保留错误码。
116
+ - 同步方法直接返回附件声明的数据;桥未就绪或方法不可用时抛出 `MWBBridgeError`。
117
+ - `clearStorageSync(groupName?)` 清空指定分组,参数已根据旧实现修正。
118
+ - iOS 的 `exitApp()` 默认返回不支持;Android 默认只关闭当前 MWB 容器。
119
+ - 应用信息、角标、推送和原生页面能力需要宿主应用配置;未配置会返回明确错误。
120
+
121
+ 完整参数、返回类型和方法列表见本包 TypeScript 声明。浏览器可通过 `mwb.onPageShow(handler)` 等方法订阅事件,用对应 `off` 方法解绑。宿主使用 `mwb.dispatchEvent`、`mwb.backBtnPressed` 及 `mwb.<handlerName>` 调用 JS。
122
+
123
+ ## 来源
124
+
125
+ MWB 的通信底层基于 [DSBridge](https://github.com/wendux/DSBridge-Android)(MIT)。接口能力参考当前工作区的旧项目,MWB 不依赖 Cordova。
126
+
127
+ 包内包含 LICENSE 和 THIRD_PARTY_NOTICES.md,ESM/IIFE/组合脚本保留完整许可注释;单独分发 bundle 时也不要移除这些注释。
@@ -0,0 +1,34 @@
1
+ # DSBridge third-party notice
2
+
3
+ DSBridge JavaScript 3.1.4: https://www.npmjs.com/package/dsbridge/v/3.1.4
4
+ DSBridge Android 3.0.0: https://github.com/wendux/DSBridge-Android/tree/d3e5ebc6ca8170f97e420f2f482680c8e149b471
5
+ DSBridge iOS 3.0.6: https://github.com/wendux/DSBridge-IOS/tree/f0e3c724dd362800528f8b6c788bdad7006cc187
6
+
7
+ Author: wendux (杜文 / Du Wen), as identified by upstream package metadata and source.
8
+ The upstream npm metadata, Android readme.md and iOS podspec declare MIT.
9
+ The pinned native trees do not provide a separate LICENSE file; the MIT terms
10
+ are reproduced below without inventing an absent upstream copyright notice.
11
+ Original iOS source notices are retained verbatim:
12
+
13
+ Copyright © 2016年 杜文. All rights reserved.
14
+ Copyright © 2018年 杜文. All rights reserved.
15
+
16
+ MIT License
17
+
18
+ Permission is hereby granted, free of charge, to any person obtaining a copy
19
+ of this software and associated documentation files (the "Software"), to deal
20
+ in the Software without restriction, including without limitation the rights
21
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
22
+ copies of the Software, and to permit persons to whom the Software is
23
+ furnished to do so, subject to the following conditions:
24
+
25
+ The above copyright notice and this permission notice shall be included in all
26
+ copies or substantial portions of the Software.
27
+
28
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
29
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
30
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
31
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
32
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
33
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
34
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ export declare const apiMethods: readonly ["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"];
@@ -0,0 +1,15 @@
1
+ import { type MWBJSSDK } from "./types";
2
+ /** 插件描述只包含所选功能,供浏览器组合包静态裁剪。 */
3
+ export interface MWBPlugin {
4
+ readonly name: string;
5
+ readonly methods: Record<string, (...args: never[]) => unknown>;
6
+ }
7
+ /** basic 的根兼容入口与命名空间始终共享同一份函数和事件状态。 */
8
+ export type MWBBasic = Omit<MWBJSSDK, "version">;
9
+ export type MWBSDK = MWBJSSDK & {
10
+ readonly basic: MWBBasic;
11
+ };
12
+ export type MWBPartialSDK = Partial<MWBJSSDK> & {
13
+ readonly basic: Partial<MWBBasic>;
14
+ };
15
+ export declare function assembleMWB(plugins: MWBPlugin[]): MWBPartialSDK;
@@ -0,0 +1,17 @@
1
+ import type { GenericAsyncResult } from "./types";
2
+ /** DSBridge 的最小接口,便于把原生通信限制在一个文件内。 */
3
+ export interface DSBridgeLike {
4
+ call(method: string, args?: unknown, callback?: (value: unknown) => void): unknown;
5
+ register?(name: string, handler: (...args: unknown[]) => unknown): void;
6
+ hasNativeMethod?(name: string, type?: string): boolean;
7
+ }
8
+ /** MWB 传输及原生错误统一使用的异常。 */
9
+ export declare class MWBBridgeError extends Error {
10
+ readonly errCode: number;
11
+ readonly errorMsg: string;
12
+ constructor(errCode: number, errorMsg: string);
13
+ }
14
+ /** 只在调用时读取桥,避免服务端渲染或页面初始化阶段直接访问 window。 */
15
+ export declare function getBridge(): DSBridgeLike;
16
+ export declare function callSync<T>(method: string, args?: unknown): T;
17
+ export declare function callAsync<T>(method: string, args?: unknown): Promise<GenericAsyncResult<T>>;
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,14 @@
1
+ import { type MWBPlugin, type MWBSDK, type MWBPartialSDK } from "./assembleMWB";
2
+ import { type MWBNativePlugin, type NativePluginNamespaces } from "./nativePlugins";
3
+ export type { MWBPlugin } from "./assembleMWB";
4
+ export type { MWBSDK, MWBBasic } from "./assembleMWB";
5
+ export { defineNativePlugin } from "./nativePlugins";
6
+ export type { MWBNativePlugin } from "./nativePlugins";
7
+ export type MWBClient = MWBSDK & {
8
+ hasPlugin(name: string): Promise<boolean>;
9
+ };
10
+ export declare function createMWB(): MWBClient;
11
+ export declare function createMWB<const Plugins extends readonly MWBNativePlugin[]>(options: {
12
+ plugins: Plugins;
13
+ }): MWBClient & NativePluginNamespaces<Plugins>;
14
+ export declare function createMWB(plugins: MWBPlugin[]): MWBPartialSDK;
@@ -0,0 +1,13 @@
1
+ import type { DSBridgeLike } from "./bridge";
2
+ type Handler = (...args: unknown[]) => unknown;
3
+ /** 同一 bridge 只注册一次原生接收器,避免默认 SDK 和业务组合实例相互覆盖。 */
4
+ declare class EventHub {
5
+ private readonly bridge;
6
+ private readonly listeners;
7
+ private back?;
8
+ constructor(bridge: DSBridgeLike);
9
+ on(name: string, handler: Handler): () => void;
10
+ setBack(owner: object, handler?: () => boolean): void;
11
+ }
12
+ export declare function getEventHub(bridge: DSBridgeLike): EventHub;
13
+ export {};
@@ -0,0 +1,3 @@
1
+ import type { MWBJSSDK } from "./types";
2
+ /** DSBridge 只保留一个注册函数;多监听器和解绑由这一层管理。 */
3
+ export declare function createEvents(): Pick<MWBJSSDK, "registerHandler" | "unRegisterHandlers" | "unRegisterHandler" | "checkHandlerExist" | "onNetworkStatusChange" | "offNetworkStatusChange" | "onAppShow" | "offAppShow" | "onAppHide" | "offAppHide" | "onRemoteNotificationReceive" | "offRemoteNotificationReceive" | "onPageShow" | "offPageShow" | "onPageHide" | "offPageHide" | "onBackBtnPressed" | "offBackBtnPressed">;
@@ -0,0 +1,19 @@
1
+ /** 默认入口组合全部能力,同时保留按功能组合的构造函数。 */
2
+ import "dsbridge";
3
+ export { createMWB, defineNativePlugin } from "./createMWB";
4
+ export type { MWBPlugin, MWBNativePlugin, MWBClient, MWBSDK, MWBBasic } from "./createMWB";
5
+ export { MWBBridgeError } from "./bridge";
6
+ export * from "./types";
7
+ export { containerPlugin } from "./plugins/container";
8
+ export { devicePlugin } from "./plugins/device";
9
+ export { mediaPlugin } from "./plugins/media";
10
+ export { storagePlugin } from "./plugins/storage";
11
+ export { basicPlugin } from "./plugins/basic";
12
+ import type { MWBClient } from "./createMWB";
13
+ declare global {
14
+ interface Window {
15
+ mwb: MWBClient;
16
+ }
17
+ }
18
+ export declare const mwb: MWBClient;
19
+ export default mwb;