@jhh96/light-app-bridge 1.0.2 → 1.0.3

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

@@ -68,16 +68,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，回退 hook handleMessageFromNative（可能需等待其注入） */
+    private _startListener;
     /** 构造消息信封 */
     private _envelope;
     /** 处理一条归一化后的消息 */

package/dist/lightAppBridge.js

@@ -52,59 +52,77 @@ function getInvoke() {
     }
     return null;
 }
+/** 等待 handleMessageFromNative 出现的轮询间隔(ms) */
+const BACKEND_POLL_INTERVAL = 100;
+/** 等待监听后端就绪的超时(ms) */
+const BACKEND_POLL_TIMEOUT = 10000;
 /** waltz 路径是否可用 */
 function hasWaltz() {
     const w = window.waltz;
     return !!(w && w.event && typeof w.event.on === 'function');
 }
+/** handleMessageFromNative 是否可用 */
+function hasHandleMessageFromNative() {
+    return typeof window.handleMessageFromNative === 'function';
+}
+/** 轮询等待条件成立 */
+function waitFor(check, timeout) {
+    return new Promise((resolve, reject) => {
+        const start = Date.now();
+        const tick = () => {
+            if (check())
+                return resolve();
+            if (Date.now() - start > timeout) {
+                return reject(new Error(`等待超时 (${timeout}ms)`));
+            }
+            setTimeout(tick, BACKEND_POLL_INTERVAL);
+        };
+        tick();
+    });
+}
 /**
- * 选择可用的监听后端：优先 waltz，回退 hook window.handleMessageFromNative。
- * 两者都不可用时抛异常。
+ * 异步解析可用的监听后端并绑定：优先 waltz，回退 hook window.handleMessageFromNative。
+ * 无 waltz 且 handleMessageFromNative 尚未注入时，轮询等待其出现（上限 BACKEND_POLL_TIMEOUT）。
+ * 两者始终不可用则 reject。
  */
-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}))
-    //    其中 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;
-            };
+    // 2. hook handleMessageFromNative 路径：无 waltz 时。
+    //    它可能晚于本 SDK 构造才被 preload/waltzBridge 注册，故轮询等待。
+    return waitFor(hasHandleMessageFromNative, BACKEND_POLL_TIMEOUT).then(() => {
+        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);
         };
-    }
-    throw new Error('LightAppBridge 无可用监听后端：window.waltz.event 与 window.handleMessageFromNative 均不可用');
+        w.handleMessageFromNative = wrapped;
+        return () => {
+            // 还原：仅当仍为自身 wrapped 时才还原，避免覆盖后续可能的重新赋值
+            if (w.handleMessageFromNative === wrapped)
+                w.handleMessageFromNative = prev;
+        };
+    });
 }
 /**
  * 解析 handleMessageFromNative / waltz native-call-js 的统一数据格式。
@@ -137,7 +155,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 +169,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 +185,8 @@ export default class LightAppBridge {
             return peerId;
         });
         this._checkDeps(); // 依赖校验，缺失直接抛异常
-        this._bindListener(); // 绑定消息监听（waltz 或 ipc，自动选择）
-        this.connect(); // 构造即自动发起握手
+        this._startListener(); // 异步绑定消息监听（waltz 或 handleMessageFromNative）
+        this.connect(); // 构造即自动发起握手（内部会等监听就绪）
     }
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     _checkDeps() {
@@ -178,17 +197,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 / handleMessageFromNative）允许稍后出现，由 _startListener 异步等待，
+        // 不在构造时强校验；两者始终未出现时 connect()/ready() 会 reject。
     }
-    /** 绑定消息监听：优先 waltz，回退 ipc（自动选择） */
-    _bindListener() {
+    /** 异步绑定消息监听：优先 waltz，回退 hook 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) => {
+            // 监听后端不可用：让连接失败并给出明确原因
+            this._connectDeferred.reject(new Error('LightAppBridge 无可用监听后端：window.waltz.event 与 window.handleMessageFromNative 均不可用 (' +
+                (e && e.message ? e.message : String(e)) + ')'));
+        });
     }
     /** 构造消息信封 */
     _envelope(type, data, id = genId()) {
@@ -225,34 +250,42 @@ export default class LightAppBridge {
      * @returns 对端 webContentsId
      */
     connect() {
+        var _a;
         if (this._connectStarted)
             return this._connectPromise;
         this._connectStarted = true;
-        // 握手超时保护
+        // 等监听后端就绪（handleMessageFromNative 可能需等待注入）后再握手，
+        // 避免对端的 ack/hello 在监听绑定前到达而丢失
+        const listenerReady = (_a = this._listenerReady) !== null && _a !== void 0 ? _a : Promise.resolve();
+        // 握手超时保护（含监听等待时间）
         this._handshakeTimer = setTimeout(() => {
             if (!this._connected) {
                 this._connectDeferred.reject(new Error(`握手超时 (${this.handshakeTimeout}ms)，对端未响应`));
                 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.3",
   "type": "module",
   "description": "招商随行（WorkLink）插件窗口(plugin)与轻应用窗口(lightapp)之间的双向通信 SDK",
   "main": "./dist/index.js",