原始碼管理 API

原始碼管理 (SCM) API 允許擴充套件作者定義原始碼管理 (SCM) 功能。它提供了一個精簡而強大的 API 表面，可以整合多種不同的 SCM 系統到 Visual Studio Code 中，同時與所有這些系統保持統一的使用者介面。

VS Code SCM

VS Code 本身就內建了一個原始碼管理提供程式，即 Git 擴充套件。它是此 API 的最佳參考，如果您想貢獻自己的 SCM 提供程式，它也是一個絕佳的起點。在 Marketplace 中還有其他很棒的示例，例如SVN 擴充套件。

本文件將幫助您構建一個擴充套件，該擴充套件可以使任何 SCM 系統與 VS Code 配合使用。

注意：您可以隨時參考我們文件中的vscode 名稱空間 API 參考。

原始碼管理模型

SourceControl 是負責使用資源狀態（SourceControlResourceState 的例項）填充原始碼管理模型的實體。資源狀態本身組織在組（SourceControlResourceGroup 的例項）中。

您可以使用 vscode.scm.createSourceControl 建立一個新的 SourceControl。

為了更好地理解這三個實體是如何相互關聯的，讓我們以Git為例。考慮以下 git status 的輸出：

vsce main* → git status
On branch main
Your branch is up-to-date with 'origin/main'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   README.md
        renamed:    src/api.ts -> src/test/api.ts

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        deleted:    .travis.yml
        modified:   README.md

此工作區中有很多事情正在進行。首先，README.md 檔案已被修改、暫存，然後又修改了一次。其次，src/api.ts 檔案已被移動到 src/test/api.ts，並且該移動已被暫存。最後，.travis.yml 檔案已被刪除。

對於此工作區，Git 定義了兩個資源組：工作樹和索引。每個檔案更改都屬於其中一個組，並被視為資源狀態。

索引 - 資源組
- README.md，已修改 - 資源狀態
- src/test/api.ts，從 src/api.ts 重新命名 - 資源狀態
工作樹 - 資源組
- .travis.yml，已刪除 - 資源狀態
- README.md，已修改 - 資源狀態

請注意，同一個檔案 README.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') }
];

const workingTree = gitSCM.createResourceGroup('workingTree', 'Changes');
workingTree.resourceStates = [
  { resourceUri: createResourceUri('.travis.yml') },
  { resourceUri: createResourceUri('README.md') }
];

對原始碼管理和資源組所做的更改將傳播到原始碼管理檢視。

原始碼管理檢視

VS Code 能夠隨著原始碼管理模型的變化而填充原始碼管理檢視。資源狀態可以使用 SourceControlResourceDecorations 進行自定義。

export interface SourceControlResourceState {
  readonly decorations?: SourceControlResourceDecorations;
}

上面的示例足以填充原始碼管理檢視中的一個簡單列表，但是使用者可能希望對每個資源執行許多互動操作。例如，當用戶單擊一個資源狀態時會發生什麼？該資源狀態可以選擇提供一個命令來處理此操作。

export interface SourceControlResourceState {
  readonly command?: Command;
}

選單

有六個原始碼管理選單 ID，您可以在其中放置選單項，以便為使用者提供更豐富的使用者介面。

scm/title 選單位於 SCM 檢視標題的右側。navigation 組中的選單項將內聯顯示，而所有其他選單項將在 … 下拉選單中。

這三個是相似的：

scm/resourceGroup/context 為 SourceControlResourceGroup 項新增命令。
scm/resourceState/context 為 SourceControlResourceState 項新增命令。
scm/resourceFolder/context 將命令新增到當 SourceControlResourceState 的 resourceUri 路徑包含資料夾，並且使用者選擇樹狀檢視而非列表檢視模式時出現的中間資料夾。

將選單項放在 inline 組中，即可使其內聯顯示。所有其他選單項組都將在上下文選單中顯示，通常可以透過滑鼠右鍵訪問。

請注意，SCM 檢視支援多選，因此命令接收一個或多個資源的陣列作為其引數。

例如，Git 支援透過將 git.stage 命令新增到 scm/resourceState/context 選單並使用如下方法宣告：

stage(...resourceStates: SourceControlResourceState[]): Promise<void>;

在建立 SourceControl 和 SourceControlResourceGroup 例項時，您需要提供一個 id 字串。這些值將分別填充到 scmProvider 和 scmResourceGroup 上下文鍵中。您可以在選單項的 when 子句中依賴這些上下文鍵。Git 能夠為其 git.stage 命令顯示內聯選單項，方法如下：

{
  "command": "git.stage",
  "when": "scmProvider == git && scmResourceGroup == merge",
  "group": "inline"
}

scm/repository 選單是 **原始碼管理儲存庫** 檢視中每個 SourceControl 例項上的選單。將選單項放在 inline 組中，即可使其內聯顯示。所有其他選單項組都將在 ... 選單中顯示。inline 組會根據可用空間進行渲染，未能顯示的選單項會自動移至 ... 選單。

scm/sourceControl 選單是 **原始碼管理儲存庫** 檢視中每個 SourceControl 例項上的上下文選單。

scm/change/title 允許您為快速差異內聯差異編輯器貢獻命令到其標題欄，該編輯器稍後會進行介紹。命令將作為引數傳遞文件的 URI、其中的更改陣列以及內聯更改差異編輯器當前聚焦的更改的索引。例如，這是 stageChange Git 命令的宣告，該命令已新增到此選單，並具有一個測試 originalResourceScheme 上下文鍵等於 git 的 when 子句：

async stageChange(uri: Uri, changes: LineChange[], index: number): Promise<void>;

SCM 輸入框

原始碼管理輸入框位於每個原始碼管理檢視的頂部，允許使用者輸入訊息。您可以獲取（和設定）此訊息以執行操作。例如，在 Git 中，它用作提交框，使用者在此輸入提交訊息，然後 git commit 命令會拾取它們。

export interface SourceControlInputBox {
  value: string;
}

export interface SourceControl {
  readonly inputBox: SourceControlInputBox;
}

使用者可以透過按 Ctrl+Enter（macOS 上為 Cmd+Enter）來接受任何訊息。您可以透過為 SourceControl 例項提供 acceptInputCommand 來處理此事件。

export interface SourceControl {
  readonly acceptInputCommand?: Command;
}

快速差異

VS Code 還支援顯示快速差異編輯器裝訂線裝飾。單擊這些裝飾會顯示一個內聯差異體驗，您可以為該體驗貢獻上下文命令。

SCM quick diff

這些裝飾由 VS Code 本身計算。您只需為 VS Code 提供任何給定檔案的原始內容即可。

export interface SourceControl {
  quickDiffProvider?: QuickDiffProvider;
}

使用 QuickDiffProvider 的 provideOriginalResource 方法，您的實現可以告訴 VS Code 原始資源的 Uri，該原始資源與作為引數傳遞給方法的資源的 Uri 相匹配。

將此 API 與 workspace 名稱空間中的registerTextDocumentContentProvider 方法結合使用，該方法允許您為任意資源提供內容，前提是有一個 Uri 與其註冊的自定義 scheme 匹配。

後續步驟

要了解有關 VS Code 可擴充套件性模型的更多資訊，請嘗試以下主題

SCM API 參考 - 閱讀完整的 SCM API 文件
Git 擴充套件 - 透過閱讀 Git 擴充套件實現來學習
擴充套件 API 概述 - 瞭解完整的 VS Code 可擴充套件性模型。
擴充套件清單檔案 - VS Code package.json 擴充套件清單檔案參考
貢獻點 - VS Code 貢獻點參考

12/10/2025