Beitragspunkte

Beitragspunkte sind eine Reihe von JSON-Deklarationen, die Sie im Feld contributes der package.json Extension Manifest vornehmen. Ihre Erweiterung registriert Beitragspunkte, um verschiedene Funktionalitäten innerhalb von Visual Studio Code zu erweitern. Hier ist eine Liste aller verfügbaren Beitragspunkte

• authentication
• Haltepunkte
• Farben
• Befehle
• Konfiguration
• Konfigurationsstandards
• Benutzerdefinierte Editoren
• Debugger
• Grammatiken
• Symbole
• Symbolthemen
• JSON-Validierung
• Tastenkombinationen
• Sprachen
• Menüs
• Problem-Matcher
• Problem-Muster
• Produkt-Symbolthemen
• Ressourcen-Label-Formatierer
• Semantische Token-Modifikatoren
• Semantische Token-Geltungsbereiche
• Semantische Token-Typen
• Snippets
• Untermenüs
• Aufgabendefinitionen
• Terminal
• Themen
• TypeScript-Server-Plugins
• Ansichten
• Ansicht-Container
• Ansichts-Willkommensnachrichten
• Walkthroughs

contributes.authentication

Stellt einen Authentifizierungsanbieter bereit. Dies richtet ein Aktivierungsereignis für Ihren Anbieter ein und zeigt ihn in den Funktionen Ihrer Erweiterung an.

{
  "contributes": {
    "authentication": [
      {
        "label": "Azure DevOps",
        "id": "azuredevops"
      }
    ]
  }
}

contributes.breakpoints

Normalerweise hat eine Debuggererweiterung auch einen contributes.breakpoints-Eintrag, in dem die Erweiterung die Dateitypen der Sprachen auflistet, für die das Setzen von Haltepunkten aktiviert wird.

{
  "contributes": {
    "breakpoints": [
      {
        "language": "javascript"
      },
      {
        "language": "javascriptreact"
      }
    ]
  }
}

contributes.colors

Trägt neue, thematisierbare Farben bei. Diese Farben können von der Erweiterung in Editor-Dekorationen und in der Statusleiste verwendet werden. Nach der Definition können Benutzer die Farbe in der Einstellung workspace.colorCustomization anpassen und Benutzerthemen können den Farbwert festlegen.

{
  "contributes": {
    "colors": [
      {
        "id": "superstatus.error",
        "description": "Color for error message in the status bar.",
        "defaults": {
          "dark": "errorForeground",
          "light": "errorForeground",
          "highContrast": "#010203",
          "highContrastLight": "#feedc3"
        }
      }
    ]
  }
}

Standardfarbwerte können für helle, dunkle und kontrastreiche Themen definiert werden und entweder ein Verweis auf eine vorhandene Farbe oder ein Farbe-Hex-Wert sein.

Erweiterungen können neue und vorhandene Theme-Farben mit der ThemeColor API konsumieren

const errorColor = new vscode.ThemeColor('superstatus.error');

contributes.commands

Stellt die Benutzeroberfläche für einen Befehl bereit, bestehend aus einem Titel und (optional) einem Symbol, einer Kategorie und einem aktivierten Zustand. Die Aktivierung wird mit when-Klauseln ausgedrückt. Standardmäßig werden Befehle in der Befehlspalette angezeigt (⇧⌘P (Windows, Linux Ctrl+Shift+P)), aber sie können auch in anderen Menüs angezeigt werden.

Die Darstellung von beigetragenen Befehlen hängt vom enthaltenden Menü ab. Die Befehlspalette beispielsweise stellt Befehlen ihre Kategorie voran, was eine einfache Gruppierung ermöglicht. Die Befehlspalette zeigt jedoch keine Symbole oder deaktivierte Befehle an. Das Kontextmenü des Editors hingegen zeigt deaktivierte Elemente an, aber nicht die Kategoriebezeichnung.

Hinweis: Wenn ein Befehl aufgerufen wird (über eine Tastenkombination, aus der Befehlspalette, einem anderen Menü oder programmatisch), gibt VS Code ein Aktivierungsereignis onCommand:${command} aus.

Hinweis: Bei Verwendung von Symbolen aus Produkt-Symbolen deaktiviert das Setzen von light und dark das Symbol. Die korrekte Syntax lautet "icon": "$(book)"

Befehlsbeispiel

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": {
          "light": "path/to/light/icon.svg",
          "dark": "path/to/dark/icon.svg"
        }
      }
    ]
  }
}

Erfahren Sie im Befehls-Erweiterungsleitfaden mehr über die Verwendung von Befehlen in VS Code-Erweiterungen.

Spezifikationen für Befehlssymbole

• Größe: Symbole sollten 16x16 sein mit 1 Pixel Polsterung (Bild ist 14x14) und zentriert.
• Farbe: Symbole sollten eine einzelne Farbe verwenden.
• Format: Es wird empfohlen, dass Symbole im SVG-Format vorliegen, obwohl jeder Bilddateityp akzeptiert wird.

contributes.configuration

Stellen Sie Einstellungen bereit, die dem Benutzer angezeigt werden. Der Benutzer kann diese Konfigurationsoptionen im Einstellungseditor festlegen oder indem er eine settings.json-Datei direkt bearbeitet.

Dieser Abschnitt kann entweder ein einzelnes Objekt sein, das eine einzelne Kategorie von Einstellungen darstellt, oder ein Array von Objekten, das mehrere Kategorien von Einstellungen darstellt. Wenn es mehrere Kategorien von Einstellungen gibt, zeigt der Einstellungseditor ein Untermenü im Inhaltsverzeichnis für diese Erweiterung an, und die Titel-Schlüssel werden für die Untermenü-Eintrag-Namen verwendet.

Konfigurationsbeispiel

{
  "contributes": {
    "configuration": {
      "title": "Settings Editor Test Extension",
      "type": "object",
      "properties": {
        "settingsEditorTestExtension.booleanExample": {
          "type": "boolean",
          "default": true,
          "description": "Boolean Example"
        },
        "settingsEditorTestExtension.stringExample": {
          "type": "string",
          "default": "Hello World",
          "description": "String Example"
        }
      }
    }
  }
}

Sie können diese Werte aus Ihrer Erweiterung mit vscode.workspace.getConfiguration('myExtension') lesen.

Konfigurationsschema

Ihr Konfigurationseintrag wird sowohl zur Bereitstellung von IntelliSense beim Bearbeiten Ihrer Einstellungen im JSON-Editor als auch zur Definition der Darstellung in der Einstellungs-UI verwendet.

Titel

Der Titel 1️⃣ einer Kategorie ist die Überschrift für diese Kategorie.

{
  "configuration": {
    "title": "GitMagic"
  }
}

Für eine Erweiterung mit mehreren Einstellungskategorien gilt: Wenn der Titel einer der Kategorien mit dem Anzeigenamen der Erweiterung übereinstimmt, behandelt die Einstellungs-UI diese Kategorie als "Standardkategorie", ignoriert das Feld Reihenfolge für diese Kategorie und platziert ihre Einstellungen unter der Hauptüberschrift der Erweiterung.

Sowohl für die Felder Titel als auch anzeigename sind Wörter wie "Erweiterung", "Konfiguration" und "Einstellungen" redundant.

• ✔ "Titel": "GitMagic"
• ❌ "Titel": "GitMagic Erweiterung"
• ❌ "Titel": "GitMagic Konfiguration"
• ❌ "Titel": "GitMagic Erweiterungs-Konfigurationseinstellungen"

Eigenschaften

Die Eigenschaften 2️⃣ in Ihrem Konfiguration-Objekt bilden ein Wörterbuch, dessen Schlüssel Einstellungs-IDs sind und dessen Werte weitere Informationen zur Einstellung liefern. Obwohl eine Erweiterung mehrere Einstellungskategorien enthalten kann, muss jede Einstellung der Erweiterung immer noch ihre eigene eindeutige ID haben. Eine Einstellungs-ID kann kein vollständiges Präfix einer anderen Einstellungs-ID sein.

Eigenschaften ohne explizites Reihenfolge-Feld werden in der Einstellungs-UI in lexikografischer Reihenfolge angezeigt (nicht in der Reihenfolge, in der sie im Manifest aufgeführt sind).

Einstellungstitel

In der Einstellungs-UI werden mehrere Felder verwendet, um einen Anzeigetitel für jede Einstellung zu erstellen. Großbuchstaben in Ihrem Schlüssel zeigen Wortumbrüche an.

Anzeigetitel für Ein-Kategorie- und Standardkategorie-Konfigurationen

Wenn die Konfiguration nur eine einzige Einstellungskategorie hat oder wenn die Kategorie denselben Titel wie der Anzeigename der Erweiterung hat, dann verwendet die Einstellungs-UI für Einstellungen innerhalb dieser Kategorie die Einstellungs-ID und das Erweiterungsfeld name, um den Anzeigetitel zu bestimmen.

Als Beispiel für die Einstellungs-ID gitMagic.blame.dateFormat und den Erweiterungsnamen authorName.gitMagic wird, da das Präfix der Einstellungs-ID mit dem Suffix des Erweiterungsnamens übereinstimmt, der Teil gitMagic der Einstellungs-ID im Anzeigetitel entfernt: "Blame: Date Format".

Anzeigetitel für Multi-Kategorie-Konfigurationen

Wenn die Konfiguration mehrere Einstellungskategorien hat und die Kategorie nicht denselben Titel wie der Anzeigename der Erweiterung hat, dann verwendet die Einstellungs-UI für Einstellungen innerhalb dieser Kategorie die Einstellungs-ID und das Kategorie-Feld id, um den Anzeigetitel zu bestimmen.

Als Beispiel für die Einstellungs-ID css.completion.completePropertyWithSemicolon und die Kategorie-ID css wird, da das Präfix der Einstellungs-ID mit dem Suffix der Kategorie-ID übereinstimmt, der Teil css der Einstellungs-ID in der Einstellungs-UI entfernt, und der generierte Titel für die Einstellung lautet "Completion: Complete Property With Semicolon".

Konfigurationseigenschaftsschema

Konfigurationsschlüssel werden mithilfe einer Obermenge von JSON Schema definiert.

Beschreibung / markdownBeschreibung

Ihre Beschreibung 3️⃣ erscheint nach dem Titel und vor dem Eingabefeld, außer bei Booleans, wo die Beschreibung als Beschriftung für die Checkbox verwendet wird. 6️⃣

{
  "gitMagic.blame.heatMap.enabled": {
    "description": "Specifies whether to provide a heatmap indicator in the gutter blame annotations"
  }
}

Wenn Sie markdownBeschreibung anstelle von Beschreibung verwenden, wird Ihre Einstellungsbeschreibung in der Einstellungs-UI als Markdown analysiert.

{
  "gitMagic.blame.dateFormat": {
    "markdownDescription": "Specifies how to format absolute dates (e.g. using the `${date}` token) in gutter blame annotations. See the [Moment.js docs](https://momentjs.com/docs/#/displaying/format/) for valid formats"
  }
}

Für markdownBeschreibung verwenden Sie \n\n, um Absätze zu trennen, anstatt nur \n, um Zeilenumbrüche oder mehrere Absätze hinzuzufügen.

type

Einträge vom Typ Zahl 4️⃣ , Zeichenkette 5️⃣ , Boolesch 6️⃣ können direkt in der Einstellungs-UI bearbeitet werden.

{
  "gitMagic.views.pageItemLimit": {
    "type": "number",
    "default": 20,
    "markdownDescription": "Specifies the number of items to show in each page when paginating a view list. Use 0 to specify no limit"
  }
}

Eine Zeichenketteneinstellung kann mit einer mehrzeiligen Texteingabe gerendert werden, wenn "editPresentation": "multilineText" für den Konfigurationseintrag gesetzt ist.

Für Boolesch-Einträge wird die markdownBeschreibung (oder Beschreibung, wenn markdownBeschreibung nicht angegeben ist) als Beschriftung neben der Checkbox verwendet.

{
  "gitMagic.blame.compact": {
    "type": "boolean",
    "description": "Specifies whether to compact (deduplicate) matching adjacent gutter blame annotations"
  }
}

Einige Objekt- und Array-Typ-Einstellungen werden in der Einstellungs-UI gerendert. Einfache Arrays von Zahl, Zeichenkette oder Boolesch werden als editierbare Listen gerendert. Objekte mit Eigenschaften vom Typ Zeichenkette, Zahl, Ganzzahl und/oder Boolesch werden als editierbare Raster von Schlüsseln und Werten gerendert. Objekteinstellungen sollten auch additionalProperties auf false oder auf ein Objekt mit einer geeigneten Typ-Eigenschaft gesetzt haben, um in der UI gerendert zu werden.

Wenn eine Objekt- oder Array-Typ-Einstellung auch andere Typen wie verschachtelte Objekte, Arrays oder null enthalten kann, dann wird der Wert nicht in der Einstellungs-UI gerendert und kann nur durch Bearbeitung des JSON direkt geändert werden. Benutzer sehen einen Link zu In settings.json bearbeiten, wie im obigen Screenshot gezeigt. 8️⃣

Reihenfolge

Sowohl Kategorien als auch die Einstellungen innerhalb dieser Kategorien können eine ganzzahlige Reihenfolge-Eigenschaft aufweisen, die eine Referenz darauf gibt, wie sie relativ zu anderen Kategorien und/oder Einstellungen sortiert werden sollen.

Wenn zwei Kategorien Reihenfolge-Eigenschaften haben, kommt die Kategorie mit der niedrigeren Ordnungszahl zuerst. Wenn einer Kategorie keine Reihenfolge-Eigenschaft zugewiesen wird, erscheint sie nach den Kategorien, denen diese Eigenschaft zugewiesen wurde.

Wenn zwei Einstellungen innerhalb derselben Kategorie Reihenfolge-Eigenschaften haben, kommt die Einstellung mit der niedrigeren Ordnungszahl zuerst. Wenn einer anderen Einstellung innerhalb derselben Kategorie keine Reihenfolge-Eigenschaft zugewiesen wird, erscheint sie nach den Einstellungen in dieser Kategorie, denen diese Eigenschaft zugewiesen wurde.

Wenn zwei Kategorien denselben Reihenfolge-Eigenschaftswert haben oder wenn zwei Einstellungen innerhalb derselben Kategorie denselben Reihenfolge-Eigenschaftswert haben, dann werden sie in der Einstellungs-UI in aufsteigender lexikografischer Reihenfolge sortiert.

Aufzählung / AufzählungsBeschreibungen / markdownAufzählungsBeschreibungen / AufzählungElementBeschriftungen

Wenn Sie ein Array von Elementen unter der Aufzählung 7️⃣ -Eigenschaft bereitstellen, rendert die Einstellungs-UI ein Dropdown-Menü mit diesen Elementen.

Sie können auch eine AufzählungsBeschreibungen-Eigenschaft bereitstellen, ein Array von Zeichenketten mit der gleichen Länge wie die Aufzählung-Eigenschaft. Die AufzählungsBeschreibungen-Eigenschaft bietet eine Beschreibung in der Einstellungs-UI am unteren Rand des Dropdown-Menüs, die jedem Aufzählung-Element entspricht.
Sie können auch markdownAufzählungsBeschreibungen anstelle von AufzählungsBeschreibungen verwenden, und Ihre Beschreibungen werden als Markdown analysiert. markdownAufzählungsBeschreibungen hat Vorrang vor AufzählungsBeschreibungen.
Um die Dropdown-Optionsnamen in der Einstellungs-UI anzupassen, können Sie AufzählungsElementBeschriftungen verwenden.

Beispiel

{
  "settingsEditorTestExtension.enumSetting": {
    "type": "string",
    "enum": ["first", "second", "third"],
    "markdownEnumDescriptions": [
      "The *first* enum",
      "The *second* enum",
      "The *third* enum"
    ],
    "enumItemLabels": ["1st", "2nd", "3rd"],
    "default": "first",
    "description": "Example setting with an enum"
  }
}

Deprecation-Nachricht / markdownDeprecation-Nachricht

Wenn Sie Deprecation-Nachricht oder markdownDeprecation-Nachricht festlegen, erhält die Einstellung eine Warnungsunterstreichung mit Ihrer angegebenen Nachricht. Außerdem wird die Einstellung aus der Einstellungs-UI ausgeblendet, es sei denn, sie wurde vom Benutzer konfiguriert. Wenn Sie markdownDeprecation-Nachricht festlegen, wird das Markdown nicht im Einstellungs-Hover oder in der Problemansicht gerendert. Wenn Sie beide Eigenschaften festlegen, wird Deprecation-Nachricht im Hover und in der Problemansicht angezeigt, und markdownDeprecation-Nachricht wird in der Einstellungs-UI als Markdown gerendert.

Beispiel

{
  "json.colorDecorators.enable": {
    "type": "boolean",
    "description": "Enables or disables color decorators",
    "markdownDeprecationMessage": "**Deprecated**: Please use `#editor.colorDecorators#` instead.",
    "deprecationMessage": "Deprecated: Please use editor.colorDecorators instead."
  }
}

Andere JSON-Schema-Eigenschaften

Sie können jede der Validierungs-JSON-Schema-Eigenschaften verwenden, um andere Einschränkungen für Konfigurationswerte zu beschreiben

• Standard zur Definition des Standardwerts einer Eigenschaft
• Minimum und Maximum zur Beschränkung numerischer Werte
• maxLength, minLength zur Beschränkung der Zeichenkettenlänge
• Muster zur Beschränkung von Zeichenketten auf einen gegebenen regulären Ausdruck
• patternErrorMessage zur Angabe einer maßgeschneiderten Fehlermeldung, wenn ein Muster nicht übereinstimmt.
• Format zur Beschränkung von Zeichenketten auf bekannte Formate wie Datum, Uhrzeit, ipv4, E-Mail und URI
• maxItems, minItems zur Beschränkung der Array-Länge
• editPresentation zur Steuerung, ob ein einzeiliger Eingabefeld oder ein mehrzeiliges Textfeld für die Zeichenketteneinstellung im Einstellungseditor gerendert wird

Nicht unterstützte JSON-Schema-Eigenschaften

Im Konfigurationsabschnitt nicht unterstützt sind

• $ref und definition: Die Konfigurationsschemata müssen in sich abgeschlossen sein und können keine Annahmen darüber treffen, wie das aggregierte Einstellungs-JSON-Schemadokument aussieht.

Weitere Details zu diesen und anderen Funktionen finden Sie in der JSON Schema Referenz.

Geltungsbereich

Eine Konfigurationseinstellung kann einen der folgenden möglichen Geltungsbereiche haben

• Anwendung - Einstellungen, die für alle Instanzen von VS Code gelten und nur in Benutzereinstellungen konfiguriert werden können.
• Maschine - Maschinenspezifische Einstellungen, die nur in Benutzereinstellungen oder nur in Remote-Einstellungen gesetzt werden können. Zum Beispiel ein Installationspfad, der nicht über Maschinen hinweg geteilt werden sollte. Der Wert dieser Einstellungen wird nicht synchronisiert.
• maschinenüberschreibbar - Maschinenspezifische Einstellungen, die durch Arbeitsbereichs- oder Ordner-Einstellungen überschrieben werden können. Der Wert dieser Einstellungen wird nicht synchronisiert.
• Fenster - Fensterspezifische Einstellungen, die in Benutzer-, Arbeitsbereichs- oder Remote-Einstellungen konfiguriert werden können.
• Ressource - Ressourceneinstellungen, die für Dateien und Ordner gelten und auf allen Einstellungsebenen, auch in Ordner-Einstellungen, konfiguriert werden können.
• sprachenüberschreibbar - Ressourceneinstellungen, die auf Sprachebene überschrieben werden können.

Konfigurationsbereiche bestimmen, wann eine Einstellung dem Benutzer über den Einstellungseditor zur Verfügung steht und ob die Einstellung anwendbar ist. Wenn kein Geltungsbereich deklariert wird, ist der Standardwert Fenster.

Unten sind Beispiel-Konfigurationsbereiche aus der integrierten Git-Erweiterung aufgeführt

{
  "contributes": {
    "configuration": {
      "title": "Git",
      "properties": {
        "git.alwaysSignOff": {
          "type": "boolean",
          "scope": "resource",
          "default": false,
          "description": "%config.alwaysSignOff%"
        },
        "git.ignoredRepositories": {
          "type": "array",
          "default": [],
          "scope": "window",
          "description": "%config.ignoredRepositories%"
        },
        "git.autofetch": {
          "type": ["boolean", "string"],
          "enum": [true, false, "all"],
          "scope": "resource",
          "markdownDescription": "%config.autofetch%",
          "default": false,
          "tags": ["usesOnlineServices"]
        }
      }
    }
  }
}

Sie sehen, dass git.alwaysSignOff den Ressource-Geltungsbereich hat und pro Benutzer, Arbeitsbereich oder Ordner gesetzt werden kann, während die Liste der ignorierten Repositorys mit Fenster-Geltungsbereich globaler für das VS Code-Fenster oder den Arbeitsbereich (der möglicherweise mehrstufig ist) gilt.

Sync ignorieren

Sie können ignoreSync auf true setzen, um zu verhindern, dass die Einstellung mit den Benutzereinstellungen synchronisiert wird. Dies ist nützlich für Einstellungen, die nicht benutzerspezifisch sind. Zum Beispiel ist die Einstellung remoteTunnelAccess.machineName nicht benutzerspezifisch und sollte nicht synchronisiert werden. Bitte beachten Sie, dass, wenn Sie den Geltungsbereich auf Maschine oder maschinenüberschreibbar gesetzt haben, die Einstellung unabhängig vom Wert von ignoreSync nicht synchronisiert wird.

{
  "contributes": {
    "configuration": {
      "properties": {
        "remoteTunnelAccess.machineName": {
          "type": "string",
          "default": "",
          "ignoreSync": true
        }
      }
    }
  }
}

Verknüpfung zu Einstellungen

Sie können einen Link zu einer anderen Einstellung einfügen, der als anklickbarer Link in der Einstellungs-UI gerendert wird, indem Sie diese spezielle Syntax in den Markdown-Typ-Eigenschaften verwenden: `#ziel.einstellungs.id#`. Dies funktioniert in markdownBeschreibung, markdownAufzählungsBeschreibungen und markdownDeprecation-Nachricht. Beispiel

  "files.autoSaveDelay": {
    "markdownDescription": "Controls the delay in ms after which a dirty editor is saved automatically. Only applies when `#files.autoSave#` is set to `afterDelay`.",
    // ...
  }

In der Einstellungs-UI wird dies gerendert als

contributes.configurationDefaults

Tragen Sie Standardwerte für andere registrierte Konfigurationen bei und überschreiben Sie deren Standardwerte.

Das folgende Beispiel überschreibt das Standardverhalten der Einstellung files.autoSave, um Dateien beim Fokuswechsel automatisch zu speichern.

"configurationDefaults": {
      "files.autoSave": "onFocusChange"
}

Sie können auch Standard-Editor-Konfigurationen für die bereitgestellte Sprache beitragen. Zum Beispiel trägt das folgende Snippet Standard-Editor-Konfigurationen für die Markdown-Sprache bei

{
  "contributes": {
    "configurationDefaults": {
      "[markdown]": {
        "editor.wordWrap": "on",
        "editor.quickSuggestions": {
          "comments": "off",
          "strings": "off",
          "other": "off"
        }
      }
    }
  }
}

contributes.customEditors

Der customEditors-Beitragspunkt ist die Art und Weise, wie Ihre Erweiterung VS Code über die benutzerdefinierten Editoren informiert, die sie bereitstellt. VS Code muss beispielsweise wissen, mit welchen Dateitypen Ihr benutzerdefinierter Editor arbeitet und wie Ihr benutzerdefinierter Editor in jeder UI identifiziert werden kann.

Hier ist ein grundlegender customEditor-Beitrag für das Benutzerdefinierter Editor Erweiterungs-Sample

"contributes": {
  "customEditors": [
    {
      "viewType": "catEdit.catScratch",
      "displayName": "Cat Scratch",
      "selector": [
        {
          "filenamePattern": "*.cscratch"
        }
      ],
      "priority": "default"
    }
  ]
}

customEditors ist ein Array, sodass Ihre Erweiterung mehrere benutzerdefinierte Editoren beisteuern kann.

• viewType - Eindeutiger Identifikator für Ihren benutzerdefinierten Editor.

  Dies ist, wie VS Code einen benutzerdefinierten Editorbeitrag in der package.json mit Ihrer benutzerdefinierten Editorimplementierung im Code verknüpft. Dies muss über alle Erweiterungen hinweg eindeutig sein. Verwenden Sie daher anstelle eines generischen viewType wie "preview" einen, der für Ihre Erweiterung eindeutig ist, z. B. "viewType": "myAmazingExtension.svgPreview".

• displayName - Name, der den benutzerdefinierten Editor in der VS Code-UI identifiziert.

  Der Anzeigename wird dem Benutzer in der VS Code-UI angezeigt, z. B. im Dropdown-Menü Anzeigen: Erneut öffnen mit.

• selector - Gibt an, für welche Dateien ein benutzerdefinierter Editor aktiv ist.

  Der Selektor ist ein Array von einem oder mehreren Glob-Mustern. Diese Glob-Muster werden mit Dateinamen abgeglichen, um zu bestimmen, ob der benutzerdefinierte Editor dafür verwendet werden kann. Ein Dateinamenmuster wie *.png aktiviert den benutzerdefinierten Editor für alle PNG-Dateien.

  Sie können auch spezifischere Muster erstellen, die auf Datei- oder Verzeichnisnamen basieren, z. B. **/translations/*.json.

• priority - (optional) Gibt an, wann der benutzerdefinierte Editor verwendet wird.

  priority steuert, wann ein benutzerdefinierter Editor verwendet wird, wenn eine Ressource geöffnet ist. Mögliche Werte sind

  • "default" - Versuchen Sie, den benutzerdefinierten Editor für jede Datei zu verwenden, die mit dem Selektor des benutzerdefinierten Editors übereinstimmt. Wenn mehrere benutzerdefinierte Editoren für eine bestimmte Datei vorhanden sind, muss der Benutzer auswählen, welchen benutzerdefinierten Editor er verwenden möchte.
  • "option" - Verwenden Sie den benutzerdefinierten Editor nicht standardmäßig, sondern erlauben Sie Benutzern, ihn zu wechseln oder als Standard festzulegen.

Mehr dazu erfahren Sie im Leitfaden für benutzerdefinierte Editoren.

contributes.debuggers

Stellen Sie einen Debugger für VS Code bereit. Ein Debugger-Beitrag hat die folgenden Eigenschaften

• type ist eine eindeutige ID, die zur Identifizierung dieses Debuggers in einer Startkonfiguration verwendet wird.
• label ist der für Benutzer sichtbare Name dieses Debuggers in der UI.
• program der Pfad zum Debug-Adapter, der das VS Code-Debug-Protokoll gegen den realen Debugger oder die Laufzeit implementiert.
• runtime falls der Pfad zum Debug-Adapter kein ausführbares Programm ist, aber eine Laufzeit benötigt.
• configurationAttributes ist das Schema für Startkonfigurationsargumente, die für diesen Debugger spezifisch sind. Bitte beachten Sie, dass die JSON-Schema-Konstrukte $ref und definition nicht unterstützt werden.
• initialConfigurations listet Startkonfigurationen auf, die verwendet werden, um eine anfängliche launch.json zu füllen.
• configurationSnippets listet Startkonfigurationen auf, die über IntelliSense beim Bearbeiten einer launch.json verfügbar sind.
• variables führt Ersetzungsvariablen ein und bindet sie an Befehle, die von der Debuggererweiterung implementiert werden.
• languages jene Sprachen, für die die Debug-Erweiterung als "Standard-Debugger" betrachtet werden könnte.

Debugger-Beispiel

{
  "contributes": {
    "debuggers": [
      {
        "type": "node",
        "label": "Node Debug",

        "program": "./out/node/nodeDebug.js",
        "runtime": "node",

        "languages": ["javascript", "typescript", "javascriptreact", "typescriptreact"],

        "configurationAttributes": {
          "launch": {
            "required": ["program"],
            "properties": {
              "program": {
                "type": "string",
                "description": "The program to debug."
              }
            }
          }
        },

        "initialConfigurations": [
          {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "program": "${workspaceFolder}/app.js"
          }
        ],

        "configurationSnippets": [
          {
            "label": "Node.js: Attach Configuration",
            "description": "A new configuration for attaching to a running node program.",
            "body": {
              "type": "node",
              "request": "attach",
              "name": "${2:Attach to Port}",
              "port": 9229
            }
          }
        ],

        "variables": {
          "PickProcess": "extension.node-debug.pickNodeProcess"
        }
      }
    ]
  }
}

Für eine vollständige Anleitung zur Integration eines Debuggers gehen Sie zu Debugger-Erweiterung.

contributes.grammars

Tragen Sie eine TextMate-Grammatik zu einer Sprache bei. Sie müssen die Sprache, für die diese Grammatik gilt, den TextMate-scopeName für die Grammatik und den Dateipfad angeben.

Hinweis: Die Datei, die die Grammatik enthält, kann im JSON-Format (Dateinamen enden auf .json) oder im XML-Plist-Format (alle anderen Dateien) vorliegen.

Grammatik-Beispiel

{
  "contributes": {
    "grammars": [
      {
        "language": "markdown",
        "scopeName": "text.html.markdown",
        "path": "./syntaxes/markdown.tmLanguage.json",
        "embeddedLanguages": {
          "meta.embedded.block.frontmatter": "yaml"
        }
      }
    ]
  }
}

Sehen Sie sich den Leitfaden zur Syntaxhervorhebung an, um mehr darüber zu erfahren, wie TextMate-Grammatiken, die mit einer Sprache verbunden sind, registriert werden, um eine Syntaxhervorhebung zu erhalten.

contributes.icons

Stellen Sie ein neues Symbol anhand seiner ID bereit, zusammen mit einem Standard-Symbol. Die Symbol-ID kann dann von der Erweiterung (oder jeder anderen Erweiterung, die von der Erweiterung abhängt) überall dort verwendet werden, wo ein ThemeIcon verwendet werden kann, z. B. new ThemeIcon("iconId"), in Markdown-Zeichenketten ($(iconId)) und als Symbole in bestimmten Beitragspunkten.

{
  "contributes": {
    "icons": {
      "distro-ubuntu": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E001"
        }
      },
      "distro-fedora": {
        "description": "Ubuntu icon",
        "default": {
          "fontPath": "./distroicons.woff",
          "fontCharacter": "\\E002"
        }
      }
    }
  }
}

contributes.iconThemes

Stellen Sie ein Dateisymbolthema für VS Code bereit. Dateisymbole werden neben Dateinamen angezeigt und kennzeichnen den Dateityp.

Sie müssen eine ID (die in den Einstellungen verwendet wird), eine Bezeichnung und den Pfad zur Dateisymboldefinitionsdatei angeben.

Datei-Symbolthema-Beispiel

{
  "contributes": {
    "iconThemes": [
      {
        "id": "my-cool-file-icons",
        "label": "Cool File Icons",
        "path": "./fileicons/cool-file-icon-theme.json"
      }
    ]
  }
}

Sehen Sie sich den Leitfaden zu Dateisymbolthemen an, um zu erfahren, wie Sie ein Dateisymbolthema erstellen.

contributes.jsonValidation

Stellen Sie ein Validierungsschema für einen bestimmten Typ von JSON-Dateien bereit. Der URL-Wert kann entweder ein lokaler Pfad zu einer in der Erweiterung enthaltenen Schemadatei oder eine URL eines Remote-Servers sein, z. B. ein JSON Schema Store.

{
  "contributes": {
    "jsonValidation": [
      {
        "fileMatch": ".jshintrc",
        "url": "https://json.schemastore.org/jshintrc"
      }
    ]
  }
}

contributes.keybindings

Stellen Sie eine Tastenkombinationsregel bereit, die definiert, welcher Befehl ausgeführt werden soll, wenn der Benutzer eine Tastenkombination drückt. Sehen Sie sich das Thema Tastenkombinationen an, wo Tastenkombinationen im Detail erklärt werden.

Das Beitragen einer Tastenkombination bewirkt, dass die Standard-Tastenkombinationen Ihre Regel anzeigen, und jede UI-Darstellung des Befehls zeigt nun die von Ihnen hinzugefügte Tastenkombination an. Und natürlich wird der Befehl ausgeführt, wenn der Benutzer die Tastenkombination drückt.

Hinweis: Da VS Code unter Windows, macOS und Linux läuft, wo die Modifikatoren unterschiedlich sind, können Sie "key" verwenden, um die Standardtastenkombination festzulegen und sie plattformspezifisch zu überschreiben.

Hinweis: Wenn ein Befehl aufgerufen wird (über eine Tastenkombination oder die Befehlspalette), gibt VS Code ein Aktivierungsereignis onCommand:${command} aus.

Tastenkombinations-Beispiel

Definiert, dass Strg+F1 unter Windows und Linux und Cmd+F1 unter macOS den Befehl "extension.sayHello" auslösen

{
  "contributes": {
    "keybindings": [
      {
        "command": "extension.sayHello",
        "key": "ctrl+f1",
        "mac": "cmd+f1",
        "when": "editorTextFocus"
      }
    ]
  }
}

contributes.languages

Stellen Sie die Definition einer Programmiersprache bereit. Dies führt eine neue Sprache ein oder erweitert das Wissen, das VS Code über eine Sprache hat.

Die wichtigsten Auswirkungen von contributes.languages sind

• Definieren Sie eine SprachID, die in anderen Teilen der VS Code API wiederverwendet werden kann, wie z. B. vscode.TextDocument.languageId und die Aktivierungsereignisse onLanguage.
  • Sie können einen für Menschen lesbaren Namen mit dem Feld aliases beisteuern. Das erste Element in der Liste wird als für Menschen lesbare Bezeichnung verwendet.
• Ordnen Sie Dateinamenerweiterungen (extensions), Dateinamen (filenames), Glob-Muster für Dateinamen (filenamePatterns), Dateien, die mit einer bestimmten Zeile beginnen (z. B. Hashbang) (firstLine) und Mimetypen dieser SprachID zu.
• Stellen Sie eine Reihe von deklarativen Sprachfunktionen für die beigesteuerte Sprache bereit. Erfahren Sie mehr über die konfigurierbaren Bearbeitungsfunktionen im Leitfaden zur Sprachkonfiguration.
• Stellen Sie ein Symbol bereit, das in Dateisymbolthemen verwendet werden kann, wenn das Thema kein Symbol für die Sprache enthält

Sprachbeispiel

{
  "contributes": {
    "languages": [
      {
        "id": "python",
        "extensions": [".py"],
        "aliases": ["Python", "py"],
        "filenames": [],
        "firstLine": "^#!/.*\\bpython[0-9.-]*\\b",
        "configuration": "./language-configuration.json",
        "icon": {
          "light": "./icons/python-light.png",
          "dark": "./icons/python-dark.png"
        }
      }
    ]
  }
}

contributes.menus

Stellen Sie ein Menüelement für einen Befehl im Editor oder Explorer bereit. Die Definition des Menüelements enthält den Befehl, der ausgeführt werden soll, wenn es ausgewählt wird, und die Bedingung, unter der das Element angezeigt werden soll. Letzteres wird mit der when-Klausel definiert, die die when-Klausel-Kontexte der Tastenkombinationen verwendet.

Eine Befehl-Eigenschaft gibt an, welcher Befehl ausgeführt werden soll, wenn ein Menüelement ausgewählt wird. Eine Untermenü-Eigenschaft gibt an, welches Untermenü an dieser Stelle gerendert werden soll.

Beim Deklarieren eines Befehl-Menüelements kann auch ein alternatives Befehl über die alt-Eigenschaft definiert werden. Es wird angezeigt und ausgeführt, wenn Alt gedrückt wird, während ein Menü geöffnet wird. Unter Windows und Linux tut dies auch Umschalt, was in Situationen nützlich ist, in denen Alt die Menüleiste des Fensters auslösen würde.

Schließlich definiert eine Gruppe-Eigenschaft die Sortierung und Gruppierung von Menüelementen. Die Gruppe navigation ist besonders, da sie immer an den Anfang/Anfang eines Menüs sortiert wird.

Hinweis: when-Klauseln gelten für Menüs und enablement-Klauseln für Befehle. Die enablement gilt für alle Menüs und sogar für Tastenkombinationen, während die when nur für ein einzelnes Menü gilt.

Derzeit können Erweiterungsautoren beitragen zu

• commandPalette - globale Befehlspalette
• comments/comment/title - Kommentare Titelmenüleiste
• comments/comment/context - Kommentare Kontextmenü
• comments/commentThread/title - Kommentare Thread Titelmenüleiste
• comments/commentThread/context- Kommentare Thread Kontextmenü
• debug/callstack/context - Debug-Aufrufstapel-Ansicht Kontextmenü
• debug/callstack/context Gruppe inline - Debug-Aufrufstapel-Ansicht Inline-Aktionen
• debug/toolBar - Debug-Ansicht Werkzeugleiste
• debug/variables/context - Debug-Variablen-Ansicht Kontextmenü
• editor/context - Editor-Kontextmenü
• editor/lineNumber/context - Editor Zeilennummern-Kontextmenü
• editor/title - Editor Titelleistenmenü
• editor/title/context - Editor Titel-Kontextmenü
• editor/title/run - Untermenü "Ausführen" in der Editor-Titelleiste
• explorer/context - Explorer-Ansicht Kontextmenü
• extension/context - Erweiterungen-Ansicht Kontextmenü
• file/newFile - Neues Dateielement im Menü "Datei" und auf der Willkommensseite
• interactive/toolbar - Interaktive Fenster Werkzeugleiste
• interactive/cell/title - Interaktive Fenster Zellen-Titelleiste
• notebook/toolbar - Notizbuch-Werkzeugleiste
• notebook/cell/title - Notizbuch Zellen-Titelleiste
• notebook/cell/execute - Notizbuch Zellen-Ausführungsmenü
• scm/title - SCM Titelmenü
• scm/resourceGroup/context - SCM-Ressourcengruppen Menüs
• scm/resourceFolder/context - SCM-Ordner Menüs
• scm/resourceState/context - SCM-Ressourcen Menüs
• scm/change/title - SCM-Änderungstitel Menüs
• scm/repository - SCM-Repository-Menü
• scm/sourceControl- SCM-Quellcodeverwaltungsmenü
• terminal/context - Terminal-Kontextmenü
• terminal/title/context - Terminal-Titel-Kontextmenü
• testing/item/context - Test Explorer-Element-Kontextmenü
• testing/item/gutter - Menü für eine Gutter-Dekoration für ein Testelement
• timeline/title - Zeitlinien-Ansicht Titelmenüleiste
• timeline/item/context - Zeitlinien-Ansicht Element-Kontextmenü
• touchBar - macOS Touch Bar
• view/title - Ansicht Titelmenü
• view/item/context - Ansicht Element-Kontextmenü
• webview/context - beliebiges Webview Kontextmenü
• Jedes beitragende Untermenü

Hinweis 1: Wenn ein Befehl aus einem (Kontext-)Menü aufgerufen wird, versucht VS Code, die aktuell ausgewählte Ressource zu ermitteln und übergibt diese als Parameter bei der Ausführung des Befehls. Zum Beispiel wird einem Menüelement innerhalb des Explorers die URI der ausgewählten Ressource übergeben und einem Menüelement innerhalb eines Editors die URI des Dokuments.

Hinweis 2: Befehle von Menüelementen, die zu editor/lineNumber/context beitragen, erhalten auch die Zeilennummer. Zusätzlich können diese Elemente auf den editorLineNumber-Kontextschlüssel in ihren when-Klauseln verweisen, z. B. durch die Verwendung der Operatoren in oder not in, um ihn gegen einen Array-basierten Kontextschlüssel zu testen, der von der Erweiterung verwaltet wird.

Zusätzlich zu einem Titel kann ein beigesteuerter Befehl das Symbol angeben, das VS Code anzeigt, wenn das aufrufende Menüelement als Schaltfläche dargestellt wird, z. B. auf einer Titelleiste.

Menübeispiel

Hier ist ein Befehls-Menüelement

{
  "contributes": {
    "menus": {
      "editor/title": [
        {
          "when": "resourceLangId == markdown",
          "command": "markdown.showPreview",
          "alt": "markdown.showPreviewToSide",
          "group": "navigation"
        }
      ]
    }
  }
}

Ebenso ist hier ein Befehls-Menüelement, das zu einer bestimmten Ansicht hinzugefügt wurde. Das folgende Beispiel trägt zu einer beliebigen Ansicht wie dem Terminal bei

{
  "contributes": {
    "menus": {
      "view/title": [
        {
          "command": "terminalApi.sendText",
          "when": "view == terminal",
          "group": "navigation"
        }
      ]
    }
  }
}

Hier ist ein Untermenü-Menüelement

{
  "contributes": {
    "menus": {
      "scm/title": [
        {
          "submenu": "git.commit",
          "group": "2_main@1",
          "when": "scmProvider == git"
        }
      ]
    }
  }
}

Kontextspezifische Sichtbarkeit von Befehlspaletten-Menüelementen

Beim Registrieren von Befehlen in package.json werden sie automatisch in der Befehlspalette angezeigt (⇧⌘P (Windows, Linux Ctrl+Shift+P)). Um mehr Kontrolle über die Sichtbarkeit von Befehlen zu ermöglichen, gibt es das Menüelement commandPalette. Es ermöglicht Ihnen, eine when-Bedingung zu definieren, um zu steuern, ob ein Befehl in der Befehlspalette sichtbar sein soll oder nicht.

Das folgende Snippet macht den Befehl "Hello World" nur in der Befehlspalette sichtbar, wenn im Editor etwas ausgewählt ist

{
  "commands": [
    {
      "command": "extension.sayHello",
      "title": "Hello World"
    }
  ],
  "menus": {
    "commandPalette": [
      {
        "command": "extension.sayHello",
        "when": "editorHasSelection"
      }
    ]
  }
}

Sortierung von Gruppen

Menüelemente können in Gruppen sortiert werden. Sie werden in lexikografischer Reihenfolge sortiert, mit den folgenden Standardwerten/Regeln. Sie können Menüelemente zu diesen Gruppen hinzufügen oder neue Gruppen von Menüelementen dazwischen, darunter oder darüber hinzufügen.

Das Editor-Kontextmenü hat diese Standardgruppen

• navigation - Die Gruppe navigation steht immer an erster Stelle.
• 1_modification - Diese Gruppe folgt als Nächstes und enthält Befehle, die Ihren Code modifizieren.
• 9_cutcopypaste - Die vorletzte Standardgruppe mit den grundlegenden Bearbeitungsbefehlen.
• z_commands - Die letzte Standardgruppe mit einem Eintrag zum Öffnen der Befehlspalette.

Das Explorer-Kontextmenü hat diese Standardgruppen

• navigation - Befehle zur Navigation in VS Code. Diese Gruppe steht immer an erster Stelle.
• 2_workspace - Befehle zur Manipulation des Arbeitsbereichs.
• 3_compare - Befehle zum Vergleichen von Dateien im Diff-Editor.
• 4_search - Befehle zur Suche in der Suchansicht.
• 5_cutcopypaste - Befehle zum Ausschneiden, Kopieren und Einfügen von Dateien.
• 6_copypath - Befehle zum Kopieren von Dateipfaden.
• 7_modification - Befehle zur Modifikation von Dateien.

Das Editor-Tab-Kontextmenü hat diese Standardgruppen

• 1_close - Befehle zum Schließen von Editoren.
• 3_preview - Befehle zum Anheften von Editoren.

Die Editor-Titelleiste hat diese Standardgruppen

• navigation - Befehle zur Navigation.
• 1_run - Befehle zum Ausführen und Debuggen des Editors.
• 1_diff - Befehle zur Arbeit mit Diff-Editoren.
• 3_open - Befehle zum Öffnen von Editoren.
• 5_close - Befehle zum Schließen von Editoren.

navigation und 1_run werden im primären Editor-Titelbereich angezeigt. Die anderen Gruppen werden im sekundären Bereich angezeigt – im ...-Menü.

Das Terminal-Tab-Kontextmenü hat diese Standardgruppen

• 1_create - Befehle zur Erstellung von Terminals.
• 3_run - Befehle zur Ausführung von etwas im Terminal.
• 5_manage - Befehle zur Verwaltung eines Terminals.
• 7_configure - Befehle zur Terminalkonfiguration.

Das Terminal-Kontextmenü hat diese Standardgruppen

• 1_create - Befehle zur Erstellung von Terminals.
• 3_edit - Befehle zur Bearbeitung von Text, Auswahl oder Zwischenablage.
• 5_clear - Befehle zum Löschen des Terminals.
• 7_kill - Befehle zum Schließen/Beenden des Terminals.
• 9_config - Befehle zur Terminalkonfiguration.

Das Kontextmenü für Zeitleistenansichtselemente hat diese Standardgruppen

• inline - Wichtige oder häufig verwendete Befehle für Zeitleistenelemente. Gerendert als Symbolleiste.
• 1_actions - Befehle im Zusammenhang mit der Arbeit mit Zeitleistenelementen.
• 5_copy - Befehle zum Kopieren von Informationen zu Zeitleistenelementen.

Das Kontextmenü der Erweiterungsansicht hat diese Standardgruppen

• 1_copy - Befehle zum Kopieren von Erweiterungsinformationen.
• 2_configure - Befehle zur Konfiguration einer Erweiterung.

Sortierung innerhalb von Gruppen

Die Reihenfolge innerhalb einer Gruppe hängt vom Titel oder einem Ordnungsattribut ab. Die gruppenlokale Reihenfolge eines Menüeintrags wird angegeben, indem @<Nummer> an die Gruppenkennung angehängt wird, wie unten gezeigt

{
  "editor/title": [
    {
      "when": "editorHasSelection",
      "command": "extension.Command",
      "group": "myGroup@1"
    }
  ]
}

contributes.problemMatchers

Problemübereinstimmungsmuster beitragen. Diese Beiträge funktionieren sowohl im Ausgabepaneel-Runner als auch im Terminal-Runner. Unten sehen Sie ein Beispiel, wie ein Problemübereinstimmungsmuster für den gcc-Compiler in einer Erweiterung beigetragen werden kann

{
  "contributes": {
    "problemMatchers": [
      {
        "name": "gcc",
        "owner": "cpp",
        "fileLocation": ["relative", "${workspaceFolder}"],
        "pattern": {
          "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5
        }
      }
    ]
  }
}

Dieses Problemübereinstimmungsmuster kann nun in einer tasks.json-Datei über einen Namensverweis $gcc verwendet werden. Ein Beispiel sieht wie folgt aus

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "gcc",
      "args": ["-Wall", "helloWorld.c", "-o", "helloWorld"],
      "problemMatcher": "$gcc"
    }
  ]
}

Siehe auch: Definieren eines Problemübereinstimmungsmusters

contributes.problemPatterns

Benannte Problem-Muster beitragen, die in Problemübereinstimmungsmustern verwendet werden können (siehe oben).

contributes.productIconThemes

Ein Produkt-Icon-Theme für VS Code beitragen. Produkt-Icons sind alle Icons, die in VS Code verwendet werden, mit Ausnahme von Datei-Icons und von Erweiterungen beigetragenen Icons.

Sie müssen eine ID (in den Einstellungen verwendet), eine Bezeichnung und den Pfad zur Icon-Definitionsdatei angeben.

Produkt-Icon-Theme-Beispiel

{
  "contributes": {
    "productIconThemes": [
      {
        "id": "elegant",
        "label": "Elegant Icon Theme",
        "path": "./producticons/elegant-product-icon-theme.json"
      }
    ]
  }
}

Sehen Sie sich den Leitfaden für Produkt-Icon-Themes an, wie man ein Produkt-Icon-Theme erstellt.

contributes.resourceLabelFormatters

Ressourcenbeschriftungsformatierer beitragen, die festlegen, wie URIs überall in der Benutzeroberfläche angezeigt werden. Zum Beispiel, wie eine Erweiterung einen Formatierer für URIs mit dem Schema remotehub beitragen könnte

{
  "contributes": {
    "resourceLabelFormatters": [
      {
        "scheme": "remotehub",
        "formatting": {
          "label": "${path}",
          "separator": "/",
          "workspaceSuffix": "GitHub"
        }
      }
    ]
  }
}

Dies bedeutet, dass alle URIs mit dem Schema remotehub gerendert werden, indem nur das path-Segment des URIs angezeigt wird und der Trennzeichen / ist. Arbeitsbereiche, die die remotehub-URI haben, erhalten den GitHub-Suffix in ihrer Beschriftung.

contributes.semanticTokenModifiers

Neue semantische Token-Modifikatoren beitragen, die über Themaregeln hervorgehoben werden können.

{
  "contributes": {
    "semanticTokenModifiers": [
      {
        "id": "native",
        "description": "Annotates a symbol that is implemented natively"
      }
    ]
  }
}

Sehen Sie sich den Leitfaden für semantisches Hervorheben an, um mehr über semantisches Hervorheben zu erfahren.

contributes.semanticTokenScopes

Zuordnungen zwischen semantischen Token-Typen & Modifikatoren und Geltungsbereichen beitragen, entweder als Fallback oder zur Unterstützung sprachspezifischer Themes.

{
  "contributes": {
    "semanticTokenScopes": [
      {
        "language": "typescript",
        "scopes": {
          "property.readonly": ["variable.other.constant.property.ts"]
        }
      }
    ]
  }
}

Sehen Sie sich den Leitfaden für semantisches Hervorheben an, um mehr über semantisches Hervorheben zu erfahren.

contributes.semanticTokenTypes

Neue semantische Token-Typen beitragen, die über Themaregeln hervorgehoben werden können.

{
  "contributes": {
    "semanticTokenTypes": [
      {
        "id": "templateType",
        "superType": "type",
        "description": "A template type."
      }
    ]
  }
}

Sehen Sie sich den Leitfaden für semantisches Hervorheben an, um mehr über semantisches Hervorheben zu erfahren.

contributes.snippets

Snippets für eine bestimmte Sprache beitragen. Das Attribut language ist die Sprachkennung und path ist der relative Pfad zur Snippet-Datei, die Snippets im VS Code-Snippet-Format definiert.

Das folgende Beispiel zeigt das Hinzufügen von Snippets für die Go-Sprache.

{
  "contributes": {
    "snippets": [
      {
        "language": "go",
        "path": "./snippets/go.json"
      }
    ]
  }
}

contributes.submenus

Ein Untermenü als Platzhalter beitragen, in das Menüeinträge eingefügt werden können. Ein Untermenü benötigt eine label, die im übergeordneten Menü angezeigt wird.

Zusätzlich zu einem Titel können Befehle auch Icons definieren, die VS Code in der Editor-Titelleiste anzeigt.

Untermenü-Beispiel

{
  "contributes": {
    "submenus": [
      {
        "id": "git.commit",
        "label": "Commit"
      }
    ]
  }
}

contributes.taskDefinitions

Eine Objektliteralstruktur beitragen und definieren, die es ermöglicht, eine beigesteuerte Aufgabe im System eindeutig zu identifizieren. Eine Aufgaben-Definition hat mindestens eine type-Eigenschaft, definiert aber normalerweise zusätzliche Eigenschaften. Zum Beispiel sieht eine Aufgaben-Definition für eine Aufgabe, die ein Skript in einer package.json-Datei darstellt, so aus

{
  "taskDefinitions": [
    {
      "type": "npm",
      "required": ["script"],
      "properties": {
        "script": {
          "type": "string",
          "description": "The script to execute"
        },
        "path": {
          "type": "string",
          "description": "The path to the package.json file. If omitted the package.json in the root of the workspace folder is used."
        }
      }
    }
  ]
}

Die Aufgaben-Definition wird mit JSON-Schema-Syntax für die Eigenschaften required und properties definiert. Die Eigenschaft type definiert den Aufgabentyp. Wenn das obige Beispiel

• "type": "npm" ordnet die Aufgaben-Definition den npm-Aufgaben zu
• "required": [ "script" ] definiert, dass script-Attribute zwingend erforderlich sind. Die Eigenschaft path ist optional.
• "properties" : { ... } definiert die zusätzlichen Eigenschaften und ihre Typen.

Wenn die Erweiterung tatsächlich eine Aufgabe erstellt, muss sie eine TaskDefinition übergeben, die mit der in der package.json-Datei beigetragenen Aufgaben-Definition übereinstimmt. Für das npm-Beispiel sieht eine Aufgaben-Erstellung für das Testskript in einer package.json-Datei wie folgt aus

let task = new vscode.Task({ type: 'npm', script: 'test' }, ....);

contributes.terminal

Ein Terminalprofil für VS Code beitragen, das es Erweiterungen ermöglicht, die Erstellung der Profile zu handhaben. Wenn definiert, sollte das Profil bei der Erstellung des Terminalprofils erscheinen

{
  "activationEvents": ["onTerminalProfile:my-ext.terminal-profile"],
  "contributes": {
    "terminal": {
      "profiles": [
        {
          "title": "Profile from extension",
          "id": "my-ext.terminal-profile"
        }
      ]
    }
  }
}

Wenn definiert, erscheint das Profil im Terminalprofil-Selektor. Bei Aktivierung die Erstellung des Profils durch Rückgabe von Terminaloptionen handhaben

vscode.window.registerTerminalProfileProvider('my-ext.terminal-profile', {
  provideTerminalProfile(
    token: vscode.CancellationToken
  ): vscode.ProviderResult<vscode.TerminalOptions | vscode.ExtensionTerminalOptions> {
    return { name: 'Profile from extension', shellPath: 'bash' };
  }
});

contributes.themes

Ein Farbschema für VS Code beitragen, das Arbeitsbereichfarben und Stile für Syntax-Tokens im Editor definiert.

Sie müssen eine Bezeichnung angeben, ob das Thema ein dunkles oder ein helles Thema ist (damit sich der Rest von VS Code an Ihr Thema anpasst) und den Pfad zur Datei (im JSON-Format).

Thema-Beispiel

{
  "contributes": {
    "themes": [
      {
        "label": "Monokai",
        "uiTheme": "vs-dark",
        "path": "./themes/monokai-color-theme.json"
      }
    ]
  }
}

Sehen Sie sich den Leitfaden für Farbschemata an, wie man ein Farbschema erstellt.

contributes.typescriptServerPlugins

Trägt TypeScript-Server-Plugins bei, die die JavaScript- und TypeScript-Unterstützung von VS Code erweitern.

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin"
      }
    ]
  }
}

Die obige Beispielerweiterung trägt das typescript-styled-plugin bei, das Styled-Component-IntelliSense für JavaScript und TypeScript hinzufügt. Dieses Plugin wird aus der Erweiterung geladen und muss als normale NPM-dependency in der Erweiterung installiert werden.

{
  "dependencies": {
    "typescript-styled-plugin": "*"
  }
}

TypeScript-Server-Plugins werden für alle JavaScript- und TypeScript-Dateien geladen, wenn der Benutzer die VS Code-Version von TypeScript verwendet. Sie werden nicht aktiviert, wenn der Benutzer eine Arbeitsbereichsversion von TypeScript verwendet, es sei denn, das Plugin setzt explizit "enableForWorkspaceTypeScriptVersions": true.

{
  "contributes": {
    "typescriptServerPlugins": [
      {
        "name": "typescript-styled-plugin",
        "enableForWorkspaceTypeScriptVersions": true
      }
    ]
  }
}

Plugin-Konfiguration

Erweiterungen können Konfigurationsdaten über eine von VS Codes integrierter TypeScript-Erweiterung bereitgestellte API an beigesteuerte TypeScript-Plugins senden.

// In your VS Code extension

export async function activate(context: vscode.ExtensionContext) {
  // Get the TS extension
  const tsExtension = vscode.extensions.getExtension('vscode.typescript-language-features');
  if (!tsExtension) {
    return;
  }

  await tsExtension.activate();

  // Get the API from the TS extension
  if (!tsExtension.exports || !tsExtension.exports.getAPI) {
    return;
  }

  const api = tsExtension.exports.getAPI(0);
  if (!api) {
    return;
  }

  // Configure the 'my-typescript-plugin-id' plugin
  api.configurePlugin('my-typescript-plugin-id', {
    someValue: process.env['SOME_VALUE']
  });
}

Das TypeScript-Server-Plugin empfängt die Konfigurationsdaten über eine onConfigurationChanged-Methode.

// In your TypeScript plugin

import * as ts_module from 'typescript/lib/tsserverlibrary';

export = function init({ typescript }: { typescript: typeof ts_module }) {
  return {
    create(info: ts.server.PluginCreateInfo) {
      // Create new language service
    },
    onConfigurationChanged(config: any) {
      // Receive configuration changes sent from VS Code
    }
  };
};

Diese API ermöglicht es VS Code-Erweiterungen, VS Code-Einstellungen mit einem TypeScript-Server-Plugin zu synchronisieren oder das Verhalten eines Plugins dynamisch zu ändern. Schauen Sie sich die TypeScript TSLint plugin und lit-html Erweiterungen an, um zu sehen, wie diese API in der Praxis verwendet wird.

contributes.views

Eine Ansicht für VS Code beitragen. Sie müssen eine Kennung und einen Namen für die Ansicht angeben. Sie können zu folgenden Ansichtscontainern beitragen

• explorer: Explorer-Ansichtscontainer in der Aktivitätsleiste
• scm: Source Control Management (SCM) Ansichtscontainer in der Aktivitätsleiste
• debug: Ausführen und Debuggen Ansichtscontainer in der Aktivitätsleiste
• test: Test Ansichtscontainer in der Aktivitätsleiste
• Benutzerdefinierte Ansichtscontainer, die von Erweiterungen beigesteuert werden.

Wenn der Benutzer die Ansicht öffnet, löst VS Code ein Aktivierungsereignis onView:${viewId} aus (onView:nodeDependencies für das folgende Beispiel). Sie können auch die Sichtbarkeit der Ansicht steuern, indem Sie den when-Kontextwert angeben. Das icon wird verwendet, wenn der Titel nicht angezeigt werden kann (z. B. wenn die Ansicht zur Aktivitätsleiste gezogen wird). Der contextualTitle wird verwendet, wenn die Ansicht aus ihrem Standardansichtscontainer verschoben wird und zusätzlichen Kontext benötigt.

{
  "contributes": {
    "views": {
      "explorer": [
        {
          "id": "nodeDependencies",
          "name": "Node Dependencies",
          "when": "workspaceHasPackageJSON",
          "icon": "media/dep.svg",
          "contextualTitle": "Package Explorer"
        }
      ]
    }
  }
}

Der Inhalt einer Ansicht kann auf zwei Arten gefüllt werden

• Mit einer TreeView durch Bereitstellung eines Datenanbieters über die API createTreeView oder Registrierung des Datenanbieters direkt über die API registerTreeDataProvider, um Daten zu füllen. TreeViews eignen sich ideal für die Anzeige hierarchischer Daten und Listen. Siehe das tree-view-sample.
• Mit einer WebviewView durch Registrierung eines Anbieters mit registerWebviewViewProvider. Webview-Ansichten ermöglichen das Rendern von beliebigem HTML in der Ansicht. Siehe die Beispielerweiterung webview view sample für weitere Details.

contributes.viewsContainers

Ein Ansichtscontainer beitragen, in den benutzerdefinierte Ansichten beigesteuert werden können. Sie müssen eine Kennung, einen Titel und ein Icon für den Ansichtscontainer angeben. Derzeit können Sie sie zur Aktivitätsleiste (activitybar) und zum Panel (panel) beitragen. Das folgende Beispiel zeigt, wie der Ansichtscontainer Package Explorer zur Aktivitätsleiste beigesteuert wird und wie Ansichten dazu beigesteuert werden.

{
  "contributes": {
    "viewsContainers": {
      "activitybar": [
        {
          "id": "package-explorer",
          "title": "Package Explorer",
          "icon": "resources/package-explorer.svg"
        }
      ]
    },
    "views": {
      "package-explorer": [
        {
          "id": "package-dependencies",
          "name": "Dependencies"
        },
        {
          "id": "package-outline",
          "name": "Outline"
        }
      ]
    }
  }
}

Icon-Spezifikationen

• Größe: Icons sollten 24x24 sein und zentriert.

• Farbe: Symbole sollten eine einzelne Farbe verwenden.

• Format: Es wird empfohlen, dass Symbole im SVG-Format vorliegen, obwohl jeder Bilddateityp akzeptiert wird.

• Zustände: Alle Icons erben die folgenden Zustandsstile

  Zustand	Deckkraft
  Standard	60%
  Hover	100%
  Aktiv	100%

contributes.viewsWelcome

Willkommensinhalte zu benutzerdefinierten Ansichten beitragen. Willkommensinhalte gelten nur für leere Baumansichten. Eine Ansicht gilt als leer, wenn der Baum keine Kinder und keine TreeView.message hat. Konventionsgemäß werden alle Befehlslinks, die auf einer eigenen Zeile stehen, als Schaltfläche angezeigt. Sie können die Ansicht, auf die die Willkommensinhalte angewendet werden sollen, mit der Eigenschaft view angeben. Die Sichtbarkeit der Willkommensinhalte kann mit dem when-Kontextwert gesteuert werden. Der anzuzeigende Text als Willkommensinhalt wird mit der Eigenschaft contents festgelegt.

{
  "contributes": {
    "viewsWelcome": [
      {
        "view": "scm",
        "contents": "In order to use git features, you can open a folder containing a git repository or clone from a URL.\n[Open Folder](command:vscode.openFolder)\n[Clone Repository](command:git.clone)\nTo learn more about how to use git and source control in VS Code [read our docs](https://aka.ms/vscode-scm).",
        "when": "config.git.enabled && git.state == initialized && workbenchState == empty"
      }
    ]
  }
}

Mehrere Willkommensinhaltselemente können zu einer Ansicht beigesteuert werden. Wenn dies geschieht, kommen die Inhalte aus dem VS Code-Kern zuerst, gefolgt von Inhalten aus integrierten Erweiterungen, gefolgt von Inhalten aus allen anderen Erweiterungen.

contributes.walkthroughs

Beispielerweiterung

Walkthroughs beitragen, die auf der Startseite angezeigt werden. Walkthroughs werden automatisch bei der Installation Ihrer Erweiterung geöffnet und bieten eine bequeme Möglichkeit, Benutzer mit den Funktionen Ihrer Erweiterung vertraut zu machen.

Walkthroughs bestehen aus einem Titel, einer Beschreibung, einer ID und einer Reihe von Schritten. Zusätzlich kann eine when-Bedingung festgelegt werden, um den Walkthrough basierend auf Kontextschlüsseln ein- oder auszublenden. Zum Beispiel könnte ein Walkthrough zur Erklärung der Einrichtung unter Linux die Angabe when: "isLinux" erhalten, um nur auf Linux-Maschinen angezeigt zu werden.

Jeder Schritt in einem Walkthrough hat einen Titel, eine Beschreibung, eine ID und ein Medienelement (entweder ein Bild oder Markdown-Inhalt) sowie eine optionale Reihe von Ereignissen, die dazu führen, dass der Schritt überprüft wird (siehe Beispiel unten). Schrittbeschreibungen sind Markdown-Inhalte und unterstützen **fett**, __unterstrichen__ und ``code``-Rendering sowie Links. Ähnlich wie bei Walkthroughs können Schritten when-Bedingungen zugewiesen werden, um sie basierend auf Kontextschlüsseln ein- oder auszublenden.

SVGs werden für Bilder empfohlen, da sie skalierbar sind und die Farbthemen von VS Code unterstützen. Verwenden Sie das Figma-Plugin Visual Studio Code Color Mapper, um Theme-Farben einfach in SVGs zu referenzieren.

{
  "contributes": {
    "walkthroughs": [
      {
        "id": "sample",
        "title": "Sample",
        "description": "A sample walkthrough",
        "steps": [
          {
            "id": "runcommand",
            "title": "Run Command",
            "description": "This step will run a command and check off once it has been run.\n[Run Command](command:getting-started-sample.runCommand)",
            "media": { "image": "media/image.png", "altText": "Empty image" },
            "completionEvents": ["onCommand:getting-started-sample.runCommand"]
          },
          {
            "id": "changesetting",
            "title": "Change Setting",
            "description": "This step will change a setting and check off when the setting has changed\n[Change Setting](command:getting-started-sample.changeSetting)",
            "media": { "markdown": "media/markdown.md" },
            "completionEvents": ["onSettingChanged:getting-started-sample.sampleSetting"]
          }
        ]
      }
    ]
  }
}

Abschlussereignisse

Standardmäßig, wenn keine completionEvents-Ereignisse angegeben sind, wird der Schritt abgehakt, wenn einer seiner Schaltflächen geklickt wird, oder wenn der Schritt keine Schaltflächen hat, wenn er geöffnet wird. Wenn eine feinere Steuerung erforderlich ist, kann eine Liste von completionEvents bereitgestellt werden.

Verfügbare Abschlussereignisse sind

• onCommand:myCommand.id: Schritt abhaken, wenn ein Befehl ausgeführt wurde.
• onSettingChanged:mySetting.id: Schritt abhaken, sobald die angegebene Einstellung geändert wurde.
• onContext:contextKeyExpression: Schritt abhaken, wenn ein Kontextschlüssel-Ausdruck wahr ausgewertet wird.
• extensionInstalled:myExt.id: Schritt abhaken, wenn die angegebene Erweiterung installiert ist.
• onView:myView.id: Schritt abhaken, sobald eine gegebene Ansicht sichtbar wird.
• onLink:https://...: Schritt abhaken, sobald ein gegebener Link über einen Walkthrough geöffnet wurde.

Sobald ein Schritt abgehakt wurde, bleibt er abgehakt, bis der Benutzer den Schritt explizit abwählt oder seinen Fortschritt zurücksetzt (über den Befehl Getting Started: Reset Progress).