跳至主要內容

插件基础

大约 3 分钟

插件基础

WebCAD 提供完善的插件系统，支持扩展命令、UI 和功能。

在线示例

示例描述链接
基本插件插件结构示例在线演示{target="_blank"}
校验插件数据校验示例在线演示{target="_blank"}
标准插件PluginManager 标准写法在线演示{target="_blank"}

Plugin 接口

import type { Plugin, PluginManifest, PluginContext } from 'vjcad';

// 插件清单
const manifest: PluginManifest = {
  id: 'my-plugin',              // 唯一标识符
  name: '我的插件',              // 显示名称
  version: '1.0.0',             // 版本号
  author: '作者名',
  description: '插件描述',
  keywords: ['工具', 'CAD'],
  dependencies: [],              // 依赖的其他插件
  minEngineVersion: '1.0.0'     // 最低引擎版本
};

// 插件定义
const myPlugin: Plugin = {
  manifest,
  
  // 插件加载时调用（初始化，不激活功能）
  async onLoad(context: PluginContext): Promise<void> {
    console.log('插件已加载');
  },
  
  // 插件激活时调用（注册命令、菜单等）
  async onActivate(context: PluginContext): Promise<void> {
    console.log('插件已激活');
  },
  
  // 插件停用时调用（清理资源）
  async onDeactivate(context: PluginContext): Promise<void> {
    console.log('插件已停用');
  },
  
  // 插件卸载时调用（最终清理）
  async onUnload(context: PluginContext): Promise<void> {
    console.log('插件已卸载');
  }
};

export default myPlugin;

PluginManifest

插件清单描述插件的基本信息：

属性类型必填说明
idstring是唯一标识符
namestring是显示名称
versionstring是版本号
authorstring否作者
descriptionstring否描述
keywordsstring[]否关键字
dependenciesstring[]否依赖插件ID
minEngineVersionstring否最低引擎版本
homepagestring否主页URL
iconstring否图标

PluginState 状态

enum PluginState {
  Unloaded = 'unloaded',      // 未加载
  Loading = 'loading',         // 正在加载
  Loaded = 'loaded',           // 已加载未激活
  Activating = 'activating',   // 正在激活
  Active = 'active',           // 已激活
  Deactivating = 'deactivating', // 正在停用
  Unloading = 'unloading',     // 正在卸载
  Error = 'error'              // 出错
}

生命周期

生命周期钩子

钩子调用时机用途
onLoad插件加载时初始化、检查依赖、注册资源
onActivate插件激活时注册命令、添加 UI、启动功能
onDeactivate插件停用时注销命令、移除 UI、暂停功能
onUnload插件卸载时最终清理、释放资源、断开连接

生命周期事件

插件管理器在每个状态转换时会触发相应的事件：

事件触发时机
PluginLoading开始加载插件前
PluginLoaded插件加载完成后
PluginActivating开始激活插件前
PluginActivated插件激活完成后
PluginDeactivating开始停用插件前
PluginDeactivated插件停用完成后
PluginUnloading开始卸载插件前
PluginUnloaded插件卸载完成后
PluginError插件发生错误时
import { Engine, CadEvents } from 'vjcad';

// 监听插件加载事件
Engine.eventManager.on(CadEvents.PluginLoaded, (args) => {
  console.log('插件已加载:', args.pluginId);
});

// 监听插件卸载事件
Engine.eventManager.on(CadEvents.PluginUnloaded, (args) => {
  console.log('插件已卸载:', args.pluginId);
});

// 监听插件错误
Engine.eventManager.on(CadEvents.PluginError, (args) => {
  console.error('插件错误:', args.pluginId, args.error);
});

下一步