@jhh96/light-app-bridge 1.0.2 → 1.0.4

package/README.md

@@ -19,10 +19,12 @@
 
 | 监听后端 | 优先级 | 适用环境 | 说明 |
 |---------|--------|---------|------|
-| `window.waltz.event.on('native-call-js')` | 高（优先） | 有 waltz 注入的环境 | 推荐路径 |
-| `window.handleMessageFromNative` | 低（回退） | 无 waltz 的环境 | hook 此全局方法（waltzBridge 投递消息的统一入口，`sendMessageToPluginLightAppById` 最终会调它） |
+| `window.waltz.event.on('native-call-js')` | 高（优先） | 有 waltz 注入的环境 | 推荐路径，立即可用 |
+| `window.handleMessageFromNative` | 低（回退） | 无 waltz 的环境 | hook 此全局方法（waltzBridge 投递消息的统一入口）。**可能晚于构造注入**，SDK 会轮询等待（上限 10s） |
 
-两者都不可用时构造抛异常。SDK 内部按 waltz → handleMessageFromNative 顺序探测，无需手动指定。
+- 两者都始终不可用时，`connect()`/`ready()` reject（构造不抛，因监听后端允许稍后出现）
+- SDK 内部按 waltz → handleMessageFromNative 顺序探测，无需手动指定
+- 握手会等监听就绪后才开始，避免早到的 ack/hello 丢失
 
 ## 安装（两个项目）
 

package/dist/lightAppBridge.d.ts

@@ -12,9 +12,10 @@
  *
  * 收消息不强依赖 waltz，按以下优先级自动选择监听后端：
  *   1. window.waltz.event.on('native-call-js')  —— 有 waltz 的环境（推荐）
- *   2. window.handleMessageFromNative            —— 无 waltz 时 hook 此全局方法
- *      （waltzBridge 投递消息的统一入口，sendMessageToPluginLightAppById 最终会调它）
- *   两者都不可用则抛异常。
+ *   2. window.handleMessageFromNative            —— 无 waltz 时由本 SDK 定义此方法
+ *      （该方法由 waltz.min.js 注册；无 waltz 时为 undefined，renderer 投递消息前
+ *       会检查其类型，没人定义则消息被丢弃。故由本 SDK 照 waltz.min.js 方式定义，
+ *       renderer 收到消息后主动调用它传入消息）
  *
  * 消息信封：
  *   { __sdk: 'LightAppBridge', v: 1, id, type, data }
@@ -68,16 +69,17 @@ export default class LightAppBridge {
     private _connectDeferred;
     private _connectPromise;
     private _unlisten;
+    private _listenerReady;
     /**
      * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
      * @param options 超时配置
-     * @throws 依赖未就绪时抛出（window.worklink / 监听后端）
+     * @throws 依赖未就绪时抛出（window.worklink；监听后端可稍后出现，不算构造失败）
      */
     constructor(role?: BridgeRole, options?: BridgeOptions);
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     private _checkDeps;
-    /** 绑定消息监听：优先 waltz，回退 ipc（自动选择） */
-    private _bindListener;
+    /** 绑定消息监听：优先 waltz；无 waltz 时定义/包装 window.handleMessageFromNative */
+    private _startListener;
     /** 构造消息信封 */
     private _envelope;
     /** 处理一条归一化后的消息 */

package/dist/lightAppBridge.js

@@ -12,9 +12,10 @@
  *
  * 收消息不强依赖 waltz，按以下优先级自动选择监听后端：
  *   1. window.waltz.event.on('native-call-js')  —— 有 waltz 的环境（推荐）
- *   2. window.handleMessageFromNative            —— 无 waltz 时 hook 此全局方法
- *      （waltzBridge 投递消息的统一入口，sendMessageToPluginLightAppById 最终会调它）
- *   两者都不可用则抛异常。
+ *   2. window.handleMessageFromNative            —— 无 waltz 时由本 SDK 定义此方法
+ *      （该方法由 waltz.min.js 注册；无 waltz 时为 undefined，renderer 投递消息前
+ *       会检查其类型，没人定义则消息被丢弃。故由本 SDK 照 waltz.min.js 方式定义，
+ *       renderer 收到消息后主动调用它传入消息）
  *
  * 消息信封：
  *   { __sdk: 'LightAppBridge', v: 1, id, type, data }
@@ -58,53 +59,63 @@ function hasWaltz() {
     return !!(w && w.event && typeof w.event.on === 'function');
 }
 /**
- * 选择可用的监听后端：优先 waltz，回退 hook window.handleMessageFromNative。
- * 两者都不可用时抛异常。
+ * 解析可用的监听后端并绑定：优先 waltz，回退定义 window.handleMessageFromNative。
+ *
+ * 说明：handleMessageFromNative 由 waltz.min.js 注册（参考其实现）。
+ * 无 waltz 的环境里它是 undefined，且 renderer（waltzBridge preload）投递消息前
+ * 会检查 typeof window.handleMessageFromNative === 'function'——
+ * 没人定义它消息就会被丢弃。因此无 waltz 时由本 SDK 定义此方法，
+ * renderer 收到消息后会主动调用它传入消息。
  */
-function pickMessageBackend() {
-    // 1. waltz 路径：有 waltz 的环境
+function bindMessageBackend(cb) {
+    const w = window;
+    // 1. waltz 路径：有 waltz 的环境（立即可用）
     if (hasWaltz()) {
-        return (cb) => {
-            const handler = (raw) => {
-                const msg = parseHandleMessageFromNative(raw);
-                if (msg)
-                    cb(msg);
-            };
-            window.waltz.event.on('native-call-js', handler);
-            return () => {
-                var _a;
-                const ev = (_a = window.waltz) === null || _a === void 0 ? void 0 : _a.event;
-                if (ev && typeof ev.off === 'function')
-                    ev.off('native-call-js', handler);
-                else if (ev && typeof ev.removeListener === 'function')
-                    ev.removeListener('native-call-js', handler);
-            };
+        const handler = (raw) => {
+            const msg = parseHandleMessageFromNative(raw);
+            if (msg)
+                cb(msg);
         };
+        w.waltz.event.on('native-call-js', handler);
+        return Promise.resolve(() => {
+            var _a;
+            const ev = (_a = w.waltz) === null || _a === void 0 ? void 0 : _a.event;
+            if (ev && typeof ev.off === 'function')
+                ev.off('native-call-js', handler);
+            else if (ev && typeof ev.removeListener === 'function')
+                ev.removeListener('native-call-js', handler);
+        });
     }
-    // 2. hook handleMessageFromNative 路径：无 waltz 时
-    //    waltzBridge 投递消息的统一入口：handleMessageFromNative(JSON.stringify({responseId, responseData}))
+    // 2. 定义 handleMessageFromNative 路径：无 waltz 时。
+    //    renderer（waltzBridge）投递：handleMessageFromNative(JSON.stringify({responseId, responseData}))，
     //    其中 responseData = {code, body:{eventName, params:{message, fromWebContentsId}}, msg}
-    if (typeof window.handleMessageFromNative === 'function') {
-        return (cb) => {
-            const w = window;
-            const prev = w.handleMessageFromNative;
-            const wrapped = function (raw) {
-                const msg = parseHandleMessageFromNative(raw);
-                if (msg)
-                    cb(msg);
-                // 透传给原 handler（若存在），保持 waltz/业务自身逻辑不被破坏
-                if (typeof prev === 'function')
-                    return prev.apply(this, arguments);
-            };
-            w.handleMessageFromNative = wrapped;
-            return () => {
-                // 还原：仅当仍为自身 wrapped 时才还原，避免覆盖后续可能的重新赋值
-                if (w.handleMessageFromNative === wrapped)
-                    w.handleMessageFromNative = prev;
-            };
+    if (typeof w.handleMessageFromNative !== 'function') {
+        // 尚未定义（无 waltz 的正常情况）：由本 SDK 定义，renderer 主动调它传消息
+        const handler = function (raw) {
+            const msg = parseHandleMessageFromNative(raw);
+            if (msg)
+                cb(msg);
         };
+        w.handleMessageFromNative = handler;
+        return Promise.resolve(() => {
+            // 清理：仅当仍为自身 handler 时才删除，避免误删后续重新赋值
+            if (w.handleMessageFromNative === handler)
+                delete w.handleMessageFromNative;
+        });
     }
-    throw new Error('LightAppBridge 无可用监听后端：window.waltz.event 与 window.handleMessageFromNative 均不可用');
+    // 已存在（如 waltz 晚于本 SDK 加载、或其它实例已定义）：包装透传，不破坏原逻辑
+    const prev = w.handleMessageFromNative;
+    const wrapped = function (raw) {
+        const msg = parseHandleMessageFromNative(raw);
+        if (msg)
+            cb(msg);
+        return prev.apply(this, arguments);
+    };
+    w.handleMessageFromNative = wrapped;
+    return Promise.resolve(() => {
+        if (w.handleMessageFromNative === wrapped)
+            w.handleMessageFromNative = prev;
+    });
 }
 /**
  * 解析 handleMessageFromNative / waltz native-call-js 的统一数据格式。
@@ -137,7 +148,7 @@ export default class LightAppBridge {
     /**
      * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
      * @param options 超时配置
-     * @throws 依赖未就绪时抛出（window.worklink / 监听后端）
+     * @throws 依赖未就绪时抛出（window.worklink；监听后端可稍后出现，不算构造失败）
      */
     constructor(role, options = {}) {
         this._pending = new Map();
@@ -151,6 +162,7 @@ export default class LightAppBridge {
         this._handshakeTimer = null;
         this._started = false;
         this._unlisten = null;
+        this._listenerReady = null;
         let r = role === 'plugin' || role === 'lightapp' ? role : 'lightapp';
         if (role !== 'plugin' && role !== 'lightapp') {
             const wl = window.worklink;
@@ -166,8 +178,8 @@ export default class LightAppBridge {
             return peerId;
         });
         this._checkDeps(); // 依赖校验，缺失直接抛异常
-        this._bindListener(); // 绑定消息监听（waltz 或 ipc，自动选择）
-        this.connect(); // 构造即自动发起握手
+        this._startListener(); // 绑定消息监听（waltz 或定义 handleMessageFromNative）
+        this.connect(); // 构造即自动发起握手（内部会等监听就绪）
     }
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     _checkDeps() {
@@ -178,17 +190,23 @@ export default class LightAppBridge {
         if (this.role === 'plugin' && typeof (w.worklink.plugin && w.worklink.plugin.getContentContext) !== 'function') {
             throw new Error('LightAppBridge(plugin) 依赖 window.worklink.plugin.getContentContext，当前环境不可用');
         }
-        if (!hasWaltz() && typeof w.handleMessageFromNative !== 'function') {
-            throw new Error('LightAppBridge 无可用监听后端：window.waltz.event 与 window.handleMessageFromNative 均不可用');
-        }
+        // 监听后端不强校验：有 waltz 走 waltz；无 waltz 由 _startListener 定义
+        // window.handleMessageFromNative（renderer 会主动调用它传入消息）。
     }
-    /** 绑定消息监听：优先 waltz，回退 ipc（自动选择） */
-    _bindListener() {
+    /** 绑定消息监听：优先 waltz；无 waltz 时定义/包装 window.handleMessageFromNative */
+    _startListener() {
         if (this._started)
             return;
         this._started = true;
-        const backend = pickMessageBackend();
-        this._unlisten = backend((msg) => this._onMessage(msg));
+        this._listenerReady = bindMessageBackend((msg) => this._onMessage(msg))
+            .then((unlisten) => {
+            this._unlisten = unlisten;
+        })
+            .catch((e) => {
+            // 理论上不会发生（无 waltz 时必走定义路径），保险起见让连接失败并给出原因
+            this._connectDeferred.reject(new Error('LightAppBridge 监听后端绑定失败 (' +
+                (e && e.message ? e.message : String(e)) + ')'));
+        });
     }
     /** 构造消息信封 */
     _envelope(type, data, id = genId()) {
@@ -225,9 +243,12 @@ export default class LightAppBridge {
      * @returns 对端 webContentsId
      */
     connect() {
+        var _a;
         if (this._connectStarted)
             return this._connectPromise;
         this._connectStarted = true;
+        // 等监听后端绑定完成后再握手，避免对端的 ack/hello 在监听绑定前到达而丢失
+        const listenerReady = (_a = this._listenerReady) !== null && _a !== void 0 ? _a : Promise.resolve();
         // 握手超时保护
         this._handshakeTimer = setTimeout(() => {
             if (!this._connected) {
@@ -235,24 +256,28 @@ export default class LightAppBridge {
                 this._clearHelloTimer();
             }
         }, this.handshakeTimeout);
-        if (this.role === 'plugin') {
-            // 插件：解析目标后发 hello，并重试直到收到 ack
-            ;
-            window.worklink.plugin.getContentContext()
-                .then((ctx) => {
-                if (!ctx || ctx.webContentsId == null) {
-                    throw new Error('getContentContext 未返回 webContentsId');
-                }
-                this._target = ctx.webContentsId;
-                this._sendHello();
-                this._helloTimer = setInterval(() => {
-                    if (!this._connected)
-                        this._sendHello();
-                }, HELLO_RETRY_INTERVAL);
-            })
-                .catch((e) => this._connectDeferred.reject(e));
-        }
-        // lightapp 被动等待 hello（listener 已绑定），收到后在 _onHello 中回 ack 并 resolve
+        listenerReady
+            .then(() => {
+            if (this._connected)
+                return;
+            if (this.role === 'plugin') {
+                // 插件：解析目标后发 hello，并重试直到收到 ack
+                return window.worklink.plugin.getContentContext()
+                    .then((ctx) => {
+                    if (!ctx || ctx.webContentsId == null) {
+                        throw new Error('getContentContext 未返回 webContentsId');
+                    }
+                    this._target = ctx.webContentsId;
+                    this._sendHello();
+                    this._helloTimer = setInterval(() => {
+                        if (!this._connected)
+                            this._sendHello();
+                    }, HELLO_RETRY_INTERVAL);
+                });
+            }
+            // lightapp 被动等待 hello（listener 已绑定），收到后在 _onHello 中回 ack 并 resolve
+        })
+            .catch((e) => this._connectDeferred.reject(e));
         return this._connectPromise;
     }
     /** 发送 hello（携带自身 webContentsId） */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhh96/light-app-bridge",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "description": "招商随行（WorkLink）插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK",
   "main": "./dist/index.js",