@jhh96/light-app-bridge 1.0.3 → 1.0.5

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 }
@@ -36,7 +37,7 @@ export interface Envelope {
 export interface BridgeOptions {
     /** send 默认超时(ms)，默认 3000 */
     timeout?: number;
-    /** 握手超时(ms)，默认 30000 */
+    /** 握手超时(ms)，默认 30000。仅 plugin 角色生效；lightapp 端持续等待，不超时 */
     handshakeTimeout?: number;
 }
 /** send 单次调用选项 */
@@ -77,7 +78,7 @@ export default class LightAppBridge {
     constructor(role?: BridgeRole, options?: BridgeOptions);
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     private _checkDeps;
-    /** 异步绑定消息监听：优先 waltz，回退 hook handleMessageFromNative（可能需等待其注入） */
+    /** 绑定消息监听：优先 waltz；无 waltz 时定义/包装 window.handleMessageFromNative */
     private _startListener;
     /** 构造消息信封 */
     private _envelope;
@@ -85,8 +86,8 @@ export default class LightAppBridge {
     private _onMessage;
     /**
      * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
-     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack）
-     *   - 轻应用：启动握手等待（被动等 hello；若插件始终未来则超时）
+     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack 或超时）
+     *   - 轻应用：被动等待 hello（持续监听，不超时——插件可能任意晚才发起连接）
      * 多次调用幂等，返回同一个连接 Promise。
      * @returns 对端 webContentsId
      */

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 }
@@ -52,38 +53,19 @@ 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 且 handleMessageFromNative 尚未注入时，轮询等待其出现（上限 BACKEND_POLL_TIMEOUT）。
- * 两者始终不可用则 reject。
+ * 解析可用的监听后端并绑定：优先 waltz，回退定义 window.handleMessageFromNative。
+ *
+ * 说明：handleMessageFromNative 由 waltz.min.js 注册（参考其实现）。
+ * 无 waltz 的环境里它是 undefined，且 renderer（waltzBridge preload）投递消息前
+ * 会检查 typeof window.handleMessageFromNative === 'function'——
+ * 没人定义它消息就会被丢弃。因此无 waltz 时由本 SDK 定义此方法，
+ * renderer 收到消息后会主动调用它传入消息。
  */
 function bindMessageBackend(cb) {
     const w = window;
@@ -104,24 +86,35 @@ function bindMessageBackend(cb) {
                 ev.removeListener('native-call-js', handler);
         });
     }
-    // 2. hook handleMessageFromNative 路径：无 waltz 时。
-    //    它可能晚于本 SDK 构造才被 preload/waltzBridge 注册，故轮询等待。
-    return waitFor(hasHandleMessageFromNative, BACKEND_POLL_TIMEOUT).then(() => {
-        const prev = w.handleMessageFromNative;
-        const wrapped = function (raw) {
+    // 2. 定义 handleMessageFromNative 路径：无 waltz 时。
+    //    renderer（waltzBridge）投递：handleMessageFromNative(JSON.stringify({responseId, responseData}))，
+    //    其中 responseData = {code, body:{eventName, params:{message, fromWebContentsId}}, msg}
+    if (typeof w.handleMessageFromNative !== 'function') {
+        // 尚未定义（无 waltz 的正常情况）：由本 SDK 定义，renderer 主动调它传消息
+        const handler = 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;
         };
+        w.handleMessageFromNative = handler;
+        return Promise.resolve(() => {
+            // 清理：仅当仍为自身 handler 时才删除，避免误删后续重新赋值
+            if (w.handleMessageFromNative === handler)
+                delete w.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;
     });
 }
 /**
@@ -185,7 +178,7 @@ export default class LightAppBridge {
             return peerId;
         });
         this._checkDeps(); // 依赖校验，缺失直接抛异常
-        this._startListener(); // 异步绑定消息监听（waltz 或 handleMessageFromNative）
+        this._startListener(); // 绑定消息监听（waltz 或定义 handleMessageFromNative）
         this.connect(); // 构造即自动发起握手（内部会等监听就绪）
     }
     /** 校验依赖是否就绪，缺失抛出明确异常 */
@@ -197,10 +190,10 @@ 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，当前环境不可用');
         }
-        // 监听后端（waltz / handleMessageFromNative）允许稍后出现，由 _startListener 异步等待，
-        // 不在构造时强校验；两者始终未出现时 connect()/ready() 会 reject。
+        // 监听后端不强校验：有 waltz 走 waltz；无 waltz 由 _startListener 定义
+        // window.handleMessageFromNative（renderer 会主动调用它传入消息）。
     }
-    /** 异步绑定消息监听：优先 waltz，回退 hook handleMessageFromNative（可能需等待其注入） */
+    /** 绑定消息监听：优先 waltz；无 waltz 时定义/包装 window.handleMessageFromNative */
     _startListener() {
         if (this._started)
             return;
@@ -210,8 +203,8 @@ export default class LightAppBridge {
             this._unlisten = unlisten;
         })
             .catch((e) => {
-            // 监听后端不可用：让连接失败并给出明确原因
-            this._connectDeferred.reject(new Error('LightAppBridge 无可用监听后端：window.waltz.event 与 window.handleMessageFromNative 均不可用 (' +
+            // 理论上不会发生（无 waltz 时必走定义路径），保险起见让连接失败并给出原因
+            this._connectDeferred.reject(new Error('LightAppBridge 监听后端绑定失败 (' +
                 (e && e.message ? e.message : String(e)) + ')'));
         });
     }
@@ -244,8 +237,8 @@ export default class LightAppBridge {
     // —— 连接 / 握手 —— //
     /**
      * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
-     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack）
-     *   - 轻应用：启动握手等待（被动等 hello；若插件始终未来则超时）
+     *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack 或超时）
+     *   - 轻应用：被动等待 hello（持续监听，不超时——插件可能任意晚才发起连接）
      * 多次调用幂等，返回同一个连接 Promise。
      * @returns 对端 webContentsId
      */
@@ -254,16 +247,18 @@ export default class LightAppBridge {
         if (this._connectStarted)
             return this._connectPromise;
         this._connectStarted = true;
-        // 等监听后端就绪（handleMessageFromNative 可能需等待注入）后再握手，
-        // 避免对端的 ack/hello 在监听绑定前到达而丢失
+        // 等监听后端绑定完成后再握手，避免对端的 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);
+        // 握手超时保护：仅插件（主动方）需要——它发了 hello 却收不到 ack 说明对端异常。
+        // 轻应用（被动方）持续等待，不超时：插件可能任意晚才发起连接。
+        if (this.role === 'plugin') {
+            this._handshakeTimer = setTimeout(() => {
+                if (!this._connected) {
+                    this._connectDeferred.reject(new Error(`握手超时 (${this.handshakeTimeout}ms)，对端未响应`));
+                    this._clearHelloTimer();
+                }
+            }, this.handshakeTimeout);
+        }
         listenerReady
             .then(() => {
             if (this._connected)

package/package.json

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