🚀 在 VS Code 中

虚拟工作区

诸如 GitHub Repositories 扩展之类的扩展在一个或多个由 文件系统提供程序 支持的文件夹上打开 VS Code。当扩展实现文件系统提供程序时,工作区资源可能不在本地磁盘上,而是虚拟的,位于服务器或云端,并且编辑操作在那里发生。

此配置称为虚拟工作区。当在 VS Code 窗口中打开虚拟工作区时,这将在左下角的远程指示器中通过标签指示,类似于其他 远程开发 窗口。

Remote indicator

并非所有扩展都能够与虚拟资源一起工作,并且可能需要资源位于磁盘上。某些扩展使用依赖于磁盘访问的工具,需要同步文件访问,或者没有必要的文件系统抽象。在这些情况下,当在虚拟工作区中时,VS Code 会向用户指示他们正在受限模式下运行,并且某些扩展已停用或功能有限。

通常,用户希望尽可能多的扩展在虚拟工作区中工作,并在浏览和编辑远程资源时获得良好的用户体验。本指南介绍扩展如何针对虚拟工作区进行测试,描述允许它们在虚拟工作区中工作的修改,并介绍 virtualWorkspaces 功能属性。

修改扩展以与虚拟工作区一起工作也是在 Web 版 VS Code 中良好工作的重要一步。Web 版 VS Code 完全在浏览器内部运行,并且由于浏览器沙箱,工作区是虚拟的。有关更多详细信息,请参阅 Web 扩展 指南。

我的扩展是否受影响?

当扩展没有可执行代码,而是纯粹声明性的,例如主题、键盘快捷键、代码片段或语法扩展时,它可以运行在虚拟工作区中,并且无需修改。

具有代码的扩展,即定义 main 入口点的扩展,需要检查,并且可能需要修改。

针对虚拟工作区运行您的扩展

安装 GitHub Repositories 扩展,并从命令面板运行 打开 GitHub 仓库... 命令。该命令显示一个快速选择下拉列表,您可以粘贴任何 GitHub URL,或者选择搜索特定的仓库或拉取请求。

这将为虚拟工作区打开一个 VS Code 窗口,其中所有资源都是虚拟的。

检查扩展代码是否为虚拟资源做好准备

VS Code API 对虚拟文件系统的支持已经存在很长时间了。您可以查看 文件系统提供程序 API

文件系统提供程序是为新的 URI 方案(例如,vscode-vfs)注册的,并且该文件系统上的资源将由使用该方案的 URI 表示 (vscode-vfs://github/microsoft/vscode/package.json)

检查您的扩展如何处理从 VS Code API 返回的 URI

  • 永远不要假设 URI 方案是 file。只有当 URI 方案是 file 时才能使用 URI.fsPath
  • 注意使用 fs node 模块进行文件系统操作的情况。如果可能,请使用 vscode.workspace.fs API,它会委托给适当的文件系统提供程序。
  • 检查依赖于 fs 访问的第三方组件(例如,语言服务器或 node 模块)。
  • 如果您从命令运行可执行文件和任务,请检查这些命令在虚拟工作区窗口中是否有意义,或者是否应该禁用它们。

表明您的扩展是否可以处理虚拟工作区

package.jsoncapabilities 下的 virtualWorkspaces 属性用于表明扩展是否与虚拟工作区一起工作。

不支持虚拟工作区

下面的示例声明扩展不支持虚拟工作区,并且不应在此设置中由 VS Code 启用。

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": false,
      "description": "Debugging is not possible in virtual workspaces."
    }
  }
}

部分和完全支持虚拟工作区

当扩展在虚拟工作区中工作或部分工作时,它应定义 "virtualWorkspaces": true

{
  "capabilities": {
    "virtualWorkspaces": true
  }
}

如果扩展可以工作,但功能有限,则应向用户解释限制

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": "limited",
      "description": "In virtual workspaces, resolving and finding references across files is not supported."
    }
  }
}

描述显示在扩展视图中

Extensions view

然后,扩展应禁用虚拟工作区中不支持的功能,如下所述。

默认

对于所有尚未填写 virtualWorkspaces 功能的扩展,"virtualWorkspaces": true 是默认值。

但是,在测试虚拟工作区时,我们列出了一系列我们认为应该在虚拟工作区中禁用的扩展。该列表可以在 issue #122836 中找到。这些扩展默认具有 "virtualWorkspaces": false

当然,扩展作者更适合做出此决定。扩展的 package.json 中的 virtualWorkspaces 功能将覆盖我们的默认值,我们最终将取消我们的列表。

在虚拟工作区打开时禁用功能

禁用命令和视图贡献

命令和视图以及许多其他贡献的可用性可以通过 when 子句 中的上下文键来控制。

当所有工作区文件夹都位于虚拟文件系统上时,将设置 virtualWorkspace 上下文键。下面的示例仅在不在虚拟工作区中时才在命令面板中显示命令 npm.publish

{
  "menus": {
    "commandPalette": [
      {
        "command": "npm.publish",
        "when": "!virtualWorkspace"
      }
    ]
  }
}

resourceScheme 上下文键设置为文件资源管理器中当前选定元素或编辑器中打开的元素的 URI 方案。

在下面的示例中,只有当底层资源位于本地磁盘上时,npm.runSelectedScript 命令才会显示在编辑器上下文菜单中。

{
  "menus": {
    "editor/context": [
      {
        "command": "npm.runSelectedScript",
        "when": "resourceFilename == 'package.json' && resourceScheme == file"
      }
    ]
  }
}

以编程方式检测虚拟工作区

要检查当前工作区是否由非 file 方案组成并且是虚拟的,您可以使用以下源代码

const isVirtualWorkspace =
  workspace.workspaceFolders &&
  workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');

语言扩展和虚拟工作区

对于虚拟工作区的语言支持有哪些期望?

所有扩展都能够完全与虚拟资源一起工作是不现实的。许多扩展使用外部工具,这些工具需要同步文件访问和磁盘上的文件。因此,仅提供有限的功能是可以接受的,例如下面列出的 基本单文件 支持。

A. 基本 语言支持

  • TextMate 标记化和着色
  • 特定于语言的编辑支持:括号对,注释,回车规则,折叠标记
  • 代码片段

B. 单文件 语言支持

  • 文档符号(大纲),折叠,选择范围
  • 文档高亮,语义高亮,文档颜色
  • 基于当前文件和静态语言库中的符号的完成,悬停,签名帮助,查找引用/声明
  • 格式化,链接编辑
  • 语法验证和同文件语义验证和代码操作

C. 跨文件,工作区感知 语言支持

  • 跨文件引用
  • 工作区符号
  • 验证工作区/项目中的所有文件

与 VS Code 一起提供的丰富语言扩展(TypeScript,JSON,CSS,HTML,Markdown)在处理虚拟资源时仅限于单文件语言支持。

禁用语言扩展

如果处理单个文件不是一种选择,则语言扩展也可以决定在虚拟工作区中禁用该扩展。

如果您的扩展同时提供语法和需要禁用的丰富语言支持,则语法也将被禁用。为避免这种情况,您可以创建一个基本语言扩展(语法,语言配置,代码片段),与丰富的语言支持分开,并拥有两个扩展。

  • 基本语言扩展具有 "virtualWorkspaces": true,并提供语言 ID,配置,语法和代码片段。
  • 丰富的语言扩展具有 "virtualWorkspaces": false,并包含 main 文件。它贡献语言支持,命令,并且具有对基本语言扩展的扩展依赖项(extensionDependencies)。丰富的语言扩展应保留已建立的扩展的扩展 ID,以便用户可以通过安装单个扩展继续拥有全部功能。

您可以在内置语言扩展(例如 JSON)中看到这种方法,JSON 由 JSON 扩展和 JSON 语言功能扩展组成。

这种分离也有助于在 受限工作区 中运行 受限模式。丰富的语言扩展通常需要信任,而基本语言功能可以在任何设置中运行。

语言选择器

当为语言功能(例如,完成,悬停,代码操作等)注册提供程序时,请确保指定提供程序支持的方案

return vscode.languages.registerCompletionItemProvider(
  { language: 'typescript', scheme: 'file' },
  {
    provideCompletionItems(document, position, token) {
      // ...
    }
  }
);

语言服务器协议(LSP)中访问虚拟资源的支持如何?

正在进行的工作将文件系统提供程序支持添加到 LSP。在语言服务器协议 issue #1264 中跟踪。