自定义命令

概览

使用命令的场景主要有下面两种:

插件

插件中可以通过下面例子的用法使用 OpenSumi 中的命令:

import { commands, Uri } from 'sumi';

// OpenSumi 针对插件进程的命令调用进行了特殊处理,真实执行时会将 `Uri` 转化为 `URI`
let uri = Uri.file('/some/path/to/folder');
let success = await commands.executeCommand('vscode.openFolder', uri);

模块

模块中可以通过下面例子的用法使用 OpenSumi 中的命令:

import { Injectable, Autowired } from '@opensumi/common-di';
import { CommandService, URI } from '@opensumi/ide-core-browser';

@Injectable()
class DemoModule {
  ...
  @Autowired(CommandService)
  private readonly commandService: CommandService;

  run () {
    let uri = new URI('/some/path/to/folder');
    await this.commandService.executeCommand('vscode.openFolder', uri);
  }

  ...
}

React 组件

在 React 组件中你可以使用 useInjectable 来获取到命令服务:

import React from 'react';

import { useInjectable, FILE_COMMANDS } from '@opensumi/ide-core-browser';
import { localize, CommandService } from '@opensumi/ide-core-common';

export const DemoView = () => {
  const commandService: CommandService = useInjectable(CommandService);

  const openFolder = () => {
    commandService.executeCommand(FILE_COMMANDS.OPEN_FOLDER.id, { newWindow: false });
  };

  return (
    <a className={styles.empty_button} onClick={openFolder}>
      {localize('file.empty.openFolder')}
    </a>
  );
};

内置命令

在 OpenSumi 框架中,内置了许多基础命令,在需要实现时,你可以先到对应模块查找一下对应实现,避免重复劳动。常用的一些内置命令如下:

命令功能参数
revealInExplorer在资源管理器界面定位文件uri: URI
setContext设置 Context 变量值key:键, value:值
workbench.action.closeActiveEditor关闭当前激活的编辑器
workbench.action.revertAndCloseActiveEditor恢复当前文件内容同时关闭激活的编辑器
workbench.action.splitEditorRight向右拆分当前编辑器
workbench.action.splitEditorDown向下拆分当前编辑器
workbench.action.files.newUntitledFile新建临时的编辑器文件
workbench.action.closeAllEditors关闭所有编辑器
workbench.action.closeOtherEditors关闭其他编辑器
workbench.action.files.save保存当前文件
workbench.action.splitEditor打开文件并向右拆分resource : ResourceArgs
workbench.action.splitEditorOrthogonal打开文件并向下拆分resource : ResourceArgs
workbench.action.navigateLeft切换到左侧编辑器
workbench.action.navigateUp切换到顶部编辑器
workbench.action.navigateRight切换到右侧编辑器
workbench.action.navigateDown切换到底部编辑器
workbench.action.navigateEditorGroups切换编辑器组
workbench.action.nextEditor切换至下个文件
workbench.action.previousEditor切换至上个文件
workbench.action.openEditorAtIndex通过下标位置打开编辑器
workbench.action.files.revert恢复当前激活的文件内容
workbench.action.terminal.clear清理当前激活的终端窗口内容
workbench.action.terminal.toggleTerminal打开/关闭 终端窗口
workbench.files.action.focusFilesExplorer打开激活的编辑器组
vscode.open打开文件(仅在 Electron 下可用)uri: URI, newWindow: boolean
vscode.openFolder打开文件夹(仅在 Electron 下可用)uri: URI, newWindow: boolean
workbench.action.reloadWindow (reload_window)重载窗口
copyFilePath复制文件绝对路径uri: URI
copyRelativeFilePath复制文件相对路径uri: URI
workbench.action.openSettings打开设置面板
workbench.action.navigateBack前往上一个编辑器
workbench.action.navigateForward前往下一个编辑器
workbench.action.files.saveAll保存全部文件
workbench.action.debug.stepInto调试步入
workbench.action.debug.stepOut调试步出
workbench.action.debug.stepOver调试步进
workbench.action.debug.continue调试继续
workbench.action.debug.run (workbench.action.debug.start)调试运行
workbench.action.debug.pause调试暂停
workbench.action.debug.restart调试重启
workbench.action.debug.stop调试终止
workbench.action.showAllSymbols展示所有符号

注册自定义命令

注册自定义命令的方式同样也存在两种方式:

通过插件注册

插件注册主要依赖 commands 贡献点,详细文档可见:contributes.commands

在插件的 package.json 声明自定义命令的简单例子如下:

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": {
          "light": "path/to/light/icon.svg",
          "dark": "path/to/dark/icon.svg"
        }
      }
    ]
  }
}

声明的好处是能够让该命令“显式”的存在于框架中,即通过 ⇧⌘P 打开快速导航面板,或是在菜单中都能找到其位置,没有声明直接进行注册的命令将不会出现在上述面板中。

// sumi 自有插件 API
import * as sumi from 'sumi';

export async function activate(context: sumi.ExtensionContext) {
  context.subscriptions.push(
    sumi.commands.registerCommand('extension.sayHello', async () => {
      sumi.window.showInformationMessage('Hello World');
    })
  );
}

通过模块注册

在模块中,我们通常采用 CommandContribution 进行注册,详细可见文档:命令注册