本站点文档内容均翻译自code.visualstudio.com，仅供个人学习，如有差异请以官网为准。

源代码控制 API

源代码控制 API 允许扩展作者定义源代码控制管理 (SCM) 功能。有一个精简但强大的 API 表面，允许在 Visual Studio Code 中集成许多不同的 SCM 系统，同时它们都具有相同的用户界面。

VS Code 版本控制

VS Code本身提供了一个源代码控制提供者，即Git扩展，它是此API的最佳参考，并且是如果你希望贡献你自己的SCM提供者的一个很好的起点。市场上的其他优秀示例包括SVN扩展。

此文档将帮助您构建一个扩展，使任何SCM系统都能与VS Code配合使用。

注意： 可以随时查阅 Visual Studio Code命名空间 API 参考在我们的文档中。

源代码控制模型

一个源代码管理 是负责用 资源状态填充源控制模型的实体源控制资源状态资源状态本身是组织在组中，实例的源代码控制资源组输入：.

您可以创建一个新的源代码控制vscode.scm.createSourceControl输入：.

为了更好地理解这三个实体如何相互关联，让我们以Git为例。考虑以下输出git 状态输入：

vsce 主* → git 状态
在 分支 main
你的 分支 是 最新的 与 'origin/main'
的更改 将要 提交:
  (使用 "git reset HEAD <文件>..." 来 取消更改)

        修改：   README.md
        重命名：    src/api.ts -> src/test/api.ts

更改 未 舍入 为 提交：
  (使用 "git add/rm <文件>..." 来 更新 将会 提交 的内容 )
  (使用 "git checkout -- <文件>..." 来 抛弃 工作 目录中的 更改 )

        已删除：    .travis.yml
        已修改：   README.md

在这个工作区有很多事情在进行。首先，自述文件.md文件已修改、暂存，然后再次修改。第二，src/api.ts文件已移动至src/test/api.ts并且那次行动是精心策划的。最后，.travis.yml文件已被删除。

对于这个工作区，Git 定义了两个资源组： 工作树 和 索引。每个 文件更改 都是该组的 资源状态：

  • 索引 - 资源组
    • 自述文件.md修改 - 资源状态
    • src/test/api.ts重命名自src/api.ts- 资源状态
  • 工作树 - 资源组
    • .travis.yml已删除 - 资源状态
    • 自述文件.md修改 - 资源状态

注意如何使用相同的文件，自述文件.md是两个不同的资源状态的一部分。

以下是Git创建此模型的方法：

function createResourceUri(relativePath: string): vscode.Uri {
  const absolutePath = path.join(vscode.workspace.rootPath, relativePath);
  return vscode.Uri.file(absolutePath);
}

const gitSCM = vscode.scm.createSourceControl('git', 'Git');

const index = gitSCM.createResourceGroup('index', 'Index');
index.resourceStates = [
  { resourceUri: createResourceUri('README.md') },
  { resourceUri: createResourceUri('src/test/api.ts') }
];

常量 工作树 = gitSCM.创建资源组('工作树', '更改');
工作树.资源状态 = [
  { 资源uri: 创建资源uri('/.travis.yml') },
  { 资源uri: 创建资源uri('README.md') }
];

对源控制和资源组所做的更改将传播到源控制视图。

源代码控制视图

VS Code 能够随着源控制模型的变化填充源控制视图。资源状态可以通过 源代码控制资源装饰输入：

导出 接口 SourceControlResourceState {
  只读 装饰?: SourceControlResourceDecorations;
}

前面的示例足以在源代码控制视图中填充一个简单的列表，但用户可能希望对每个资源执行许多用户交互操作。例如，当用户点击资源状态时会发生什么？资源状态可以可选地提供一个命令来处理此操作：

导出 接口 SourceControlResourceState {
  只读 命令?: Command;
}

有六个源代码控制菜单id，您可以在其中放置菜单项，以便为用户提供更丰富的用户界面。

该scm/标题菜单位于 SCM 视图标题的右侧。菜单项在导航组将保持对齐，而其他的全部将位于…下拉菜单。

这三者相似：

  • scm/资源组/上下文添加命令到源代码控制资源组项目。
  • scm/资源状态/上下文添加命令到源控制资源状态项目。
  • scm/资源文件夹/上下文添加命令到出现的中间文件夹源控制资源状态'resourceUri 路径包含文件夹，并且用户选择了树形视图而非列表视图模式。

将菜单项放置在内联将它们内联显示。所有其他菜单项组将显示在上下文菜单中，通常可以通过鼠标右键访问。

请注意，SCM视图支持多选，因此一个命令接收一个或多个资源的数组作为其参数。

例如，Git 支持通过添加来分阶段提交多个文件git.阶段命令到scm/资源状态/上下文菜单和使用这样的方法声明：

阶段(...资源状态: 源控制资源状态[]): 承诺<无>;

当创建它们时，源代码管理和源代码控制资源组实例需要您提供一个身份证字符串。这些值将被填充在scmProvider和scm资源组 上下文键，分别。您可以依赖这些 上下文键 在 当你的菜单项的条款。以下是Git如何显示其内联菜单项的方法git.阶段命令:

{
  "命令": "git.阶段",
  "条件": "scmProvider == git && scmResourceGroup == merge",
  "组": "内联"
}

该scm/仓库菜单是每个菜单源代码管理 实例在 源代码控制仓库 视图中。将菜单项放置在 内联将它们作为组来使它们按行显示。所有其他菜单项组将显示在输入：...菜单。内联组将根据可用空间进行渲染，不合适的菜单项将自动移入输入：...菜单。

该scm/源代码控制菜单是每个上下文菜单源代码管理 实例在 源代码控制库 视图中：

源代码控制菜单

该scm/更改/标题 允许您向 Quick Diff 内联差异编辑器的标题栏贡献命令，将在 稍后描述。该命令将传递文档的 URI、其中的更改数组以及内联更改差异编辑器当前聚焦的更改索引。例如，这里是 阶段变化将此菜单贡献给Git命令的当条款测试表明，原始资源方案 上下文键 等于 吉特输入：

异步阶段变化(uri: Uri, 更改: 行更改[], 索引: 数字): 承诺<无>;

SCM 输入框

源代码控制输入框位于每个源代码控制视图的顶部，允许用户输入一条消息。您可以在其中获取（并设置）此消息以执行操作。例如，在Git中，这被用作提交框，用户在此输入提交信息和提交更改命令拾取它们。

导出 接口 SourceControlInputBox {
  值: 字符串;
}

导出 接口 源控制 {
  只读 输入框: 源控制输入框;
}

用户可以输入Ctrl+Enter（或在macOS上输入Cmd+Enter）以接受任何消息。您可以通过提供一个来处理此事件接受输入命令到你的源代码管理实例。

导出 接口 源控制 {
  只读 接受输入命令?: 命令;
}

快速差异

VS Code 还支持显示快速差异编辑器侧边栏装饰。点击这些装饰可以显示内联差异体验，您可以为此贡献上下文命令：

SCM快速差异

这些装饰是由 VS Code 本身计算的。你所需要做的只是向 VS Code 提供任何给定文件的原始内容。

导出 接口 源控制 {
  快速差异提供者?: QuickDiffProvider;
}

使用一个快速差异提供者'提供原始资源方法，你的实现能够告诉 VS Code乌里原始资源的匹配资源乌里作为方法的参数提供。

将此 API 与注册文本文档内容提供者方法在工作区命名空间，它允许您为任意资源提供内容，给定一个乌里匹配定制计划它注册的。

下一步

要了解更多关于 VS Code 可扩展性模型的信息，请尝试这些主题：