@kudashi/kds-api-bridge-core

酷大师 3D 建模软件的跨环境通信核心库

概述

@kudashi/kds-api-bridge-core 是酷大师 3D 建模软件的底层通信库，用于实现插件 UI 与插件沙盒之间的跨环境通信。它封装了底层的 postMessage 机制，提供了可靠的异步通信、函数调用和数据同步功能，是开发酷大师插件的基础组件。

功能特性

• 跨环境通信：实现插件 UI 与插件沙盒之间的双向通信
• 函数调用：支持远程函数调用和回调处理
• 数据同步：提供对象属性的双向同步机制
• 类型安全：基于 TypeScript 开发，提供完整的类型定义
• 错误处理：完善的错误捕获和处理机制
• 轻量级：体积小巧，无冗余依赖

安装

# 使用npm
npm install @kudashi/kds-api-bridge-core

# 使用yarn
yarn add @kudashi/kds-api-bridge-core

核心类与 API

BridgeChannel 基础使用

BridgeChannel 是跨环境通信的核心类，用于建立和管理两个环境之间的通信通道。以下是插件 UI 与沙盒通信的基础示例：

// 在插件沙盒中
import { BridgeChannel } from '@kudashi/kds-api-bridge-core';

// 创建通信通道
const channel = new BridgeChannel('plugin-channel');

// 注册供UI调用的函数
channel.registerFunc('getSceneInfo', () => {
    return {
        objects: 10,
        materials: 5,
        lights: 2,
    };
});

// 监听UI发送的消息
channel.registerFunc('updateObject', (objectId: string, params: any) => {
    // 更新3D场景中的对象
    return { success: true };
});

// 在插件UI中
import { BridgeChannel } from '@kudashi/kds-api-bridge-core';

// 创建与沙盒相同ID的通信通道
const channel = new BridgeChannel('plugin-channel');

// 调用沙盒中的函数
async function getSceneData() {
    try {
        const sceneInfo = await channel.invoke('getSceneInfo');
        console.log('Scene info:', sceneInfo);
    } catch (error) {
        console.error('Error getting scene info:', error);
    }
}

// 发送更新消息到沙盒
async function update3DObject(objectId: string, params: any) {
    try {
        const result = await channel.invoke('updateObject', [objectId, params]);
        console.log('Update result:', result);
    } catch (error) {
        console.error('Error updating object:', error);
    }
}

BridgeChannel 实例隔离设计 (进阶)

在实际插件开发中，我们通常需要管理多个 UI 组件与沙盒之间的通信。BridgeChannel 的核心设计是每个 Widget 实例独立持有一个通道实例，并使用 Widget 的唯一 ID 作为通道标识符。这种设计确保了不同 Widget 之间的通信互不干扰。

import { BridgeChannel } from '@kudashi/kds-api-bridge-core';

export abstract class Widget {
    abstract type: string;
    readonly id: string;
    protected readonly bridge: BridgeChannel;

    protected constructor(id: string) {
        this.id = id;
        // 每个 Widget 实例创建独立的 BridgeChannel
        // 使用 Widget ID 作为通道标识符，确保通信隔离
        this.bridge = new BridgeChannel(id);

        // 注册当前 Widget 特有的远程函数
        this.bridge.registerFunc('setClickListener', (listenerConfig) => {
            // 处理特定于当前 Widget 的点击监听器
        });
    }

    // Widget 销毁时释放通道资源
    dispose() {
        this.bridge.dispose();
    }
}

实例隔离的优势

1. 通信隔离：每个 Widget 使用独立的通道，避免不同 Widget 之间的调用冲突
2. 资源隔离：每个 Widget 负责管理自己的通道生命周期，便于资源释放
3. 命名空间隔离：相同的函数名可以在不同 Widget 中使用而不会冲突
4. 插件沙盒与 UI 对应：插件沙盒中的每个 Widget 实例与 UI 中的对应实例通过唯一通道通信
5. 可扩展性：新增 Widget 类型无需担心与现有 Widget 通信冲突

实际应用示例

// 插件沙盒环境
const widget1 = new KPanelWidget('panel-1');
const widget2 = new KTopBarWidget('topbar-1');

// 插件 UI 环境
const uiWidget1 = new KPanelWidget('panel-1'); // 与沙盒中 panel-1 通信
const uiWidget2 = new KTopBarWidget('topbar-1'); // 与沙盒中 topbar-1 通信

// 调用只会在相同 ID 的 Widget 之间传递，互不干扰
uiWidget1.bridge.invoke('updateConfig', { visible: true });
uiWidget2.bridge.invoke('updateTitle', '新标题');

FunctionHandle

函数句柄类，用于管理函数引用和跨环境调用。

import { FunctionHandle } from '@kudashi/kds-api-bridge-core';

// 插件UI创建函数句柄
const handle = FunctionHandle.create((message: string) => {
    console.log('Received message:', message);
    return 'Message processed';
});

// 将函数ID传入插件沙盒
const functionId = handle.id;
postMessage({
    type: 'registerFunction',
    functionId,
});

// 插件沙盒内调用函数
const result = new FunctionHandle(functionId).invoke('Hello from bridge-core');
console.log('Function result:', result);

// 插件UI内同样可以调用
const result2 = handle.invoke('Hello from bridge-core');
console.log('Function result:', result2);

// 反之亦然，插件沙盒也可以创建函数句柄传递给插件UI调用

// 销毁函数句柄
handle.dispose();

注意事项

1. 确保在不同环境中使用相同的通道 ID 进行通信
2. 调用 dispose() 方法释放不再使用的资源，避免内存泄漏
3. 对于跨环境传递的复杂数据结构，确保其可序列化
4. 处理异步调用可能出现的错误

许可证

MIT © 酷大师团队