🚀 在 VS Code 中免費取得 ！

原始檔控制 API

原始檔控制 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 檢視標題的右側。導覽群組中的選單項目將會是內嵌的，而所有其他項目將會位於 … 下拉式選單中。

這三個是類似的

  • 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，而資源的 Uri 會作為方法的引數提供。

將此 API 與 workspace 命名空間中的 registerTextDocumentContentProvider 方法結合使用，這可讓您為任意資源提供內容，前提是 Uri 符合其註冊的自訂配置。

後續步驟

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

04/03/2025