가상 문서

텍스트 문서 콘텐츠 제공자 API를 사용하면 임의 소스에서 Visual Studio Code 내 읽기 전용 문서를 만들 수 있습니다. 소스 코드가 포함된 샘플 확장은 다음에서 찾을 수 있습니다: https://github.com/microsoft/vscode-extension-samples/blob/main/virtual-document-sample/README.md.

TextDocumentContentProvider

API는 uri-scheme을 선점하는 방식으로 작동하며, 해당 scheme에 대해 제공자가 텍스트 콘텐츠를 반환합니다. scheme은 제공자를 등록할 때 제공되어야 하며 이후에는 변경할 수 없습니다. 동일한 제공자를 여러 scheme에 사용할 수 있으며, 단일 scheme에 여러 제공자를 등록할 수 있습니다.

vscode.workspace.registerTextDocumentContentProvider(myScheme, myProvider);

registerTextDocumentContentProvider를 호출하면 등록을 취소할 수 있는 disposable 객체가 반환됩니다. 제공자는 uri와 취소 토큰으로 호출되는 provideTextDocumentContent 함수만 구현해야 합니다.

const myProvider = new (class implements vscode.TextDocumentContentProvider {
  provideTextDocumentContent(uri: vscode.Uri): string {
    // invoke cowsay, use uri-path as text
    return cowsay.say({ text: uri.path });
  }
})();

제공자가 가상 문서에 대한 uri를 생성하지 않는다는 점에 유의하십시오. 제공자의 역할은 해당 uri가 주어졌을 때 콘텐츠를 **제공**하는 것입니다. 이에 대한 보답으로, 콘텐츠 제공자는 열린 문서 논리에 연결되어 제공자가 항상 고려되도록 합니다.

이 샘플은 편집기가 표시해야 하는 uri를 생성하는 'cowsay' 명령을 사용합니다.

vscode.commands.registerCommand('cowsay.say', async () => {
  let what = await vscode.window.showInputBox({ placeHolder: 'cow say?' });
  if (what) {
    let uri = vscode.Uri.parse('cowsay:' + what);
    let doc = await vscode.workspace.openTextDocument(uri); // calls back into the provider
    await vscode.window.showTextDocument(doc, { preview: false });
  }
});

이 명령은 입력을 요청하고, cowsay-scheme의 uri를 생성하며, 해당 uri에 대한 문서를 열고, 마지막으로 해당 문서에 대한 편집기를 엽니다. 3단계인 문서 열기에서 제공자는 해당 uri에 대한 콘텐츠를 제공하도록 요청받습니다.

이를 통해 완전한 기능을 갖춘 텍스트 문서 콘텐츠 제공자를 갖추게 되었습니다. 다음 섹션에서는 가상 문서를 업데이트하는 방법과 가상 문서에 대한 UI 명령을 등록하는 방법을 설명합니다.

가상 문서 업데이트

시나리오에 따라 가상 문서가 변경될 수 있습니다. 이를 지원하기 위해 제공자는 onDidChange 이벤트를 구현할 수 있습니다.

vscode.Event 타입은 VS Code에서의 이벤트에 대한 계약을 정의합니다. 이벤트를 구현하는 가장 쉬운 방법은 vscode.EventEmitter를 사용하는 것입니다. 다음과 같습니다:

const myProvider = new (class implements vscode.TextDocumentContentProvider {
  // emitter and its event
  onDidChangeEmitter = new vscode.EventEmitter<vscode.Uri>();
  onDidChange = this.onDidChangeEmitter.event;

  //...
})();

이벤트 이미터에는 fire 메소드가 있으며, 문서에 변경이 발생했음을 VS Code에 알리는 데 사용할 수 있습니다. 변경된 문서는 fire 메소드의 인수로 제공된 uri로 식별됩니다. 문서가 여전히 열려 있다고 가정하면, 제공자는 업데이트된 콘텐츠를 제공하기 위해 다시 호출됩니다.

이것이 VS Code가 가상 문서의 변경 사항을 수신 대기하도록 만드는 데 필요한 전부입니다. 이 기능을 활용하는 더 복잡한 예제를 보려면 다음을 참조하십시오: https://github.com/microsoft/vscode-extension-samples/blob/main/contentprovider-sample/README.md.

편집기 명령 추가

연결된 콘텐츠 제공자가 제공한 문서와만 상호 작용하는 편집기 동작을 추가할 수 있습니다. 이것은 소가 방금 말한 것을 반대로 하는 샘플 명령입니다.

// register a command that updates the current cowsay
subscriptions.push(
  vscode.commands.registerCommand('cowsay.backwards', async () => {
    if (!vscode.window.activeTextEditor) {
      return; // no editor
    }
    let { document } = vscode.window.activeTextEditor;
    if (document.uri.scheme !== myScheme) {
      return; // not my scheme
    }
    // get path-components, reverse it, and create a new uri
    let say = document.uri.path;
    let newSay = say
      .split('')
      .reverse()
      .join('');
    let newUri = document.uri.with({ path: newSay });
    await vscode.window.showTextDocument(newUri, { preview: false });
  })
);

위의 스니펫은 활성 편집기가 있고 해당 문서가 우리의 scheme 중 하나인지 확인합니다. 명령은 모두에게 사용 가능하고(그리고 실행 가능)하기 때문에 이러한 확인이 필요합니다. 그런 다음 uri의 경로 구성 요소가 뒤집히고 새 uri가 생성되며, 마지막으로 편집기가 열립니다.

편집기 명령으로 마무리하려면 package.json에 선언적 부분이 필요합니다. contributes 섹션에 이 구성을 추가하십시오.

"menus": {
  "editor/title": [
    {
      "command": "cowsay.backwards",
      "group": "navigation",
      "when": "resourceScheme == cowsay"
    }
  ]
}

이것은 contributes/commands 섹션에 정의된 cowsay.backwards 명령을 참조하며, 편집기 제목 메뉴(오른쪽 상단 툴바)에 표시되어야 한다고 말합니다. 이제 이것만으로는 명령이 모든 편집기에 대해 항상 표시됩니다. when 절이 사용되는 이유입니다. 이 절은 동작을 표시하기 위해 참이어야 하는 조건을 설명합니다. 이 샘플에서는 편집기 내 문서의 scheme이 cowsay-scheme이어야 한다고 명시합니다. 그런 다음 구성은 commandPalette-메뉴에 대해 반복됩니다. 이 메뉴는 기본적으로 모든 명령을 표시합니다.

이벤트 및 가시성

문서 제공자는 VS Code에서 일급 시민입니다. 해당 콘텐츠는 일반 텍스트 문서에 표시되며, 파일 등과 동일한 인프라를 사용합니다. 그러나 이는 "귀하의" 문서가 숨겨질 수 없다는 것을 의미하기도 합니다. onDidOpenTextDocument 및 onDidCloseTextDocument 이벤트에 표시되며, vscode.workspace.textDocuments의 일부이며 더 많은 기능을 제공합니다. 모든 사람에게 적용되는 규칙은 문서의 scheme을 확인하고 문서에 대해 수행할 작업이 있는지 여부를 결정하는 것입니다.

파일 시스템 API

더 많은 유연성과 강력한 기능이 필요한 경우 FileSystemProvider API를 살펴보십시오. 이 API를 사용하면 파일, 폴더, 바이너리 데이터, 파일 삭제, 생성 등을 갖춘 완전한 파일 시스템을 구현할 수 있습니다.

소스 코드가 포함된 샘플 확장은 다음에서 찾을 수 있습니다: https://github.com/microsoft/vscode-extension-samples/tree/main/fsprovider-sample/README.md.

VS Code가 이러한 파일 시스템의 폴더 또는 작업 공간에서 열릴 때 이를 가상 작업 공간이라고 합니다. VS Code 창에 가상 작업 공간이 열리면 왼쪽 하단의 원격 표시기에 레이블로 표시되며, 원격 창과 유사합니다. 확장이 이 설정을 지원하는 방법에 대한 자세한 내용은 가상 작업 공간 가이드를 참조하십시오.