虚拟文档
文本文档内容提供程序 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 打开一个文档,最后为该文档打开一个编辑器。在第三步,即打开文档时,会要求提供程序提供该 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 });
})
);
上面的代码片段检查我们是否有一个活动编辑器,并且它的文档是否是我们方案中的文档。这些检查是必需的,因为命令对所有人都是可用(且可执行)的。然后,URI 的路径组件被反转并从中创建一个新的 URI,最后打开一个编辑器。
要为编辑器命令添加顶部,需要在 package.json
中声明一部分。在 contributes
部分添加此配置
"menus": {
"editor/title": [
{
"command": "cowsay.backwards",
"group": "navigation",
"when": "resourceScheme == cowsay"
}
]
}
这引用了在 contributes/commands
部分中定义的 cowsay.backwards
命令,并表示它应该出现在编辑器标题菜单(右上角的工具栏)中。然而,仅仅这样意味着该命令将始终显示,适用于每个编辑器。这就是 when
子句的用途——它描述了显示该操作必须满足的条件。在此示例中,它声明编辑器中文档的方案必须是 cowsay
方案。然后为 commandPalette
菜单重复此配置——它默认显示所有命令。
事件和可见性
文档提供程序是 VS Code 中的一等公民,它们的内容出现在常规文本文档中,它们使用与文件等相同的基础设施。然而,这也意味着“您的”文档无法隐藏,它们将出现在 onDidOpenTextDocument
和 onDidCloseTextDocument
事件中,它们是 vscode.workspace.textDocuments
等的一部分。所有人的规则是检查文档的 scheme
,然后决定是否要对该文档执行某些操作。
文件系统 API
如果您需要更大的灵活性和能力,请查看 FileSystemProvider
API。它允许实现一个完整的文件系统,包括文件、文件夹、二进制数据、文件删除、创建等。
您可以在以下链接找到包含源代码的示例扩展:https://github.com/microsoft/vscode-extension-samples/tree/main/fsprovider-sample/README.md。
当 VS Code 在此类文件系统的文件夹或工作区中打开时,我们称之为虚拟工作区。当虚拟工作区在 VS Code 窗口中打开时,远程指示器(左下角)中会显示一个标签,类似于远程窗口。请参阅虚拟工作区指南,了解扩展如何支持此设置。