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

Befehle

Befehle lösen Aktionen in Visual Studio Code aus. Wenn Sie jemals eine Tastenkombination konfiguriert haben, dann haben Sie mit Befehlen gearbeitet. Befehle werden auch von Erweiterungen verwendet, um Funktionalität für Benutzer bereitzustellen, Aktionen in der Benutzeroberfläche von VS Code zu binden und interne Logik zu implementieren.

Befehle verwenden

VS Code enthält eine große Anzahl von integrierten Befehlen, die Sie verwenden können, um mit dem Editor zu interagieren, die Benutzeroberfläche zu steuern oder Hintergrundoperationen durchzuführen. Viele Erweiterungen stellen auch ihre Kernfunktionalität als Befehle bereit, die Benutzer und andere Erweiterungen nutzen können.

Befehle programmatisch ausführen

Die API vscode.commands.executeCommand führt einen Befehl programmatisch aus. Dies ermöglicht Ihnen, die integrierten Funktionalitäten von VS Code zu nutzen und auf Erweiterungen wie die integrierten Git- und Markdown-Erweiterungen von VS Code aufzubauen.

Der Befehl editor.action.addCommentLine beispielsweise kommentiert die aktuell ausgewählten Zeilen im aktiven Texteditor

import * as vscode from 'vscode';

function commentLine() {
  vscode.commands.executeCommand('editor.action.addCommentLine');
}

Einige Befehle nehmen Argumente entgegen, die ihr Verhalten steuern. Befehle können auch ein Ergebnis zurückgeben. Der API-ähnliche Befehl vscode.executeDefinitionProvider fragt beispielsweise ein Dokument nach Definitionen an einer bestimmten Position ab. Er nimmt eine Dokument-URI und eine Position als Argumente entgegen und gibt ein Promise mit einer Liste von Definitionen zurück

import * as vscode from 'vscode';

async function printDefinitionsForActiveEditor() {
  const activeEditor = vscode.window.activeTextEditor;
  if (!activeEditor) {
    return;
  }

  const definitions = await vscode.commands.executeCommand<vscode.Location[]>(
    'vscode.executeDefinitionProvider',
    activeEditor.document.uri,
    activeEditor.selection.active
  );

  for (const definition of definitions) {
    console.log(definition);
  }
}

Verfügbare Befehle finden

Befehls-URIs

Befehls-URIs sind Links, die einen bestimmten Befehl ausführen. Sie können als klickbare Links in Hover-Texten, Abschlussdetails oder innerhalb von Webviews verwendet werden.

Ein Befehls-URI verwendet das Schema command, gefolgt vom Befehlsnamen. Der Befehls-URI für den Befehl editor.action.addCommentLine lautet beispielsweise command:editor.action.addCommentLine. Hier ist ein Hover-Provider, der einen Link in den Kommentaren der aktuellen Zeile im aktiven Texteditor anzeigt

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  vscode.languages.registerHoverProvider(
    'javascript',
    new (class implements vscode.HoverProvider {
      provideHover(
        _document: vscode.TextDocument,
        _position: vscode.Position,
        _token: vscode.CancellationToken
      ): vscode.ProviderResult<vscode.Hover> {
        const commentCommandUri = vscode.Uri.parse(`command:editor.action.addCommentLine`);
        const contents = new vscode.MarkdownString(`[Add comment](${commentCommandUri})`);

        // To enable command URIs in Markdown content, you must set the `isTrusted` flag.
        // When creating trusted Markdown string, make sure to properly sanitize all the
        // input content so that only expected command URIs can be executed
        contents.isTrusted = true;

        return new vscode.Hover(contents);
      }
    })()
  );
}

Die Liste der Argumente für den Befehl wird als JSON-Array übergeben, das ordnungsgemäß URI-kodiert ist: Das folgende Beispiel verwendet den Befehl git.stage, um einen Hover-Link zu erstellen, der die aktuelle Datei staged

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  vscode.languages.registerHoverProvider(
    'javascript',
    new (class implements vscode.HoverProvider {
      provideHover(
        document: vscode.TextDocument,
        _position: vscode.Position,
        _token: vscode.CancellationToken
      ): vscode.ProviderResult<vscode.Hover> {
        const args = [{ resourceUri: document.uri }];
        const stageCommandUri = vscode.Uri.parse(
          `command:git.stage?${encodeURIComponent(JSON.stringify(args))}`
        );
        const contents = new vscode.MarkdownString(`[Stage file](${stageCommandUri})`);
        contents.isTrusted = true;
        return new vscode.Hover(contents);
      }
    })()
  );
}

Sie können Befehls-URIs in Webviews aktivieren, indem Sie enableCommandUris in den WebviewOptions beim Erstellen des Webviews einstellen.

Neue Befehle erstellen

Einen Befehl registrieren

vscode.commands.registerCommand bindet eine Befehls-ID an eine Handler-Funktion in Ihrer Erweiterung

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const command = 'myExtension.sayHello';

  const commandHandler = (name: string = 'world') => {
    console.log(`Hello ${name}!!!`);
  };

  context.subscriptions.push(vscode.commands.registerCommand(command, commandHandler));
}

Die Handler-Funktion wird aufgerufen, wenn der Befehl myExtension.sayHello ausgeführt wird, sei es programmatisch mit executeCommand, über die VS Code-Benutzeroberfläche oder über eine Tastenkombination.

Einen benutzerorientierten Befehl erstellen

vscode.commands.registerCommand bindet nur eine Befehls-ID an eine Handler-Funktion. Um diesen Befehl in der Befehlspalette verfügbar zu machen, damit er für Benutzer auffindbar ist, benötigen Sie außerdem einen entsprechenden Befehls-contribution in der package.json Ihrer Erweiterung.

{
  "contributes": {
    "commands": [
      {
        "command": "myExtension.sayHello",
        "title": "Say Hello"
      }
    ]
  }
}

Der commands-Beitrag teilt VS Code mit, dass Ihre Erweiterung einen bestimmten Befehl bereitstellt und aktiviert werden soll, wenn dieser Befehl aufgerufen wird. Außerdem können Sie steuern, wie der Befehl in der Benutzeroberfläche angezeigt wird. Achten Sie darauf, die Namenskonventionen für Befehle zu befolgen, wenn Sie Befehle erstellen.

The contributed command in the Command Palette

Wenn ein Benutzer nun zum ersten Mal den Befehl myExtension.sayHello über die Befehlspalette oder eine Tastenkombination aufruft, wird die Erweiterung aktiviert und registerCommand bindet myExtension.sayHello an den entsprechenden Handler.

Hinweis: Erweiterungen, die auf VS Code-Versionen vor 1.74.0 abzielen, müssen explizit ein onCommand activationEvent für alle benutzerorientierten Befehle registrieren, damit die Erweiterung aktiviert wird und registerCommand ausgeführt wird.

{
  "activationEvents": ["onCommand:myExtension.sayHello"]
}

Sie benötigen kein onCommand Aktivierungsereignis für interne Befehle, aber Sie müssen sie für alle Befehle definieren, die

  • Über die Befehlspalette aufgerufen werden können.
  • Über eine Tastenkombination aufgerufen werden können.
  • Über die VS Code-Benutzeroberfläche aufgerufen werden können, z. B. über die Titelleiste des Editors.
  • Als API für andere Erweiterungen zur Nutzung vorgesehen sind.

Steuern, wann ein Befehl in der Befehlspalette angezeigt wird

Standardmäßig werden alle benutzerorientierten Befehle, die über den Abschnitt commands in der package.json beigesteuert werden, in der Befehlspalette angezeigt. Viele Befehle sind jedoch nur unter bestimmten Umständen relevant, z. B. wenn ein aktiver Texteditor einer bestimmten Sprache vorhanden ist oder wenn der Benutzer eine bestimmte Konfigurationsoption festgelegt hat.

Der Beitrag menus.commandPalette (menus.commandPalette) ermöglicht es Ihnen, einzugrenzen, wann ein Befehl in der Befehlspalette angezeigt werden soll. Er nimmt die ID des Zielbefehls und eine when-Klausel entgegen, die steuert, wann der Befehl angezeigt wird.

{
  "contributes": {
    "menus": {
      "commandPalette": [
        {
          "command": "myExtension.sayHello",
          "when": "editorLangId == markdown"
        }
      ]
    }
  }
}

Nun wird der Befehl myExtension.sayHello nur in der Befehlspalette angezeigt, wenn der Benutzer sich in einer Markdown-Datei befindet.

Aktivierung von Befehlen

Befehle unterstützen die Aktivierung über eine enablement-Eigenschaft – ihr Wert ist eine when-Klausel. Die Aktivierung gilt für alle Menüs und registrierte Tastenkombinationen.

Hinweis: Es gibt eine semantische Überschneidung zwischen enablement und der when-Bedingung von Menüelementen. Letztere wird verwendet, um das Anzeigen von Menüs voller deaktivierter Elemente zu verhindern. Beispielsweise sollte ein Befehl, der einen JavaScript-Regulären Ausdruck analysiert, wenn die Datei JavaScript ist, angezeigt werden und nur aktiviert werden, wenn der Cursor über einem regulären Ausdruck steht. Die when-Klausel verhindert Unordnung, indem der Befehl nicht für alle anderen Sprachdateien angezeigt wird. Das Verhindern von unübersichtlichen Menüs wird dringend empfohlen.

Schließlich implementieren Menüs, die Befehle anzeigen, wie die Befehlspalette oder Kontextmenüs, unterschiedliche Möglichkeiten, mit der Aktivierung umzugehen. Editor- und Explorer-Kontextmenüs rendern aktivierte/deaktivierte Elemente, während die Befehlspalette sie filtert.

Verwendung einer benutzerdefinierten when-Klausel-Kontext

Wenn Sie Ihre eigene VS Code-Erweiterung erstellen und Befehle, Menüs oder Ansichten über eine when-Klausel ein-/ausblenden müssen und keine der vorhandenen Schlüssel Ihren Bedürfnissen entsprechen, können Sie Ihren eigenen Kontext hinzufügen.

Das erste Beispiel unten setzt den Schlüssel myExtension.showMyCommand auf true, den Sie zur Aktivierung von Befehlen oder mit der when-Eigenschaft verwenden können. Das zweite Beispiel speichert einen Wert, den Sie mit einer when-Klausel verwenden könnten, um zu prüfen, ob die Anzahl der offenen coolen Dinge größer als 2 ist.

vscode.commands.executeCommand('setContext', 'myExtension.showMyCommand', true);

vscode.commands.executeCommand('setContext', 'myExtension.numberOfCoolOpenThings', 2);

Namenskonventionen

Beim Erstellen von Befehlen sollten Sie diese Namenskonventionen befolgen

  • Befehls-Titel
    • Verwenden Sie Kleinschreibung im Titel. Großbuchstaben für Präpositionen von vier oder weniger Buchstaben (wie an, zu, in, von, mit und für) vermeiden, es sei denn, die Präposition ist das erste oder letzte Wort.
    • Beginnen Sie mit einem Verb, um die auszuführende Aktion zu beschreiben.
    • Verwenden Sie ein Nomen, um das Ziel der Aktion zu beschreiben.
    • Vermeiden Sie die Verwendung von "Befehl" im Titel.
12/10/2025
© . This site is unofficial and not affiliated with Microsoft.