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

package/.prettierrc

@@ -1,8 +1,8 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "tabWidth": 2,
-  "trailingComma": "es5",
-  "printWidth": 100,
-  "endOfLine": "auto"
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "endOfLine": "auto"
 }

package/CHANGELOG.md

@@ -1,13 +1,17 @@
-## 发布日志
-
-#### 0.3.0
-
-- 兼容 CC 方法调用中需要监听异步回调事件，才能在回调事件中返回返回值
-
-#### 0.2.0
-
-- 兼容 SU 事件取消后，回调函数继续被调用时，函数不存在报错
-
-#### 0.1.0
-
-第一版 SDK
+## 发布日志
+
+#### 0.4.0
+
+- 从js迁移到ts，SDK支持类型系统
+
+#### 0.3.0
+
+- 兼容 CC 方法调用中需要监听异步回调事件，才能在回调事件中返回返回值
+
+#### 0.2.0
+
+- 兼容 SU 事件取消后，回调函数继续被调用时，函数不存在报错
+
+#### 0.1.0
+
+第一版 SDK

package/README.md

@@ -1,68 +1,95 @@
-## ECS-BRIDGE-SDK
-
-ECSHub Panel 存在与多个宿主环境交互的场景，因此抽离出桥接的 SDK，以适配不同宿主环境。
-
-已支持：
-
-- [x] SketchUp
-- [ ] QT
-- [x] Web(for test)
-- [ ] Rhino
-- [-] Concetto
-
-### 前置项
-
-- node >= 16
-
-### 使用示例
-
-```js
-import ECSHubBridge from '@glodon-ecs/web-bridge-sdk';
-
-// 使用示例
-async function main() {
-  // initialize 方法需要先被调用
-  // await ECSHubBridge.initialize(); // 自动检测初始化，QT、SU、Web环境
-  const options = { env: 'sketchup', logger: window.console }; // options 可选
-  await ECSHubBridge.initialize(options);
-  const bridge = ECSHubBridge.getInstance();
-
-  // 调用方法
-  const data = await bridge.callMethod('getInitialData', 'param1');
-
-  // 订阅
-  const unsubscribe = bridge.subscribe('modelChanged', (data) => {});
-}
-```
-
-#### 扩展适配器
-
-> 需要实现如下三个内部方法
-
-```js
-class CADAdapter {
-  // 初始方法
-  async init() {
-    this.client = window.CADPlugin; // 假设第三方CAD插件
-  }
-
-  // 调用内部函数
-  call(method, args, options) {
-    return this.client.execCommand(method, args, options);
-  }
-
-  // 注册事件监听
-  onEvent(event, callback) {
-    this.client.on(event, callback);
-    return () => this.client.off(event, callback);
-  }
-}
-
-// 注入自定义适配器
-await ECSHubBridge.initialize();
-ECSHubBridge.setAdapter(new CADAdapter(), 'cad');
-
-// 设置自定义适配器的client交互对象，如 ecsClient
-await ECSHubBridge.initialize();
-ECSHubBridge.setAdapterClient(new ECS({...}));
-```
+## ECS-BRIDGE-SDK
+
+ECSHub Panel 存在与多个宿主环境交互的场景，因此抽离出桥接的 SDK，以适配不同宿主环境。
+
+已支持：
+
+- [x] SketchUp
+- [ ] QT
+- [ ] Web(for test)
+- [ ] Rhino
+- [x] Concetto
+
+### 前置项
+
+- node >= 16
+
+### 安装
+
+```bash
+npm install @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: BridgeEnv.sketchup, logger: window.console }; // options 可选
+  await ECSHubBridge.initialize(options);
+  const bridge = ECSHubBridge.getInstance();
+
+  // 调用方法
+  const data = await bridge.callMethod('getInitialData', 'param1');
+
+  // 订阅
+  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';
+
+class CADAdapter extends BaseAdapter {
+  // 初始方法
+  async init() {
+    this.client = window.CADPlugin; // 假设第三方CAD插件
+  }
+
+  // 调用内部函数
+  async call(method: string, args: unknown[]) {
+    return this.client.execCommand(method, ...args);
+  }
+
+  // 注册事件监听
+  onEvent(event: string, callback: (...args: unknown[]) => void) {
+    this.client.on(event, callback);
+    return () => this.client.off(event, callback);
+  }
+}
+
+// 注入自定义适配器
+await ECSHubBridge.initialize();
+ECSHubBridge.setAdapter(new CADAdapter(), 'cad');
+
+// 设置自定义适配器的 client 交互对象，如 ecsClient
+await ECSHubBridge.initialize();
+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,135 @@
+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"
+}
+
+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);
+    /**
+     * 环境检测
+     * @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 { }