跳至主要內容

插件上下文

大约 3 分钟

插件上下文

PluginContext 提供插件与 WebCAD 交互的 API。

命令注册

import type { PluginContext, CommandOptions } from 'vjcad';
import { Engine, Point2D, LineEnt } from 'vjcad';

// 命令类
class DrawCrossCommand {
  async main(): Promise<void> {
    const size = 50;
    const center = new Point2D(0, 0);
    
    const hLine = new LineEnt(
      new Point2D(center.x - size, center.y),
      new Point2D(center.x + size, center.y)
    );
    const vLine = new LineEnt(
      new Point2D(center.x, center.y - size),
      new Point2D(center.x, center.y + size)
    );
    
    hLine.setDefaults();
    vLine.setDefaults();
    
    Engine.addEntities([hLine, vLine], { recordUndo: true });
    Engine.pcanvas.regen();
  }
}

// 在onActivate中注册
async onActivate(context: PluginContext): Promise<void> {
  const options = new CommandOptions();
  
  context.registerCommand(
    'DRAWCROSS',
    '绘制十字',
    DrawCrossCommand,
    options
  );
}

// 在onDeactivate中注销
async onDeactivate(context: PluginContext): Promise<void> {
  context.unregisterCommand('DRAWCROSS');
}

图标注册

async onActivate(context: PluginContext): Promise<void> {
  // 注册SVG图标
  const svgIcon = `<svg viewBox="0 0 24 24">
    <line x1="4" y1="12" x2="20" y2="12" stroke="currentColor" stroke-width="2"/>
    <line x1="12" y1="4" x2="12" y2="20" stroke="currentColor" stroke-width="2"/>
  </svg>`;
  
  context.registerIcon('DRAWCROSS', svgIcon);
}

Ribbon 菜单扩展

添加按钮

import type { RibbonButtonConfig, RibbonGroupConfig, RibbonTabConfig } from 'vjcad';

async onActivate(context: PluginContext): Promise<void> {
  // 添加按钮到现有组
  const button: RibbonButtonConfig = {
    cmd: 'DRAWCROSS',
    label: '十字',
    icon: 'DRAWCROSS',
    tooltip: '绘制十字标记'
  };
  context.addRibbonButton('home', 'draw', button, 'primary');
}

添加组

// 添加新组到现有标签页
const group: RibbonGroupConfig = {
  id: 'my-tools',
  label: '我的工具',
  primaryButtons: [
    { cmd: 'DRAWCROSS', label: '十字' },
    { cmd: 'MYCMD2', label: '命令2' }
  ],
  moreButtons: []
};
context.addRibbonGroup('home', group);

添加标签页

// 添加新标签页
const tab: RibbonTabConfig = {
  id: 'my-plugin-tab',
  label: '我的插件',
  groups: [
    {
      id: 'main-group',
      label: '主要功能',
      primaryButtons: [
        { cmd: 'DRAWCROSS', label: '十字' }
      ]
    }
  ]
};
context.addRibbonTab(tab, 'home');  // 在home标签后插入

移除 UI 元素

async onDeactivate(context: PluginContext): Promise<void> {
  context.removeRibbonTab('my-plugin-tab');
  context.removeRibbonGroup('home', 'my-tools');
  context.removeRibbonButton('home', 'draw', 'DRAWCROSS');
}

菜单栏扩展

添加菜单项到现有菜单

async onActivate(context: PluginContext): Promise<void> {
  // 注册命令和图标
  context.registerCommand('MYCMD', '我的命令', MyCommand);
  context.registerIcon('MYCMD', '<svg>...</svg>');  // 菜单使用同名图标
  
  // 添加到工具菜单
  context.addMenuItem('tool', {
    command: 'MYCMD',
    shortcut: 'Ctrl+M'  // 可选快捷键提示
  });
}

创建新主菜单

async onActivate(context: PluginContext): Promise<void> {
  // 创建主菜单（如果不存在）
  context.addMenu({
    id: 'my-tools',
    label: '我的工具',
    after: 'tool'  // 在工具菜单后
  });
  
  // 添加菜单项
  context.addMenuItem('my-tools', { command: 'MYCMD1' });
  context.addMenuItem('my-tools', { command: 'MYCMD2' });
}

async onDeactivate(context: PluginContext): Promise<void> {
  context.removeMenuItem('my-tools', 'MYCMD1');
  context.removeMenuItem('my-tools', 'MYCMD2');
  context.removeMenu('my-tools');
}

详细说明请参考 菜单栏与 Ribbon 扩展

事件监听

import { CadEvents } from 'vjcad';

async onActivate(context: PluginContext): Promise<void> {
  // 监听实体添加事件
  context.on(CadEvents.EntityAdded, (args) => {
    console.log('实体已添加:', args.entity.type);
  });
  
  // 监听命令执行
  context.on(CadEvents.CommandStarted, (args) => {
    console.log('命令开始:', args.commandName);
  });
  
  // 一次性监听
  context.once(CadEvents.DocumentOpened, (args) => {
    console.log('文档已打开:', args.document.name);
  });
}

数据存储

interface PluginSettings {
  defaultSize: number;
  autoSave: boolean;
}

async onActivate(context: PluginContext): Promise<void> {
  // 读取存储的设置
  const settings = context.getStorageItem<PluginSettings>('settings');
  if (settings) {
    console.log('默认尺寸:', settings.defaultSize);
  }
  
  // 保存设置
  context.setStorageItem<PluginSettings>('settings', {
    defaultSize: 100,
    autoSave: true
  });
  
  // 删除数据
  context.removeStorageItem('old-key');
}

PluginContext API

命令相关

方法说明
registerCommand(name, desc, cls, opt)注册命令
unregisterCommand(name)注销命令
executeCommand(name)执行命令
getRegisteredCommands()获取已注册命令

菜单相关

方法说明
addMenu(config)添加主菜单（已存在则跳过）
removeMenu(menuId)移除主菜单
addMenuItem(menuId, config)添加菜单项到指定菜单
removeMenuItem(menuId, command)移除菜单项

Ribbon 相关

方法说明
registerIcon(name, svg)注册图标
addRibbonButton(tab, group, btn, type)添加按钮
removeRibbonButton(tab, group, cmd)移除按钮
addRibbonGroup(tab, group)添加组
removeRibbonGroup(tab, groupId)移除组
addRibbonTab(tab, afterId)添加标签（已存在则跳过）
removeRibbonTab(tabId)移除标签

事件相关

方法说明
on(event, handler)监听事件
off(event, handler)取消监听
once(event, handler)一次性监听

存储相关

方法说明
getStorageItem<T>(key)读取数据
setStorageItem<T>(key, value)保存数据
removeStorageItem(key)删除数据

下一步