when clause Kontexte

Visual Studio Code setzt verschiedene Kontextschlüssel und spezifische Werte, abhängig davon, welche Elemente in der VS Code UI sichtbar und aktiv sind. Diese Kontexte können verwendet werden, um Erweiterungsbefehle und UI-Elemente, wie Menüs und Ansichten, selektiv zu aktivieren oder zu deaktivieren.

Zum Beispiel verwendet VS Code when clauses, um Tastenkombinationen für Befehle zu aktivieren oder zu deaktivieren, was Sie in der JSON-Datei für Standardtastenkombinationen sehen können (Einstellungen: Standardtastenkombinationen (JSON) öffnen).

{ "key": "f5",  "command": "workbench.action.debug.start",
                   "when": "debuggersAvailable && !inDebugMode" },

Oben hat der integrierte Befehl Debuggen starten die Tastenkombination F5, die nur aktiviert ist, wenn ein geeigneter Debugger verfügbar ist (Kontextschlüssel debuggersAvailable ist true) und der Editor sich nicht im Debug-Modus befindet (Kontextschlüssel inDebugMode ist false).

Bedingte Operatoren

Eine when clause kann aus einem Kontextschlüssel (z.B. inDebugMode) bestehen oder verschiedene Operatoren verwenden, um nuanciertere Editorzustände auszudrücken.

Logische Operatoren

Logische Operatoren ermöglichen die Kombination einfacher Kontextschlüssel oder when-clause-Ausdrücke, die andere logische Operatoren, Gleichheitsoperatoren, Vergleichsoperatoren, Match-Operatoren, in/not in Operatoren oder geklammerte Ausdrücke enthalten.

Hinweis zur Priorität logischer Operatoren: Die obige Tabelle listet Operatoren in absteigender Reihenfolge der Priorität auf. Beispiele

Gleichheitsoperatoren

Sie können die Gleichheit eines Kontextschlüsselwerts mit einem angegebenen Wert prüfen. Beachten Sie, dass die rechte Seite ein Wert ist und nicht als Kontextschlüssel interpretiert wird, d.h., sie wird nicht im Kontext nachgeschlagen.

Hinweise

• Wenn der Wert auf der rechten Seite ein String ist, der Leerzeichen enthält, muss er in einfache Anführungszeichen gesetzt werden - "resourceFilename == 'My New File.md'".
• === hat das gleiche Verhalten wie == und !== hat das gleiche Verhalten wie !=

Vergleichsoperatoren

Sie können den Wert eines Kontextschlüssels mit einer Zahl vergleichen. Beachten Sie, dass die linke und die rechte Seite des Operators durch ein Leerzeichen getrennt sein müssen - foo < 1, aber nicht foo<1.

Match-Operator

(früherer Name: Key-Value-Pair-Match-Operator)

Es gibt einen Match-Operator (=~) für when clauses. Der Ausdruck key =~ regularExpressionLiteral behandelt die rechte Seite als regulären Ausdrucksliteral zum Abgleich mit der linken Seite. Um beispielsweise Kontextmenüeinträge für alle Docker-Dateien beizutragen, könnte man verwenden

   "when": "resourceFilename =~ /docker/"

Hinweise

• Die rechte Seite des =~ Operators folgt den gleichen Regeln wie reguläre Ausdruckliterale (Referenz) in JavaScript, mit der Ausnahme, dass Zeichen sowohl den Escape-Regeln von JSON-Strings als auch regulären Ausdrücken folgen müssen. Zum Beispiel wäre ein regulärer Ausdrucksliteral zum Abgleich eines Substrings file:// /file:\/\// in JavaScript, aber /file:\\/\\// in einer when clause, da ein Backslash in einem JSON-String und ein Schrägstrich in einem regulären Ausdrucksmuster escaped werden muss.
• Es gibt keinen Operator !=~, aber Sie können den Match-Ausdruck negieren - !(foo =~ /baz/).

Reguläre Ausdruck-Flags

Es ist möglich, Flags mit den regulären Ausdrucksliteralen zu verwenden. Zum Beispiel resourceFilename =~ /json/i oder myContextKey =~ /baz/si.

Unterstützte Flags: i, s, m, u.

Ignorierte Flags: g, y.

'in' und 'not in' bedingte Operatoren

Der in Operator für when clauses ermöglicht die dynamische Suche nach dem Wert eines Kontextschlüssels innerhalb des Werts eines anderen Kontextschlüssels. Wenn Sie beispielsweise einen Kontextmenübefehl zu Ordnern hinzufügen möchten, die einen bestimmten Dateityp enthalten (oder etwas, das nicht statisch bekannt ist), können Sie nun den in Operator verwenden, um dies zu erreichen. Sie können den not in Operator verwenden, um die entgegengesetzte Bedingung zu prüfen.

Bestimmen Sie zuerst, welche Ordner den Befehl unterstützen sollen, und fügen Sie die Ordnernamen zu einem Array hinzu. Verwenden Sie dann den setContext Befehl, um das Array in einen Kontextschlüssel umzuwandeln.

vscode.commands.executeCommand('setContext', 'ext.supportedFolders', [
  'test',
  'foo',
  'bar'
]);

// or

// Note in this case (using an object), the value doesn't matter, it is based on the existence of the key in the object
// The value must be of a simple type
vscode.commands.executeCommand('setContext', 'ext.supportedFolders', {
  test: true,
  foo: 'anything',
  bar: false
});

Dann können Sie in der package.json eine Menübeitragung für das explorer/context Menü hinzufügen.

// Note, this assumes you have already defined a command called ext.doSpecial
"menus": {
  "explorer/context": [
    {
      "command": "ext.doSpecial",
      "when": "explorerResourceIsFolder && resourceFilename in ext.supportedFolders"
    }
  ]
}

In diesem Beispiel nehmen wir den Wert von resourceFilename (was in diesem Fall der Ordnername ist) und prüfen dessen Existenz im Wert von ext.supportedFolders. Wenn er existiert, wird das Menü angezeigt. Dieser leistungsstarke Operator sollte reichhaltigere bedingte und dynamische Beiträge ermöglichen, die when clauses unterstützen, z.B. Menüs, Ansichten usw.

Verfügbare Kontextschlüssel

Nachfolgend sind einige der verfügbaren Kontextschlüssel aufgeführt, die zu Boolean true/false ausgewertet werden.

Die Liste hier ist nicht vollständig und Sie können andere when clause Kontexte finden, indem Sie im Tastenkombinationen-Editor suchen und filtern (Einstellungen: Tastenkombinationen öffnen) oder die JSON-Datei für Standardtastenkombinationen überprüfen (Einstellungen: Standardtastenkombinationen (JSON) öffnen). Sie können auch Kontextschlüssel identifizieren, an denen Sie interessiert sind, mit dem Inspect Context Keys Utility.

Hinweis: Sie können jede Benutzer- oder Arbeitsbereichseinstellung, die zu einem booleschen Wert ausgewertet wird, hier mit dem Präfix "config." verwenden.

Sichtbare/Fokussierte Ansicht bei when clause Kontext

Sie können eine when clause haben, die prüft, ob eine bestimmte Ansicht sichtbar oder fokussiert ist.

Ansicht-Identifikatoren

• workbench.explorer.fileView - Datei-Explorer
• workbench.explorer.openEditorsView - Geöffnete Editoren
• outline - Gliederungsansicht
• timeline - Timeline-Ansicht
• workbench.scm - Quellcodeverwaltung
• workbench.scm.repositories - Quellcodeverwaltung Repositories
• workbench.debug.variablesView - Variablen
• workbench.debug.watchExpressionsView - Überwachung
• workbench.debug.callStackView - Aufrufstapel
• workbench.debug.loadedScriptsView - Geladene Skripte
• workbench.debug.breakPointsView - Haltepunkte
• workbench.debug.disassemblyView - Disassemblierung
• workbench.views.extensions.installed - Installierte Erweiterungen
• extensions.recommendedList - Empfohlene Erweiterungen
• workbench.panel.markers.view - Probleme
• workbench.panel.output - Ausgabe
• workbench.panel.repl.view - Debug-Konsole
• terminal - Integriertes Terminal
• workbench.panel.comments - Kommentare

Sichtbare Ansichtscontainer bei when clause Kontext

Sie können eine when clause haben, die prüft, ob ein bestimmter Ansichtscontainer sichtbar ist.

Ansichtscontainer-Identifikatoren

• workbench.view.explorer - Datei-Explorer
• workbench.view.search - Suche
• workbench.view.scm - Quellcodeverwaltung
• workbench.view.debug - Ausführen
• workbench.view.extensions - Erweiterungen
• workbench.panel.markers - Probleme
• workbench.panel.output - Ausgabe
• workbench.panel.repl - Debug-Konsole
• terminal - Integriertes Terminal
• workbench.panel.comments - Kommentare

Wenn Sie eine when clause wünschen, die nur aktiviert ist, wenn ein bestimmter Ansichtscontainer den Fokus hat, verwenden Sie sideBarFocus oder panelFocus oder auxiliaryBarFocus in Kombination mit den Kontextschlüsseln activeViewlet oder activePanel oder activeAuxiliary.

Zum Beispiel ist die folgende when clause nur dann wahr, wenn der Datei-Explorer den Fokus hat.

"sideBarFocus && activeViewlet == 'workbench.view.explorer'"

Eine Einstellung in einer when clause prüfen

In einer when clause können Sie auf einen Konfigurationswert (Einstellung) verweisen, indem Sie ihm das Präfix config. voranstellen, z.B. config.editor.tabCompletion oder config.breadcrumbs.enabled.

Einen benutzerdefinierten when clause Kontext hinzufügen

Wenn Sie Ihre eigene VS Code-Erweiterung erstellen und Befehle, Menüs oder Ansichten mithilfe eines when clause Kontexts aktivieren/deaktivieren müssen und keine der vorhandenen Schlüssel Ihren Anforderungen entspricht, können Sie Ihren eigenen Kontextschlüssel mit dem setContext Befehl hinzufügen.

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

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

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

Inspect Context Keys Utility

Wenn Sie alle aktuell aktiven Kontextschlüssel zur Laufzeit sehen möchten, können Sie den Befehl Entwickler: Kontextschlüssel inspizieren aus der Befehlspalette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) verwenden. Kontextschlüssel inspizieren zeigt Kontextschlüssel und ihre Werte in der **Konsole** der VS Code Developer Tools an (Hilfe > Entwicklertools umschalten).

Wenn Sie Entwickler: Kontextschlüssel inspizieren ausführen, hebt Ihr Cursor Elemente in der VS Code UI hervor, und wenn Sie auf ein Element klicken, werden die aktuellen Kontextschlüssel und ihre Zustände als Objekt in der Konsole ausgegeben.

Die Liste der aktiven Kontextschlüssel ist umfangreich und kann benutzerdefinierte Kontextschlüssel von installierten Erweiterungen enthalten.

Hinweis: Einige Kontextschlüssel sind für die interne Verwendung von VS Code bestimmt und können sich in Zukunft ändern.