@glodon-ecs/web-bridge-sdk 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## 发布日志
 
+#### 0.5.0
+
+- 支持CCWeb(qiankun)
+
+#### 0.4.0
+
+- 从js迁移到ts，SDK支持类型系统
+
 #### 0.3.0
 
 - 兼容 CC 方法调用中需要监听异步回调事件，才能在回调事件中返回返回值

package/README.md

@@ -4,26 +4,34 @@ ECSHub Panel 存在与多个宿主环境交互的场景，因此抽离出桥接
 
 已支持：
 
-- [x] SketchUp
+- [√] SketchUp
 - [ ] QT
-- [x] Web(for test)
+- [ ] Web(for test)
 - [ ] Rhino
-- [-] Concetto
+- [√] Concetto
+- [√] ConcettoWeb
 
 ### 前置项
 
 - node >= 16
 
+### 安装
+
+```bash
+npm install @glodon-ecs/web-bridge-sdk
+```
+
 ### 使用示例
 
-```js
-import ECSHubBridge from '@glodon-ecs/web-bridge-sdk';
+```ts
+import ECSHubBridge, { BridgeEnv } from '@glodon-ecs/web-bridge-sdk';
+// 或使用命名导入：import { ECSHubBridge, BridgeEnv } from "@glodon-ecs/web-bridge-sdk";
 
 // 使用示例
 async function main() {
   // initialize 方法需要先被调用
   // await ECSHubBridge.initialize(); // 自动检测初始化，QT、SU、Web环境
-  const options = { env: 'sketchup', logger: window.console }; // options 可选
+  const options = { env: BridgeEnv.sketchup, logger: window.console }; // options 可选
   await ECSHubBridge.initialize(options);
   const bridge = ECSHubBridge.getInstance();
 
@@ -32,27 +40,33 @@ async function main() {
 
   // 订阅
   const unsubscribe = bridge.subscribe('modelChanged', (data) => {});
+
+  // 取消订阅
+  unsubscribe();
 }
 ```
 
 #### 扩展适配器
 
-> 需要实现如下三个内部方法
+> 继承 `BaseAdapter` 并实现三个抽象方法
+
+```ts
+import { BaseAdapter } from '@glodon-ecs/web-bridge-sdk';
+import type { LoggerType } from '@glodon-ecs/web-bridge-sdk';
 
-```js
-class CADAdapter {
+class CADAdapter extends BaseAdapter {
   // 初始方法
   async init() {
     this.client = window.CADPlugin; // 假设第三方CAD插件
   }
 
   // 调用内部函数
-  call(method, args, options) {
-    return this.client.execCommand(method, args, options);
+  async call(method: string, args: unknown[]) {
+    return this.client.execCommand(method, ...args);
   }
 
   // 注册事件监听
-  onEvent(event, callback) {
+  onEvent(event: string, callback: (...args: unknown[]) => void) {
     this.client.on(event, callback);
     return () => this.client.off(event, callback);
   }
@@ -62,7 +76,21 @@ class CADAdapter {
 await ECSHubBridge.initialize();
 ECSHubBridge.setAdapter(new CADAdapter(), 'cad');
 
-// 设置自定义适配器的client交互对象，如 ecsClient
+// 设置自定义适配器的 client 交互对象，如 ecsClient
 await ECSHubBridge.initialize();
-ECSHubBridge.setAdapterClient(new ECS({...}));
+ECSHubBridge.setAdapterClient(client);
+```
+
+### 导出列表
+
+| 导出            | 类型            | 说明                                                       |
+| --------------- | --------------- | ---------------------------------------------------------- |
+| `ECSHubBridge`  | class (default) | 桥接器主类                                                 |
+| `BridgeEnv`     | enum            | 环境枚举：`qt` / `web` / `sketchup` / `concetto` / `rhino` |
+| `BaseAdapter`   | abstract class  | 适配器基类，扩展适配器时继承                               |
+| `BridgeOptions` | interface       | 初始化配置项类型                                           |
+| `LoggerType`    | type            | 日志对象类型                                               |
+
+```
+
 ```

package/lib/index.d.ts

@@ -0,0 +1,137 @@
+export declare abstract class BaseAdapter {
+    protected logger: LoggerType;
+    protected client: Client;
+    constructor(logger: LoggerType);
+    /**
+     * 初始化适配器
+     * @abstract
+     */
+    abstract init(): Promise<void>;
+    /**
+     * 调用宿主环境方法
+     * @abstract
+     * @param {string} methodName - 方法名称
+     * @param {Array} args - 参数数组
+     * @options
+     */
+    abstract call(methodName: string, args?: unknown, options?: {
+        eventName?: string;
+    } & Record<string, unknown>): Promise<unknown>;
+    /**
+     * 订阅事件
+     * @abstract
+     * @param {string} eventName - 事件名称
+     * @param {Function} callback - 回调函数
+     * @returns {Function} 取消订阅函数
+     */
+    abstract onEvent(eventName: string, callback: (args: unknown) => void): () => void;
+    setClient(client: Client): void;
+}
+
+export declare enum BridgeEnv {
+    qt = "qt",
+    web = "web",
+    sketchup = "sketchup",
+    concetto = "concetto",
+    rhino = "rhino",
+    qiankun = "qiankun"
+}
+
+export declare interface BridgeOptions {
+    env?: BridgeEnv;
+    logger?: LoggerType;
+}
+
+declare type Client = Record<string, unknown> | null;
+
+/**
+ * ECSHub多环境桥接器
+ */
+declare class ECSHubBridge {
+    private static _instance;
+    protected _subscriptions: Map<(...args: unknown[]) => void, () => void>;
+    protected _isInitialized: boolean;
+    protected _logger: LoggerType;
+    protected _env: string;
+    protected _adapter: BaseAdapter;
+    /**
+     * @param {BridgeOptions} [options={}] 配置选项
+     * @param {BridgeEnv} [options.env] 强制指定环境
+     * @param {LoggerType} [options.logger] 日志输出对象
+     */
+    constructor(options?: BridgeOptions);
+    _isQiankun(): boolean;
+    /**
+     * 环境检测
+     * @private
+     */
+    _detectEnv(forceEnv?: BridgeEnv): string;
+    /**
+     * 创建适配器实例
+     * @private
+     */
+    _createAdapter(env: string, logger: LoggerType): BaseAdapter;
+    /**
+     * 初始化桥接器
+     * @async
+     */
+    static initialize(options?: BridgeOptions): Promise<void>;
+    /**
+     * 调用宿主环境方法
+     * @async
+     * @param {string} methodName 方法名称
+     * @param {...unknown} args 参数列表
+     *  options 可选参数
+     */
+    callMethod(methodName: string, args?: unknown, options?: {
+        eventName?: string;
+    } & Record<string, unknown>): Promise<unknown>;
+    /**
+     * 订阅事件
+     * @param {string} eventName 事件名称
+     * @param {Function} callback 回调函数
+     * @returns {Function} 取消订阅函数
+     */
+    subscribe(eventName: string, callback: (args: unknown) => void): () => void;
+    /**
+     * 取消订阅
+     * @param {Function} callback 要取消的回调函数
+     */
+    unsubscribe(callback: (args: unknown) => void): void;
+    /**
+     * 获取当前环境
+     * @static
+     */
+    static getCurrentEnv(): string;
+    /**
+     * 获取桥接器实例
+     * @static
+     */
+    static getInstance(): ECSHubBridge;
+    /**
+     * 设置自定义适配器
+     * @static
+     * @param {BaseAdapter} adapter 适配器实例
+     * @param {string} [env='custom'] 环境标识
+     */
+    static setAdapter(adapter: BaseAdapter, env?: string): void;
+    /**
+     * 设置ECS交互client对象
+     * @static
+     * @param {Record<string, unknown>} client 实例
+     */
+    static setAdapterClient(client: Record<string, unknown> | null): void;
+}
+export { ECSHubBridge }
+export default ECSHubBridge;
+
+export declare type LoggerType = {
+    enable: boolean;
+    level: number;
+    log: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+
+export { }