virtual-documents.md

layout	parent	title	nav_order	description
default	Extension Guides	Virtual Documents	7

가상 문서

텍스트 문서 컨텐츠 제공 API는 여러분이 읽기 전용 문서를 임의의 소스로부터 Visual Studio Code를 통해 생성 할 수 있게 합니다. 소스코드가 제공된 예시 익스텐션을 여기서 확인하십시오: https://github.com/Microsoft/vscode-extension-samples/blob/master/virtual-document-sample/README.md

텍스트 문서 컨텐츠 제공기

API는 제공기에 쓰일 uri-scheme을 입력받아 텍스트 컨텐츠를 돌려주는 방식으로 작동합니다. scheme은 제공기를 등록할때 반드시 제공되어야 하며, 이 후에는 변경이 불가능 합니다. 같은 제공기는 여러 종류에 scheme에 대해 사용 할 수 있고, 여러개의 제공기를 1개의 scheme에 등록 할 수도 있습니다.

vscode.workspace.registerTextDocumentContentProvider(myScheme, myProvider);

registerTextDocumentContentProvider를 호출하는 것은 등록 취소 가능한 임시변수를 리턴합니다. 제공기는 반드시 uri, 취소 토큰과 같이 호출되는 provideTextDocumentContent 함수를 구현해야 합니다.

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

제공기가 가상문서에 쓰일 uri를 생성하지 않는지 유념하십시오 - 이 역할은 uri와 같이 주어진 것에 대해 컨텐츠를 제공 하는 것입니다. 리턴시, 컨텐츠 제공기는 열려있는 문서 로직에 조합되어 제공기가 항상 고려되게 합니다.

이 예시는 cowsay 커맨드를 사용하여 에디터가 보여줄 uri를 만듭니다.

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-sheme 의 uri를 생성하고, uri에 해당하는 문서를 열고, 마지막으로 문서를 위한 에디터를 엽니다. 3번째 단계에서, 문서를 여는동안 제공기는 uri에 해당하는 컨텐츠를 요구받게 됩니다.

이를 통해 우리는 완벽하게 기능적인 텍스트 문서 컨텐츠 제공기를 가지게 되었습니다. 다음 주제에서는 가상문서가 어떤 방식으로 업데이트 되고, 가상문서를 위한 UI 커맨드가 어떻게 등록되는지 알아볼 것 입니다.

가상문서 업데이트

가상문서 업데이트 시나리오에 의존합니다. 이를 위해서 제공기는 onDidChange 이벤트를 구현 할 수 있습니다.

vscode.Event 타입은 VS Code에서 이벤트 발생을 설정합니다. 이벤트를 구현하는 가장 쉬운 방법은 다음과 같이 vscode.EventEmitter입니다:

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

  //...
};

이벤트 이미터는 문서에 변화가 생겼을때 VS Code에 알리기 위해 쓰일 수 있는 fire라는 메소드를 가지고 있습니다. 변경이 생긴 문서는 그 uri가 fire메소드에 사용되어 인식 됩니다. 제공기는, 문서가 여전히 열려있다는 가정하에, 업데이트된 컨텐츠를 제공하기 위해 다시 호출 될 것입니다.

이것이 VS Code 가 가상 문서에서 변경을 감지하기위해 필요한 전부 입니다. 이 기능을 사용한 더 복잡한 예시를 이곳에서 참조하십시오 : https://github.com/Microsoft/vscode-extension-samples/blob/master/contentprovider-sample/README.md

에디터 커맨드 추가

에디터 액션은 연관된 컨텐츠 제공기가 제공된 문서에만 추가 될 수 있습니다. 아래는 cow가 말한것을 역전환하는 예시 커맨드 입니다.

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

위의 snippet은 우리가 활성된 에디터를 가지고 있는것과, 그것의 문서가 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에서의 1등급 시민입니다, 컨텐츠는 일반 텍스트 문서에 보여지며, 파일과 같은 인프라를 사용합니다. 하지만, 이는 "여러분의" 문서를 숨길 수 없다는것을 의미하며, onDidOpenTextDocument와 onDidCloseTextDocument 이벤트를 통해 보여진다는 것과, vscode.workspace.textDocuments에 소속 된다는 것을 의미합니다. 모두를 위한 규칙은 문서의 scehe을 확인하는 다음 문서로 혹은 문서를 위해 할 것을 정하는 것입니다.

파일 시스템 API

더 강하고 유연한 사용을 위해서, FileSystemProvider API를 참조하십시오. 이는 텍스트뿐 아니라 파일, 폴더, 바이너리 데이터, 파일의 생성과 삭제 등 모든 것을 포함합니다.