🚀 在 VS Code 中！

原始碼控制 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 執行個體的關聯式選單

source control menu

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 方法結合使用，讓您可以為任意資源提供內容，前提是 Uri 符合其註冊的自訂 scheme。

後續步驟

若要深入瞭解 VS Code 擴充性模型，請嘗試以下主題

02/06/2025