이 출시되었습니다! 11월의 새로운 기능 및 수정 사항을 읽어보세요.

명령

명령은 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');
}

일부 명령은 동작을 제어하는 인수를 받습니다. 명령은 결과를 반환할 수도 있습니다. 예를 들어 API와 유사한 vscode.executeDefinitionProvider 명령은 특정 위치의 정의를 위해 문서를 쿼리합니다. 문서 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);
  }
}

사용 가능한 명령 찾기

명령 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);
      }
    })()
  );
}

웹뷰에서 명령 URI를 활성화하려면 웹뷰가 생성될 때 WebviewOptions에서 enableCommandUris를 설정하면 됩니다.

새 명령 만들기

명령 등록

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.sayHello 명령이 executeCommand로 프로그래밍 방식으로 실행되든, VS Code UI에서 실행되든, 키 바인딩을 통해 실행되든 상관없이 호출됩니다.

사용자 대상 명령 만들기

vscode.commands.registerCommand는 명령 ID를 핸들러 함수에 바인딩하기만 합니다. 이 명령을 명령 팔레트에 노출하여 사용자가 검색할 수 있도록 하려면 확장 프로그램의 package.json에 해당 명령 contribution이 있어야 합니다.

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

commands 기여는 확장 프로그램이 주어진 명령을 제공하고 해당 명령이 호출될 때 활성화되어야 함을 VS Code에 알리고 UI에서 명령이 표시되는 방식을 제어할 수 있도록 합니다. 명령을 만들 때 명령 명명 규칙을 따르십시오.

The contributed command in the Command Palette

이제 사용자가 명령 팔레트에서 또는 키 바인딩을 통해 myExtension.sayHello 명령을 처음 호출하면 확장 프로그램이 활성화되고 registerCommand가 myExtension.sayHello를 올바른 핸들러에 바인딩합니다.

참고: VS Code 버전 1.74.0 이전 버전을 대상으로 하는 확장 프로그램은 사용자 대상 명령에 대해 onCommand activationEvent를 명시적으로 등록하여 확장 프로그램이 활성화되고 registerCommand가 실행되도록 해야 합니다.

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

내부 명령에는 onCommand 활성화 이벤트가 필요하지 않지만, 다음 명령에 대해서는 정의해야 합니다.

  • 명령 팔레트를 사용하여 호출할 수 있습니다.
  • 키 바인딩을 사용하여 호출할 수 있습니다.
  • 편집기 제목 표시줄 등을 통해 VS Code UI를 통해 호출할 수 있습니다.
  • 다른 확장 프로그램에서 사용할 API로 제공됩니다.

명령 팔레트에 표시되는 시점 제어

기본적으로 package.json의 commands 섹션을 통해 기여된 모든 사용자 대상 명령은 명령 팔레트에 표시됩니다. 그러나 많은 명령은 활성 텍스트 편집기가 특정 언어이거나 사용자가 특정 구성 옵션을 설정한 경우와 같이 특정 상황에서만 관련이 있습니다.

menus.commandPalette 기여 지점을 사용하면 명령이 명령 팔레트에 표시되는 시점을 제한할 수 있습니다. 대상 명령의 ID와 명령이 표시되는 시점을 제어하는 when 절을 받습니다.

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

이제 myExtension.sayHello 명령은 사용자가 Markdown 파일에 있을 때만 명령 팔레트에 표시됩니다.

명령 사용 가능 여부

명령은 enablement 속성을 통해 사용 가능 여부를 지원하며, 값은 when 절입니다. 사용 가능 여부는 모든 메뉴와 등록된 키 바인딩에 적용됩니다.

참고: enablement과 메뉴 항목의 when 조건 간에는 의미론적 중복이 있습니다. 후자는 비활성화된 항목으로 가득 찬 메뉴를 방지하는 데 사용됩니다. 예를 들어 JavaScript 정규식을 분석하는 명령은 파일이 JavaScript일 때 when 표시되어야 하고, 커서가 정규식 위에 있을 때만 enabled되어야 합니다. when 절은 다른 언어 파일에 대해 명령을 표시하지 않음으로써 혼란을 방지합니다. 혼란스러운 메뉴를 방지하는 것이 강력히 권장됩니다.

마지막으로, 명령 팔레트 또는 컨텍스트 메뉴와 같이 명령을 표시하는 메뉴는 사용 가능 여부를 처리하는 다양한 방법을 구현합니다. 편집기 및 탐색기 컨텍스트 메뉴는 사용 가능/비활성화 항목을 렌더링하는 반면, 명령 팔레트는 이를 필터링합니다.

사용자 지정 when 절 컨텍스트 사용

자신만의 VS Code 확장 프로그램을 작성 중이고 when 절 컨텍스트를 사용하여 명령, 메뉴 또는 보기를 활성화/비활성화해야 하지만 기존 키가 필요에 맞지 않으면 자신만의 컨텍스트를 추가할 수 있습니다.

아래 첫 번째 예는 myExtension.showMyCommand 키를 true로 설정하며, 이는 명령의 사용 가능 여부에 사용하거나 when 속성과 함께 사용할 수 있습니다. 두 번째 예는 when 절과 함께 사용하여 멋진 열린 항목의 수가 2보다 큰지 확인할 수 있는 값을 저장합니다.

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

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

명명 규칙

명령을 만들 때 다음 명명 규칙을 따라야 합니다.

  • 명령 제목
    • 제목 스타일 대문자를 사용하십시오. 4자 이하의 전치사(예: on, to, in, of, with, for)는 전치사가 첫 단어 또는 마지막 단어가 아닌 경우 대문자를 사용하지 마십시오.
    • 수행될 작업을 설명하는 동사로 시작하십시오.
    • 작업의 대상을 설명하는 명사를 사용하십시오.
    • 제목에 "command"를 사용하는 것을 피하십시오.
12/10/2025
English 한국어 中文(简体)
© . This site is unofficial and not affiliated with Microsoft.