跳至主要內容

命令使用

黄曦大约 4 分钟Command命令

Visual Studio Code 命令使用指南

1. 命令概述

在 Visual Studio Code 中，命令（Command） 用于触发各类操作。无论是使用快捷键、点击菜单，还是通过扩展程序编程调用，最终都会落实到命令的执行上。

  • 内置命令：VS Code 自带大量命令，用于编辑、导航、控制界面等。
  • 扩展命令：扩展程序可以暴露自己的命令，供用户或其他扩展使用。

2. 使用命令

2.1 以编程方式执行命令

通过 vscode.commands.executeCommand API 可以在代码中直接执行任意命令。

示例：注释当前活动编辑器中的选中行（使用内置命令 editor.action.addCommentLine）。

import * as vscode from 'vscode';

function commentLine() {
  vscode.commands.executeCommand('editor.action.addCommentLine');
}

带参数与返回值：
某些命令需要传入参数，并可能返回结果。例如 vscode.executeDefinitionProvider 会返回定义列表。

import * as vscode from 'vscode';

async function printDefinitionsForActiveEditor() {
  const activeEditor = vscode.window.activeTextEditor;
  if (!activeEditor) return;

  const definitions = await vscode.commands.executeCommand<vscode.Location[]>(
    'vscode.executeDefinitionProvider',
    activeEditor.document.uri,
    activeEditor.selection.active
  );

  for (const definition of definitions) {
    console.log(definition);
  }
}

2.2 命令 URI

命令 URI 是一种特殊链接（格式为 command:<命令名>），可在悬停提示、补全详情、WebView 等位置作为可点击链接使用。

示例：在悬停提示中显示“添加注释”链接，点击后执行 editor.action.addCommentLine。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  vscode.languages.registerHoverProvider(
    'javascript',
    new (class implements vscode.HoverProvider {
      provideHover(
        _document: vscode.TextDocument,
        _position: vscode.Position,
        _token: vscode.CancellationToken
      ): vscode.ProviderResult<vscode.Hover> {
        const commentCommandUri = vscode.Uri.parse(`command:editor.action.addCommentLine`);
        const contents = new vscode.MarkdownString(`[Add comment](${commentCommandUri})`);
        // 必须将 isTrusted 设为 true 才能执行命令
        contents.isTrusted = true;
        return new vscode.Hover(contents);
      }
    })()
  );
}

传递参数：将参数以 JSON 数组形式编码后附加在 URI 的查询字符串中。

const args = [{ resourceUri: document.uri }];
const stageCommandUri = vscode.Uri.parse(
  `command:git.stage?${encodeURIComponent(JSON.stringify(args))}`
);
const contents = new vscode.MarkdownString(`[Stage file](${stageCommandUri})`);
contents.isTrusted = true;

WebView 支持：在创建 WebView 时，设置 enableCommandUris: true 即可启用命令 URI 点击。

3. 创建新命令

3.1 注册命令

使用 vscode.commands.registerCommand 将命令 ID 绑定到处理函数。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const command = 'myExtension.sayHello';

  const commandHandler = (name: string = 'world') => {
    console.log(`Hello ${name}!!!`);
  };

  context.subscriptions.push(
    vscode.commands.registerCommand(command, commandHandler)
  );
}

3.2 将命令暴露给用户（贡献命令）

仅注册命令不足以让用户在命令面板中看到它。你还需要在 package.json 的 contributes.commands 中声明。

{
  "contributes": {
    "commands": [
      {
        "command": "myExtension.sayHello",
        "title": "Say Hello"
      }
    ]
  }
}

注意：如果扩展兼容 VS Code 1.74.0 之前的版本，还必须在 activationEvents 中添加 onCommand:myExtension.sayHello，以确保扩展在命令调用前激活。

3.3 控制命令在命令面板中的显示

通过 menus.commandPalette 配合 when 条件，可以限制命令仅在特定场景下显示。

{
  "contributes": {
    "menus": {
      "commandPalette": [
        {
          "command": "myExtension.sayHello",
          "when": "editorLangId == markdown"
        }
      ]
    }
  }
}

上述配置使得 myExtension.sayHello 仅在当前文件为 Markdown 时显示在命令面板中。

3.4 命令的启用状态（Enablement）

使用 enablement 属性（值为 when 子句）来控制命令是否可点击。它适用于所有菜单和快捷键。

区分 enablement 与菜单 when：

  • when 决定菜单项是否显示，用于避免界面杂乱。
  • enablement 决定已显示的菜单项是否可用。
    命令面板会过滤掉禁用项，而编辑器上下文菜单则会显示为灰色不可用状态。
{
  "contributes": {
    "commands": [
      {
        "command": "myExtension.analyzeRegex",
        "title": "Analyze Regex",
        "enablement": "editorHasSelection && editorLangId == javascript"
      }
    ]
  }
}

3.5 自定义 when 子句上下文

如果现有的上下文键（如 editorLangId）不能满足需求，你可以通过 setContext 命令自定义上下文。

// 设置布尔值
vscode.commands.executeCommand('setContext', 'myExtension.showMyCommand', true);

// 设置数值，用于比较
vscode.commands.executeCommand('setContext', 'myExtension.numberOfCoolOpenThings', 2);

然后在 when 子句中使用：

"when": "myExtension.showMyCommand && myExtension.numberOfCoolOpenThings > 1"

4. 命令命名规范

  • 标题（Title） 采用标题式大小写（Title Case）。

    • 介词（如 on, to, in, of, with, for）若长度≤4个字母，不大写，除非位于首尾。
    • 以动词开头，描述操作。
    • 使用名词描述操作目标。
    • 避免在标题中出现“command”一词。

  • 命令 ID（Command ID） 通常采用小写字母与点号分隔的格式，例如 myExtension.sayHello。

5. 常用命令参考

本文档基于 VS Code 官方文档整理，涵盖了命令的核心用法和开发要点。