🚀 在 VS Code 中

虚拟文档

文本文件内容提供程序 API 允许你在 Visual Studio Code 中从任意来源创建只读文档。你可以在以下位置找到包含源代码的示例扩展:https://github.com/microsoft/vscode-extension-samples/blob/main/virtual-document-sample/README.md

TextDocumentContentProvider

该 API 的工作原理是声明一个 uri 方案,你的提供程序随后会为该方案返回文本内容。方案必须在注册提供程序时提供,之后无法更改。同一提供程序可用于多个方案,并且可以为单个方案注册多个提供程序。

vscode.workspace.registerTextDocumentContentProvider(myScheme, myProvider);

调用 registerTextDocumentContentProvider 会返回一个可释放对象,用于撤消注册。提供程序必须仅实现 provideTextDocumentContent 函数,该函数在调用时会传入 uri 和取消令牌。

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 的内容。作为回报,内容提供程序已连接到打开文档的逻辑,以便始终考虑提供程序。

此示例使用 '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 方案的 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。已更改的文档通过其 uri 标识,uri 作为参数传递给 fire 方法。然后将再次调用提供程序以提供更新后的内容,前提是文档仍处于打开状态。

这就是使 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 });
  })
);

上面的代码片段检查我们是否有一个活动编辑器,以及其文档是否是我们的方案之一。需要进行这些检查,因为命令对所有人都是可用(和可执行)的。然后,uri 的路径组件被反转,并从中创建一个新的 uri,最后打开一个编辑器。

为了用编辑器命令来完善这些内容,需要在 package.json 中添加声明式部分。在 contributes 部分中添加此配置

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

这引用了在 contributes/commands 部分中定义的 cowsay.backwards 命令,并说明它应出现在编辑器标题菜单(右上角的工具栏)中。现在,仅仅这样就意味着该命令始终显示,适用于每个编辑器。这就是 when 子句的用途 - 它描述了显示操作必须为真的条件。在此示例中,它声明编辑器中文档的方案必须是 cowsay 方案。然后,为 commandPalette 菜单重复配置 - 默认情况下,它显示所有命令。

cowsay-bwd

事件和可见性

文档提供程序是 VS Code 中的一等公民,其内容出现在常规文本文档中,它们使用与文件等相同的基础结构。但是,这也意味着“你的”文档无法隐藏,它们将出现在 onDidOpenTextDocumentonDidCloseTextDocument 事件中,它们是 vscode.workspace.textDocuments 的一部分等等。适用于所有人的规则是检查文档的 scheme,然后决定是否要对文档执行某些操作。

文件系统 API

如果你需要更大的灵活性和功能,请查看 FileSystemProvider API。它允许实现完整的文件系统,具有文件、文件夹、二进制数据、文件删除、创建等功能。

你可以在以下位置找到包含源代码的示例扩展:https://github.com/microsoft/vscode-extension-samples/tree/main/fsprovider-sample/README.md

当 VS Code 在这种文件系统的文件夹或工作区中打开时,我们称之为虚拟工作区。当虚拟工作区在 VS Code 窗口中打开时,这会在左下角的远程指示器中显示标签,类似于远程窗口。请参阅虚拟工作区指南,了解扩展如何支持该设置。