虚拟工作区

Name: Visual Studio Code
Author: Microsoft

像GitHub 仓库扩展一样，打开 VS Code 的一个或多个由文件系统提供者支持的文件夹。当扩展实现文件系统提供者时，工作区资源可能不位于本地磁盘上，而是位于虚拟位置，位于服务器或云端，并且编辑操作在那里进行。

这种配置被称为虚拟工作区。当在 VS Code Windows中打开一个虚拟工作区时，这会在左下角的远程指示器中显示一个标签，类似于其他远程开发Windows。

远程指示器

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

一般来说，用户希望尽可能多的扩展能够在虚拟工作区中运行，并且在浏览和编辑远程资源时拥有良好的用户体验。本指南展示了如何在虚拟工作区上测试扩展，描述了如何修改扩展以使其能够在虚拟工作区中运行，并介绍了虚拟工作区能力属性。

修改扩展以在虚拟工作区中运行是 VS Code for the Web中良好工作的重要步骤。VS Code for the Web 完全在浏览器内运行，由于浏览器沙盒，工作区是虚拟的。请参阅 Web 扩展指南以获取更多详细信息。

我的扩展受影响吗？

当一个扩展没有可执行代码，而是像主题、键绑定、片段或语法扩展这样的纯声明性扩展时，它可以在虚拟工作区中运行，不需要任何修改。

带有代码的扩展，即定义一个的扩展主要入口点，需要检查并可能需要修改。

在虚拟工作区上运行您的扩展

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

这将打开一个 VS Code Windows，用于虚拟工作区，其中所有资源都是虚拟的。

确认扩展代码已准备好用于虚拟资源

VS Code API 对虚拟文件系统的支持已经存在相当一段时间了。您可以查看文件系统提供者 API。

一个文件系统提供者被注册用于新的URI方案（例如，vscode-vfs) 和该文件系统中的资源将由使用该模式的 URIs 表示 (vscode-vfs://github/microsoft/vscode/package.json)

检查你的扩展如何处理 VS Code API 返回的 URIs：

永远不要假定URI方案是文件。URI.fsPath只能在URI方案是时使用文件输入：.
请关注以下用法输入：fs用于文件系统操作的节点模块。如果可能，请使用vscode.workspace.fsAPI，委托给适当的文件系统提供者。
检查依赖于特定第三方组件的依赖项输入：fs访问（例如，语言服务器或节点模块）。
如果你从命令中运行可执行文件和任务，请检查这些命令在虚拟工作区Windows中是否合理，或者是否应该禁用。

指示您的扩展是否可以处理虚拟工作区

该虚拟工作区物业低于能力在package.json用于指示扩展是否支持虚拟工作区。

不支持虚拟工作区

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

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": false,
      "description": "在虚拟工作区中无法进行调试。"
    }
  }
}

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

当一个扩展与虚拟工作区完全或部分工作时，它应定义"虚拟工作区": true输入：.

{
  "能力": {
    "虚拟工作区": true
  }
}

如果一个扩展可以工作，但功能有限，它应该向用户解释这种限制：

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": "limited",
      "description": "在虚拟工作区中，跨文件解析和查找引用不受支持。"
    }
  }
}

描述显示在扩展视图中：

扩展视图

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

默认

"虚拟工作区": true是所有尚未填写的扩展的默认值虚拟工作区能力。

然而，在测试虚拟工作区时，我们列出了一组我们认为在虚拟工作区中应该禁用的扩展。该列表可以在问题 #122836中找到。这些扩展具有"虚拟工作区": false默认。

当然，扩展作者在这种情况下做出决定会更合适。虚拟工作区扩展中的功能package.json将覆盖我们的默认设置，我们最终会停止使用我们的列表。

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

禁用命令并查看贡献

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

该虚拟工作区上下文密钥在所有工作区文件夹位于虚拟文件系统时设置。下面的示例仅显示命令npm 发布在命令面板中，当不在虚拟工作区中：

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

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

在下面的示例中，npm.运行所选脚本命令仅在编辑器上下文菜单中显示，前提是底层资源在本地磁盘上。

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

通过编程检测虚拟工作区

检查当前工作区是否由非文件方案是虚拟的，您可以使用以下源代码：

常量 是虚拟工作区 =
  工作区.工作区文件夹 &&
  工作区.工作区文件夹.每个(函数 => 函数.uri.方案 !== '文件');

语言扩展和虚拟工作区

对虚拟工作空间的语言支持有什么期望？

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

A. 基础语言支持：

TextMate 词法分析和语法着色
语言特定的编辑支持：括号对，注释，自动回车规则，折叠标记
代码片段

B. 单文件 语言支持：

文档符号（大纲），折叠，选择范围
文档亮点，语义突出，文档颜色
完成、悬停、签名帮助、基于当前文件和静态语言库中的符号查找引用/声明
格式化，链接编辑
语法验证和同文件语义验证以及代码行动

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

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

VS Code 随附的丰富语言扩展（TypeScript、JSON、CSS、HTML、Markdown）在处理虚拟资源时，其语言支持仅限于单文件。

禁用语言扩展

如果无法在一个文件上进行操作，语言扩展也可以决定在虚拟工作区中禁用该扩展。

如果您的扩展提供了 both grammars 和 rich language support，并且需要禁用 rich language support，那么 grammars 也会被禁用。为了避免这种情况，您可以创建一个基本语言扩展（grammars、语言配置、snippets）和一个 rich language support 的扩展，这样您会有两个扩展。

基本语言扩展有"虚拟工作区": true并提供语言ID、配置、语法和片段。
丰富的语言扩展具有"虚拟工作区": false并包含主要文件。它提供了语言支持、命令，并且有一个扩展依赖 (扩展依赖) 基于基本语言扩展。丰富的语言扩展应保持已建立扩展的扩展ID，这样用户可以通过安装一个扩展来继续拥有完整的功能。

你可以看到这种做法，例如内置的JSON语言扩展，它由一个JSON扩展和一个JSON语言特性扩展组成。

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

语言选择器

在注册一个语言功能的提供者（例如，自动完成、悬停信息、代码行动等）时，请确保指定提供者所支持的方案：

返回 vscode.语言.注册完成项提供程序(
  { 语言: 'typescript', 方案: 'file' },
  {
    提供完成项(文档, 位置, 令牌) {
      // ...
    }
  }
);

语言服务器协议（LSP）对访问虚拟资源的支持情况如何？

正在开展工作，以向LSP添加文件系统提供者支持。在Language Server Protocol中跟踪问题 #1264。