命令

命令在Visual Studio Code中触发操作。如果你曾经配置过一个快捷键，那么你已经使用过命令。命令也被扩展用来向用户暴露功能，绑定到VS Code用户界面中的操作，并实现内部逻辑。

使用命令

VS Code 包含了一大套内置命令，您可以使用这些命令与编辑器进行交互、控制用户界面或执行后台操作。许多扩展也将其核心功能暴露为命令，供用户和其他扩展利用。

通过程序执行命令

该vscode.commands.executeCommandAPI 以编程方式执行命令。这使您可以使用 VS Code 的内置功能，并基于 VS Code 的内置 Git 和 Markdown 扩展等扩展进行开发。

该编辑器操作：添加注释行命令，例如，注释掉当前在活动文本编辑器中选择的行：

导入 * 为 vscode 来自 'vscode';

函数 注释行() {
  vscode.commands.执行命令('编辑器操作.添加注释行');
}

一些命令需要参数来控制其行为。命令还可能返回结果。类似API的vscode执行定义提供者命令，例如，查询文档中给定位置的定义。它接受一个文档URI和一个位置作为参数，并返回一个包含定义列表的承诺：

导入 * 为 vscode 来自 '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
  );

  对于 (常量 定义 的 定义) {
    控制台.日志(定义);
  }
}

查找可用命令：

命令 URIs

Commands URIs 是执行给定命令的链接。它们可以作为悬停文本、完成项详情或网页视图中的可点击链接使用。

命令 URI 使用 命令方案后跟命令名称。该命令的URI为编辑器操作：添加注释行命令，例如，是命令: 编辑器操作.添加注释行. 这是一个悬停提供程序，它在当前行的活动文本编辑器的注释中显示一个链接：

导入 * 为 vscode 来自 '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})`);

        // 要在Markdown内容中启用命令URI，必须设置`isTrusted`标志。
        // 在创建受信任的Markdown字符串时，请确保正确清理所有
        // 输入内容，以确保仅执行预期的命令URI
        内容.isTrusted = true;

        返回 新的 vscode.悬停(内容);
      }
    })()
  );
}

命令的参数列表以已正确进行URI编码的JSON数组传递：下面的示例使用git.阶段命令以创建一个悬停链接，将当前文件暂存：

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 args = [{ resourceUri: document.uri }];
        const stageCommandUri = vscode.Uri.parse(
          `command:git.stage?${encodeURIComponent(JSON.stringify(args))}`
        );
        const contents = new```plaintext
vscode
.
MarkdownString
(
  Stage file(${stageCommandUri})
);
        contents
        .isTrusted = true;
        return new vscode.Hover(contents);
      }
    })();
```

您可以通过设置在 webviews 中启用命令 URIs 启用命令URI在网页视图选项当WebView创建时。

创建新命令

注册命令

vscode.commands注册命令将命令 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}!!!`);
  };

  上下文.订阅.推送(vscode.命令.注册命令(命令, 命令处理程序));
}

处理函数将在任何时候被调用myExtension.说你好命令被执行，无论是通过编程方式执行命令，从 VS Code 用户界面，或通过快捷键。

创建用户命令

vscode.commands注册命令仅将命令ID绑定到处理函数。为了在命令面板中暴露该命令以便用户可以发现，您还需要一个相应的命令。贡献在你的扩展中package.json输入：

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

该命令 贡献告诉 VS Code 您的扩展提供了一个给定的命令，并且应在该命令被调用时激活，并且还允许您控制该命令在用户界面中的显示方式。在创建命令时，请确保遵循命令命名规范。

命令面板中的贡献命令

现在当用户首次调用myExtension.说你好通过命令面板发出命令或通过快捷键，扩展将被激活并且注册命令将绑定myExtension.说你好到合适的处理人员。

注意：针对 VS Code 1.74.0 之前的版本的扩展必须显式注册一个在命令 激活事件对于所有面向用户的命令，以便激活扩展注册命令执行：
{
  "激活事件": ["onCommand:myExtension sayHello"]
}

你不需要一个在命令激活内部命令的事件，但您必须为任何满足以下条件的命令定义：

可以通过命令面板调用。
可以通过快捷键调用。
可以通过 VS Code 用户界面调用，例如通过编辑器标题栏。
旨在作为其他扩展消费的API。

控制命令在命令面板中显示的时间

默认情况下，所有通过贡献的用户界面暴露的命令命令部分package.json显示在命令面板中。然而，许多命令仅在某些情况下才相关，例如，当有活动的特定语言文本编辑器或用户设置了一定的配置选项时。

该菜单.命令面板 contribution point 允许你限制命令在命令面板中显示的时间。它接受目标命令的ID和一个when子句，用于控制命令的显示时间：

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

现在myExtension.说你好命令只有在用户处于Markdown文件中时才会显示在命令面板中。

启用命令

命令支持通过一个启用功能启用 属性 - 其值为一个 when-clause。启用适用于所有菜单和已注册的键绑定。

注意：存在语义重叠启用和当 菜单项的状态。后者用于防止菜单中充满禁用的项目。例如，分析JavaScript正则表达式的命令应在文件是JavaScript时显示，并且只有在光标位于正则表达式上时才应启用。 当该条款防止混乱，通过不显示所有其他语言文件的命令。建议防止菜单混乱。

最后，显示命令的菜单，如命令面板或上下文菜单，实现了不同的启用/禁用处理方式。编辑器和资源管理器的上下文菜单在命令面板过滤这些项目时渲染启用/禁用项目。

使用自定义when子句上下文

如果你正在编写自己的 VS Code 扩展，并且需要通过使用来启用/禁用命令、菜单或视图当如果条款上下文和现有的键都不符合您的需求，那么您可以添加自己的上下文。

下面的第一个示例设置了键myExtension显示我的命令设置为 true，这可以用于启用命令或与当属性。第二个示例存储一个值，您可以将其用于当检查冷门开放事物的数量是否大于2的条款。

vscode.commands.executeCommand('setContext', 'myExtension.showMyCommand', true);

vscode.commands.executeCommand('setContext', 'myExtension.numberOfCoolOpenThings', 2);

命名约定

在创建命令时，您应遵循以下命名约定：

命令标题
- 使用标题风格的 capitalization。不要大写四个或更少字母的介词（如 on、to、in、of、with 和 for），除非介词是第一个或最后一个单词。
- 以动词开始，描述将要执行的动作。
- 使用一个名词来描述行动的目标。
- 避免在标题中使用“command”。