@jhh96/light-app-bridge 1.0.0 → 1.0.1

package/README.md

@@ -8,12 +8,22 @@
 
 ## 依赖（构造时校验，缺失直接抛异常）
 
+**必需：**
+
 | 依赖 | 用途 | 来源 |
 |------|------|------|
-| `window.waltz.event.on` | 接收消息 | preload 注入的 waltz SDK |
 | `window.worklink`（含 `invokeModuleMethodSync`） | 发送消息 / 取 webContentsId | preload 注入 |
 | `window.worklink.plugin.getContentContext` | 解析目标轻应用 webContentsId（**仅 plugin 角色**） | pluginLightAppPreload 注入 |
 
+**收消息（二选一，自动选择，不强依赖 waltz）：**
+
+| 监听后端 | 优先级 | 适用环境 | 说明 |
+|---------|--------|---------|------|
+| `window.waltz.event.on('native-call-js')` | 高（优先） | 有 waltz 注入的环境 | 推荐路径 |
+| `window.handleMessageFromNative` | 低（回退） | 无 waltz 的环境 | hook 此全局方法（waltzBridge 投递消息的统一入口，`sendMessageToPluginLightAppById` 最终会调它） |
+
+两者都不可用时构造抛异常。SDK 内部按 waltz → handleMessageFromNative 顺序探测，无需手动指定。
+
 ## 安装（两个项目）
 
 共享包位于仓库根 `packages/lightAppBridge`（与 hkvs-llm-chat、vue-talent-cockpit 同级），两个项目以 `file:` 相对路径引用（npm 7+ 软链式安装，源码改动实时生效）。

package/dist/lightAppBridge.d.ts

@@ -6,10 +6,15 @@
  *   2. 请求/响应：基于 id 关联，对端 onMessage 回调的「返回值」带相同 id 回复。
  *   3. SDK 标识：所有消息携带 __sdk 标识 + 版本号，隔离其它消息，防止混淆。
  *
- * 依赖（构造时校验，缺失直接抛异常，请确保依赖注入完成后再 new）：
- *   - window.waltz.event.on        收消息
- *   - window.worklink              发消息 / 取 webContentsId
- *   - window.worklink.plugin.getContentContext  （仅 plugin 角色需要）
+ * 依赖（构造时校验，缺失直接抛异常）：
+ *   - window.worklink              发消息 / 取 webContentsId（必需）
+ *   - window.worklink.plugin.getContentContext  （仅 plugin 角色需要，必需）
+ *
+ * 收消息不强依赖 waltz，按以下优先级自动选择监听后端：
+ *   1. window.waltz.event.on('native-call-js')  —— 有 waltz 的环境（推荐）
+ *   2. window.handleMessageFromNative            —— 无 waltz 时 hook 此全局方法
+ *      （waltzBridge 投递消息的统一入口，sendMessageToPluginLightAppById 最终会调它）
+ *   两者都不可用则抛异常。
  *
  * 消息信封：
  *   { __sdk: 'LightAppBridge', v: 1, id, type, data }
@@ -62,20 +67,21 @@ export default class LightAppBridge {
     private _started;
     private _connectDeferred;
     private _connectPromise;
+    private _unlisten;
     /**
      * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
      * @param options 超时配置
-     * @throws 依赖未就绪时抛出（window.waltz / window.worklink）
+     * @throws 依赖未就绪时抛出（window.worklink / 监听后端）
      */
     constructor(role?: BridgeRole, options?: BridgeOptions);
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     private _checkDeps;
-    /** 绑定 native-call-js 监听 */
+    /** 绑定消息监听：优先 waltz，回退 ipc（自动选择） */
     private _bindListener;
     /** 构造消息信封 */
     private _envelope;
-    /** 处理一条原生消息 */
-    private _onRaw;
+    /** 处理一条归一化后的消息 */
+    private _onMessage;
     /**
      * 建立连接（握手）。构造时已自动调用，通常无需手动调；如需重新握手可再次调用。
      *   - 插件：发起握手（解析目标 id → 发 hello → 每秒重试直到收到 ack）
@@ -124,6 +130,8 @@ export default class LightAppBridge {
      * @returns 调用以取消监听
      */
     onMessage(handler: MessageHandler): () => void;
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试 */
+    destroy(): void;
 }
 /**
  * 工厂函数

package/dist/lightAppBridge.js

@@ -6,10 +6,15 @@
  *   2. 请求/响应：基于 id 关联，对端 onMessage 回调的「返回值」带相同 id 回复。
  *   3. SDK 标识：所有消息携带 __sdk 标识 + 版本号，隔离其它消息，防止混淆。
  *
- * 依赖（构造时校验，缺失直接抛异常，请确保依赖注入完成后再 new）：
- *   - window.waltz.event.on        收消息
- *   - window.worklink              发消息 / 取 webContentsId
- *   - window.worklink.plugin.getContentContext  （仅 plugin 角色需要）
+ * 依赖（构造时校验，缺失直接抛异常）：
+ *   - window.worklink              发消息 / 取 webContentsId（必需）
+ *   - window.worklink.plugin.getContentContext  （仅 plugin 角色需要，必需）
+ *
+ * 收消息不强依赖 waltz，按以下优先级自动选择监听后端：
+ *   1. window.waltz.event.on('native-call-js')  —— 有 waltz 的环境（推荐）
+ *   2. window.handleMessageFromNative            —— 无 waltz 时 hook 此全局方法
+ *      （waltzBridge 投递消息的统一入口，sendMessageToPluginLightAppById 最终会调它）
+ *   两者都不可用则抛异常。
  *
  * 消息信封：
  *   { __sdk: 'LightAppBridge', v: 1, id, type, data }
@@ -47,11 +52,91 @@ function getInvoke() {
     }
     return null;
 }
+/** waltz 路径是否可用 */
+function hasWaltz() {
+    const w = window.waltz;
+    return !!(w && w.event && typeof w.event.on === 'function');
+}
+/**
+ * 选择可用的监听后端：优先 waltz，回退 hook window.handleMessageFromNative。
+ * 两者都不可用时抛异常。
+ */
+function pickMessageBackend() {
+    // 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 () => {
+                const ev = window.waltz?.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;
+            };
+        };
+    }
+    throw new Error('LightAppBridge 无可用监听后端：window.waltz.event 与 window.handleMessageFromNative 均不可用');
+}
+/**
+ * 解析 handleMessageFromNative / waltz native-call-js 的统一数据格式。
+ *   - handleMessageFromNative 入参可能是 JSON 字符串 {responseId, responseData}，
+ *     responseData = {code, body:{eventName, params:{message, fromWebContentsId}}, msg}
+ *   - waltz native-call-js 回调直接收到上述 responseData 对象
+ * 两者最终都归一为 { envelope, fromWebContentsId }。
+ */
+function parseHandleMessageFromNative(raw) {
+    try {
+        let responseData = raw;
+        if (typeof raw === 'string') {
+            const parsed = JSON.parse(raw);
+            // handleMessageFromNative 入参带 responseId 包装
+            responseData = parsed && parsed.responseData != null ? parsed.responseData : parsed;
+        }
+        if (!responseData || !responseData.body || responseData.body.eventName !== 'plugin-message') {
+            return null;
+        }
+        const params = responseData.body.params || {};
+        const envelope = params.message;
+        const fromWebContentsId = params.fromWebContentsId != null ? params.fromWebContentsId : null;
+        return { envelope, fromWebContentsId };
+    }
+    catch {
+        return null;
+    }
+}
 export default class LightAppBridge {
     /**
      * @param role 角色，省略时按 window.worklink.plugin 是否存在自动探测
      * @param options 超时配置
-     * @throws 依赖未就绪时抛出（window.waltz / window.worklink）
+     * @throws 依赖未就绪时抛出（window.worklink / 监听后端）
      */
     constructor(role, options = {}) {
         this._pending = new Map();
@@ -64,6 +149,7 @@ export default class LightAppBridge {
         this._helloTimer = null;
         this._handshakeTimer = null;
         this._started = false;
+        this._unlisten = null;
         let r = role === 'plugin' || role === 'lightapp' ? role : 'lightapp';
         if (role !== 'plugin' && role !== 'lightapp') {
             const wl = window.worklink;
@@ -79,40 +165,38 @@ export default class LightAppBridge {
             return peerId;
         });
         this._checkDeps(); // 依赖校验，缺失直接抛异常
-        this._bindListener(); // 绑定 native-call-js 监听
+        this._bindListener(); // 绑定消息监听（waltz 或 ipc，自动选择）
         this.connect(); // 构造即自动发起握手
     }
     /** 校验依赖是否就绪，缺失抛出明确异常 */
     _checkDeps() {
         const w = window;
-        if (!(w.waltz && w.waltz.event) || typeof w.waltz.event.on !== 'function') {
-            throw new Error('LightAppBridge 依赖 window.waltz.event.on，当前环境不可用');
-        }
         if (!getInvoke()) {
             throw new Error('LightAppBridge 依赖 window.worklink.invokeModuleMethodSync，当前环境不可用');
         }
         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 均不可用');
+        }
     }
-    /** 绑定 native-call-js 监听 */
+    /** 绑定消息监听：优先 waltz，回退 ipc（自动选择） */
     _bindListener() {
         if (this._started)
             return;
         this._started = true;
-        window.waltz.event.on('native-call-js', (raw) => this._onRaw(raw));
+        const backend = pickMessageBackend();
+        this._unlisten = backend((msg) => this._onMessage(msg));
     }
     /** 构造消息信封 */
     _envelope(type, data, id = genId()) {
         return { __sdk: SDK_ID, v: PROTOCOL_VERSION, id, type, data };
     }
-    /** 处理一条原生消息 */
-    _onRaw(raw) {
-        if (!raw || !raw.body || raw.body.eventName !== 'plugin-message')
-            return;
-        const params = raw.body.params || {};
-        const envelope = params.message;
-        const fromId = params.fromWebContentsId != null ? params.fromWebContentsId : null;
+    /** 处理一条归一化后的消息 */
+    _onMessage(msg) {
+        const envelope = msg.envelope;
+        const fromId = msg.fromWebContentsId;
         if (!isBridgeMsg(envelope))
             return;
         switch (envelope.type) {
@@ -324,6 +408,29 @@ export default class LightAppBridge {
                 this._messageHandlers.splice(i, 1);
         };
     }
+    /** 销毁实例：解绑消息监听、清空待处理请求、停止握手重试 */
+    destroy() {
+        if (this._unlisten) {
+            try {
+                this._unlisten();
+            }
+            catch { /* ignore */ }
+            this._unlisten = null;
+        }
+        this._clearHelloTimer();
+        if (this._handshakeTimer) {
+            clearTimeout(this._handshakeTimer);
+            this._handshakeTimer = null;
+        }
+        // 拒绝所有未完成的请求
+        this._pending.forEach((p) => {
+            clearTimeout(p.timer);
+            p.reject(new Error('实例已销毁'));
+        });
+        this._pending.clear();
+        this._messageHandlers.length = 0;
+        this._connectCbs.length = 0;
+    }
 }
 /**
  * 工厂函数

package/package.json

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