커맨드

커맨드는 Visual Studio Code에서 액션을 실행합니다. 만약 여러분이 키바인딩을 구성했었다면, 커맨드로 작업을 한 것입니다. 또한 커맨드는 익스텐션에서 사용자에게 기능을 접하게 하기 위해서, VS Code의 UI의 액션에 바인드 하고, 내부 로직을 구현합니다.

커맨드 사용하기

VS Code는 여러분이 에디터와 상호작용, 사용자 인터페이스를 조절, 혹은 백그라운드 작업을 할 수 있는, 많은 빌트인 커맨드를 포함하고 있습니다. 다수의 익스텐션은 내부 기능을 커맨드로 드러내어 사용자와 다른 익스텐션이 활용 할 수 있게 합니다.

커맨드 프로그래밍

vscode.commands.executeCommand API로 커맨드 실행을 프로그래밍 할 수 있습니다. 이를 통해 여러분은 VS Code의 빌트인 기능을 활용하고, VS Code 빌트인 Git이나 Markdown 같은 익스텐션을 제작 할 수 있습니다.

예를 들면, editor.action.addCommentLine커맨드로 텍스트 에디터에서 현재 선택된 라인에 커멘트를 달 수 있습니다.

import * as vscode from 'vscode';

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

어떤 커맨드는 사용을 위해 변수를 입력받습니다. 또한 결과물을 반환 할 수도 있습니다. 예를 들어 vscode.executeDefinitionProvider API와 같은 커맨드는, 주어진 위치에서의 설정을 위해 문서를 읽습니다. 이 때 문서 URI와 위치를 변수로 입력 받아, 정의 된 목록과 promise를 반환 합니다.

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);
  }
}

사용 가능 커맨드 탐색을 위해서:

• 키보드 단축키 탐색
• VS Code의 빌트인 고급 커맨드 API 탐색

커맨드 URI

커맨드 URI는 주어진 커맨드를 실행하는 링크 입니다. 텍스트 위에서 클릭 가능한 링크로 사용, 아이템의 세부내용을 완성, 혹은 웹뷰 내부에서 사용 가능합니다.

커맨드 URI는 커맨드 이름 이후에 command 를 붙여서 사용합니다. 예를 들어 editor.action.addCommentLine 커맨드에 해당하는 커맨드 URI는, command: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})`);

        // To enable command URIs in Markdown content, you must set the `isTrusted` flag.
        // When creating trusted Markdown string, make sure to properly sanitize all the
        // input content so that only expected command URIs can be executed
        contents.isTrusted = true;

        return new vscode.Hover(contents);
      }
    }()
  );
}

커맨드에 제공되는 변수 목록은 URI 인코딩 된 JSON 의 형태입니다: 다음은 git.stage 커맨드를 이용하여 현재 파일의 단계를 띄워주는 예시입니다.

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 vscode.MarkdownString(`[Stage file](${stageCommandUri})`);
        contents.isTrusted = true;
        return new vscode.Hover(contents);
      }
    }()
  );
}

새로운 커맨드 생성

커맨드 등록

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));
}

핸들러 함수는 myExtension.sayHellow커맨드가 실행 될때마다 executeCommand나, VS Code UI, 혹은 키바인딩을 통해서 작동 될 것입니다.

사용자 직면 커맨드 생성

vscode.commands.registerCommand 는 커맨드 id를 핸들러 함수에만 바인딩 합니다. 이 커맨드를 Command Pallete를 통해, 사용자가 활용 할수 있게 하기 위해서, 여러분은 익스텐션의 package.json 내부에 해당하는 커맨드 contribution을 필요로 합니다.

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

commands contribution은 VS Code에 여러분의 익스텐션이 특정 커맨드를 제공하는지 전달하거나, 커맨드가 UI에서 어떤식으로 보여질 지 조절 할 수 있게 합니다.

여러분은 여전히 registerCommand를 호출하여, 핸들러에 커맨드 id를 바인딩해야합니다. 즉 사용자가 myExtension.sayHellow 커맨드를 Command Palette에서 선택하더라도 아직 익스텐션이 활성화 되지 않았기 때문에 아무일도 일어나지 않습니다. 이를 방지 하기 위해서 모든 사용자 직면 명령에 대해 익스텐션에서 onCommand와 activationEvent를 등록해야 합니다.

{
  "activationEvents": ["onCommand:myExtension.sayHello"]
}

이제 사용자가 Command Palette나 키바인딩을 통해 myExtension.sayHello 커맨드를 처음으로 실행하면, 익스텐션이 활성화 되고 registerCommand가 myExtension.sayHello에 적당한 핸들러를 바인딩 할 것입니다.

여러분은 내부 커맨드에 대해서는 onCommand 활성 이벤트를 필요로 하지 않지만, 다음 커맨드에 대해서는 정의 해야합니다:

• Command Palette를 통해 실행 가능한 경우.
• 키 바인딩을 통해 실행 가능한 경우.
• 에디터 타이틀 바와 같은 VS Code UI를 통해 실행 가능한 경우.
• 다른 익스텐션에서의 활용을 목적으로 하는 API 커맨드.

Command Palette에서 커맨드가 언제 보여질지 조절

기본적으로, 모든 사용자 직면 커맨드는 package.json의 commands 부분을 통해 Command Palette에 보여질지 설정 됩니다. 그러나 특정 언어를 사용하는 텍스트 에디터에서, 또는 사용자가 특정 설정 옵션을 가지고 있는 경우 와 같이, 다수의 커맨드는 특정 상황에서만 사용 가능합니다.

여러분은 menus.commandPalette contribution point 를 통해 커맨드가 Command Palette에 보여질지를 조절 할 수 있습니다. 이는 타겟 커맨드의 id와 언제 커맨드가 보여질지를 설정하는 when clause를 필요로 합니다.

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

이제 myExtension.sayHello 커맨드는 사용자가 Markdown 파일을 작업 하는 경우에만 Command Palette에 보여질 것입니다.

커맨드 활성화

커맨드는 enablement 속성을 통해 활성화 될 수 있습니다 - when-clause를 값으로 가집니다. 활성화는 모든 메뉴와 등록된 키바인딩에 적용됩니다.

주의: enablement와 메뉴 아이템의 when 컨디션 사이에는 의미가 중복됩니다. 후자의 경우는 메뉴가 비활성화 된 아이템으로 가득 차는 것을 방지합니다. 예를 들어, 자바스크립트의 정규표현식을 분석하는 커맨드의 경우 파일이 자바스크립트일때 (when) 보여져야 하며 오직 커서가 정규표현식위에 있을때만 활성화 (enabled) 되어야 합니다. when부분은 다른 언어 파일에 경우 커맨드를 숨기는 방식으로 메뉴창을 채우는 것을 방지합니다. 메뉴창을 가득 채우지 않는 것은 강력하게 추천됩니다.

마지막으로, Command Palette나 context menus처럼 커맨드를 보이는 메뉴는, 활성화를 다루기 위해 다른 방식으로 구현 합니다. 에디터와 탐색기 context menus 는 활성/비활성 아이템을 렌더링하고, Command Palette 는 필터링 합니다.