ist jetzt verfügbar! Lesen Sie über die neuen Funktionen und Fehlerbehebungen vom November.

Source Control API

Die Source Control API ermöglicht es Erweiterungsautoren, Funktionen für das Quellcodeverwaltungssystem (SCM) zu definieren. Es gibt eine schlanke, aber dennoch leistungsstarke API-Oberfläche, die die Integration vieler verschiedener SCM-Systeme in Visual Studio Code ermöglicht und gleichzeitig eine gemeinsame Benutzeroberfläche für alle bietet.

VS Code SCM

VS Code selbst wird mit einem Source Control Provider geliefert, der Git-Erweiterung. Sie ist die beste Referenz für diese API und ein großartiger Ausgangspunkt, wenn Sie Ihren eigenen SCM-Provider beisteuern möchten. Im Marketplace finden Sie weitere großartige Beispiele wie die SVN-Erweiterung.

Diese Dokumentation hilft Ihnen beim Erstellen einer Erweiterung, mit der jedes SCM-System mit VS Code funktioniert.

Hinweis: Sie können jederzeit auf die vscode-Namespace-API-Referenz in unserer Dokumentation verweisen.

Source Control Model

Ein SourceControl ist die Entität, die für die Befüllung des Source Control-Modells mit Zuständen von Ressourcen, Instanzen von SourceControlResourceState, verantwortlich ist. Ressourcen Zustände sind selbst in Gruppen, Instanzen von SourceControlResourceGroup, organisiert.

Sie können ein neues SourceControl mit vscode.scm.createSourceControl erstellen.

Um besser zu verstehen, wie diese drei Entitäten miteinander korrelieren, nehmen wir Git als Beispiel. Betrachten Sie die folgende Ausgabe von 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

In diesem Arbeitsbereich passiert vieles. Erstens wurde die Datei README.md geändert, in den Index übernommen und dann noch einmal geändert. Zweitens wurde die Datei src/api.ts nach src/test/api.ts verschoben und diese Verschiebung wurde in den Index übernommen. Schließlich wurde die Datei .travis.yml gelöscht.

Für diesen Arbeitsbereich definiert Git zwei Ressourcengruppen: den Arbeitsbaum und den Index. Jede Dateiänderung innerhalb dieser Gruppe ist ein Ressourcenzustand.

  • Index - Ressourcengruppe
    • README.md, geändert - Ressourcenzustand
    • src/test/api.ts, umbenannt von src/api.ts - Ressourcenzustand
  • Arbeitsbaum - Ressourcengruppe
    • .travis.yml, gelöscht - Ressourcenzustand
    • README.md, geändert - Ressourcenzustand

Beachten Sie, wie dieselbe Datei, README.md, Teil zweier verschiedener Ressourcenzustände ist.

So erstellt Git dieses Modell

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') }
];

Änderungen an den Source Control- und Ressourcengruppen werden an die Source Control-Ansicht weitergegeben.

Source Control View

VS Code kann die Source Control-Ansicht befüllen, wenn sich das Source Control-Modell ändert. Ressourcenzustände können mit SourceControlResourceDecorations angepasst werden.

export interface SourceControlResourceState {
  readonly decorations?: SourceControlResourceDecorations;
}

Das vorherige Beispiel wäre ausreichend, um eine einfache Liste in der Source Control-Ansicht zu befüllen, aber es gibt viele Benutzerinteraktionen, die der Benutzer möglicherweise mit jeder Ressource durchführen möchte. Was passiert zum Beispiel, wenn der Benutzer auf einen Ressourcenzustand klickt? Der Ressourcenzustand kann optional einen Befehl zur Behandlung dieser Aktion bereitstellen.

export interface SourceControlResourceState {
  readonly command?: Command;
}

Es gibt sechs Source Control-Menü-IDs, in die Sie Menüeinträge einfügen können, um dem Benutzer eine wesentlich reichhaltigere Benutzeroberfläche zu bieten.

Das Menü scm/title befindet sich rechts neben dem Titel der SCM-Ansicht. Die Menüeinträge in der Gruppe navigation werden inline angezeigt, während alle anderen im Dropdown-Menü ... enthalten sind.

Diese drei sind ähnlich

  • scm/resourceGroup/context fügt Befehle zu SourceControlResourceGroup-Elementen hinzu.
  • scm/resourceState/context fügt Befehle zu SourceControlResourceState-Elementen hinzu.
  • scm/resourceFolder/context fügt Befehle zu den Zwischenordnern hinzu, die erscheinen, wenn der resourceUri-Pfad eines SourceControlResourceState Ordner enthält und der Benutzer den Baumansicht-Modus anstelle des Listenansicht-Modus gewählt hat.

Platzieren Sie Menüeinträge in der Gruppe inline, damit sie inline angezeigt werden. Alle anderen Menüeintrag-Gruppen werden in einem Kontextmenü dargestellt, das normalerweise über die rechte Maustaste zugänglich ist.

Beachten Sie, dass die SCM-Ansicht Mehrfachauswahl unterstützt, sodass ein Befehl als Argument ein Array von einer oder mehreren Ressourcen erhält.

Zum Beispiel unterstützt Git das Stagen mehrerer Dateien, indem der Befehl git.stage zum Menü scm/resourceState/context hinzugefügt und eine solche Methodendeklaration verwendet wird.

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

Bei ihrer Erstellung erfordern SourceControl- und SourceControlResourceGroup-Instanzen die Angabe einer id-Zeichenfolge. Diese Werte werden in den Kontextschlüsseln scmProvider bzw. scmResourceGroup ausgegeben. Sie können sich auf diese Kontextschlüssel in den when-Klauseln Ihrer Menüeinträge verlassen. Hier ist, wie Git in der Lage ist, ein Inline-Menüelement für seinen git.stage-Befehl anzuzeigen.

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

Das Menü scm/repository ist das Menü für jede SourceControl-Instanz in der Ansicht Source Control Repositories. Platzieren Sie Menüeinträge in der Gruppe inline, damit sie inline angezeigt werden. Alle anderen Menüeintrag-Gruppen werden im Menü ... angezeigt. Die Gruppe inline wird basierend auf dem verfügbaren Speicherplatz gerendert, und Menüeinträge, die nicht passen, werden automatisch in das Menü ... verschoben.

Das Menü scm/sourceControl ist das Kontextmenü für jede SourceControl-Instanz in der Ansicht Source Control Repositories.

source control menu

Der Menüpunkt scm/change/title ermöglicht es Ihnen, Befehle zur Titelleiste des Inline-Diff-Editors für Quick Diff beizutragen, der weiter unten beschrieben wird. Der Befehl erhält als Argumente die URI des Dokuments, das Array der Änderungen darin und den Index der Änderung, auf die der Inline-Änderungsdiff-Editor gerade fokussiert ist. Hier ist zum Beispiel die Deklaration des Git-Befehls stageChange, der diesem Menü mit einer when-Klausel hinzugefügt wird, die prüft, ob der Kontextschlüssel originalResourceScheme gleich git ist.

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

SCM Eingabefeld

Das Source Control Eingabefeld, das sich oberhalb jeder Source Control-Ansicht befindet, ermöglicht dem Benutzer die Eingabe einer Nachricht. Sie können diese Nachricht abrufen (und festlegen), um Operationen durchzuführen. In Git wird dies beispielsweise als Commit-Feld verwendet, in das Benutzer Commit-Nachrichten eingeben und git commit-Befehle diese abgreifen.

export interface SourceControlInputBox {
  value: string;
}

export interface SourceControl {
  readonly inputBox: SourceControlInputBox;
}

Der Benutzer kann Strg+Eingabe (oder Cmd+Eingabe auf macOS) drücken, um eine beliebige Nachricht zu bestätigen. Sie können dieses Ereignis behandeln, indem Sie Ihrer SourceControl-Instanz einen acceptInputCommand zuweisen.

export interface SourceControl {
  readonly acceptInputCommand?: Command;
}

Quick Diff

VS Code unterstützt auch die Anzeige von Quick Diff-Editor-Randdekorationen. Das Klicken auf diese Dekorationen zeigt eine Inline-Diff-Erfahrung an, zu der Sie kontextbezogene Befehle beitragen können.

SCM quick diff

Diese Dekorationen werden von VS Code selbst berechnet. Alles, was Sie tun müssen, ist, VS Code die ursprünglichen Inhalte einer beliebigen Datei zur Verfügung zu stellen.

export interface SourceControl {
  quickDiffProvider?: QuickDiffProvider;
}

Mithilfe der Methode provideOriginalResource eines QuickDiffProvider kann Ihre Implementierung VS Code die Uri der ursprünglichen Ressource mitteilen, die der Ressource entspricht, deren Uri als Argument an die Methode übergeben wird.

Kombinieren Sie diese API mit der Methode registerTextDocumentContentProvider im workspace-Namespace, mit der Sie Inhalte für beliebige Ressourcen bereitstellen können, gegeben eine Uri, die dem benutzerdefinierten scheme entspricht, für das sie registriert ist.

Nächste Schritte

Um mehr über das VS Code-Erweiterbarkeitsmodell zu erfahren, probieren Sie diese Themen aus:

12/10/2025
© . This site is unofficial and not affiliated with Microsoft.