編輯

原始碼管理 API

原始碼管理 API 允許擴充套件作者定義原始碼管理 (SCM) 功能。它有一個精簡但功能強大的 API 介面，允許將許多不同的 SCM 系統整合到 Visual Studio Code 中，同時它們都擁有通用的使用者介面。

VS Code SCM

VS Code 本身附帶一個原始碼管理提供程式，即 Git 擴充套件，它是此 API 的最佳參考，如果您想貢獻自己的 SCM 提供程式，它是一個很好的起點。市場中還有其他很好的示例，例如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/sourceControl 選單是原始碼管理儲存庫檢視中每個 SourceControl 例項上的上下文選單

scm/change/title 允許您向快速差異內聯差異編輯器的標題欄貢獻命令，該編輯器將在後面進一步描述。該命令將作為引數傳遞文件的 URI、其中的更改陣列以及內聯更改差異編輯器當前聚焦的更改索引。例如，以下是 stageChange Git 命令的宣告，該命令透過 when 子句測試 originalResourceScheme 上下文鍵等於 git 來貢獻到此選單

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 方法結合使用，該方法允許您為任意資源提供內容，給定一個匹配其註冊的自定義 scheme 的 Uri。

後續步驟

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

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

09/11/2025