Aktivierungsereignisse

Aktivierungsereignisse sind eine Reihe von JSON-Deklarationen, die Sie im Feld activationEvents von package.json im Extension Manifest vornehmen. Ihre Erweiterung wird aktiviert, wenn das Aktivierungsereignis eintritt. Hier ist eine Liste aller verfügbaren Aktivierungsereignisse.

• onAuthenticationRequest
• onChatParticipant
• onCommand
• onCustomEditor
• onDebug
  • onDebugAdapterProtocolTracker
  • onDebugDynamicConfigurations
  • onDebugInitialConfigurations
  • onDebugResolve
• onEditSession
• onFileSystem
• onIssueReporterOpened
• onLanguage
• onLanguageModelTool
• onNotebook
• onOpenExternalUri
• onRenderer
• onSearch
• onStartupFinished
• onTaskType
• onTerminal
  • onTerminalProfile
  • onTerminalShellIntegration
• onUri
• onView
• onWalkthrough
• onWebviewPanel
• workspaceContains
• *

Wir bieten auch eine Referenz aller Felder im package.json Extension Manifest an.

onLanguage

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn eine Datei geöffnet wird, die einer bestimmten Sprache zugeordnet ist.

"activationEvents": [
    "onLanguage:python"
]

Das onLanguage-Ereignis nimmt einen Wert für den Sprachidentifikator entgegen.

Mehrere Sprachen können mit separaten onLanguage-Einträgen im Array activationEvents deklariert werden.

"activationEvents": [
    "onLanguage:json",
    "onLanguage:markdown",
    "onLanguage:typescript"
]

Hinweis: Ab VS Code 1.74.0 benötigen Sprachen, die von Ihrer Erweiterung beigesteuert werden, keine entsprechende onLanguage-Aktivierungsereignis-Deklaration mehr, damit Ihre Erweiterung aktiviert wird.

Zusätzlich gilt: Wenn Ihre Erweiterung aktiviert werden muss, bevor eine Sprache verwendet wird, können Sie das generische onLanguage-Aktivierungsereignis verwenden, um dies sicherzustellen.

"activationEvents": [
    "onLanguage"
]

Hinweis: Es ist bewährte Praxis, nur dann zu aktivieren, wenn ein Benutzer Ihre Erweiterung benötigt. Wenn Ihre Erweiterung für eine Teilmenge von Sprachen funktioniert, ist es für den Benutzer besser, diese Teilmenge aufzulisten, anstatt für alle Sprachen zu aktivieren.

onCommand

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn ein Befehl aufgerufen wird.

"activationEvents": [
    "onCommand:extension.sayHello"
]

Hinweis: Ab VS Code 1.74.0 benötigen Befehle, die von Ihrer Erweiterung beigesteuert werden, keine entsprechende onCommand-Aktivierungsereignis-Deklaration mehr, damit Ihre Erweiterung aktiviert wird.

onDebug

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, bevor eine Debug-Sitzung gestartet wird.

"activationEvents": [
    "onDebug"
]

Dies sind vier detailliertere onDebug-Aktivierungsereignisse.

onDebugAdapterProtocolTracker

onDebugAdapterProtocolTracker wird ausgelöst, wenn eine Debug-Sitzung mit dem spezifischen Typ gestartet werden soll und ein Debug-Protokoll-Tracker benötigt wird.

onDebugDynamicConfigurations

Dieses Aktivierungsereignis wird unmittelbar vor dem Aufruf der Methode provideDebugConfigurations des DebugConfigurationProvider ausgelöst, um dynamische Debug-Konfigurationen bereitzustellen, wenn der Benutzer sie anfordert, z. B. über die Benutzeroberfläche mit dem Befehl "Debuggen auswählen und starten".

Das Vorhandensein dieses Aktivierungsereignisses wird als Signal verwendet, dass die Erweiterung dynamische Debug-Konfigurationen beisteuert.

onDebugInitialConfigurations

Dieses Aktivierungsereignis wird unmittelbar vor dem Aufruf der Methode provideDebugConfigurations des DebugConfigurationProvider ausgelöst, um anfängliche Debug-Konfigurationen bereitzustellen, z. B. immer dann, wenn eine launch.json erstellt werden muss.

onDebugResolve

onDebugResolve:type wird ausgelöst, kurz bevor die Methode resolveDebugConfiguration des DebugConfigurationProvider für den angegebenen Typ aufgerufen wird.

Daumenregel: Wenn die Aktivierung einer Debug-Erweiterung leichtgewichtig ist, verwenden Sie onDebug. Wenn sie schwergewichtig ist, verwenden Sie onDebugInitialConfigurations und/oder onDebugResolve, je nachdem, ob der DebugConfigurationProvider die entsprechenden Methoden provideDebugConfigurations und/oder resolveDebugConfiguration implementiert. Weitere Details zu diesen Methoden finden Sie unter Verwendung eines DebugConfigurationProvider.

workspaceContains

workspaceContains:path wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn ein Ordner geöffnet wird und der Ordner mindestens eine Datei enthält, die einem Glob-Muster entspricht.

"activationEvents": [
    "workspaceContains:**/.editorconfig"
]

onFileSystem

onFileSystem:scheme wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn eine Datei oder ein Ordner eines bestimmten Schemas gelesen wird. Dies ist normalerweise das file-Schema, aber mit benutzerdefinierten Dateisystemanbietern kommen weitere Schemas ins Spiel, z. B. ftp oder ssh.

"activationEvents": [
    "onFileSystem:sftp"
]

onView

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn eine Ansicht mit der angegebenen ID im VS Code-Seitenbereich erweitert wird. Eingebaute Ansichten lösen kein Aktivierungsereignis aus.

Das folgende Aktivierungsereignis wird ausgelöst, wenn eine Ansicht mit der ID nodeDependencies sichtbar ist.

"activationEvents": [
    "onView:nodeDependencies"
]

Hinweis: Ab VS Code 1.74.0 benötigen Ansichten, die von Ihrer Erweiterung beigesteuert werden, keine entsprechende onView-Aktivierungsereignis-Deklaration mehr, damit Ihre Erweiterung aktiviert wird.

onUri

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn eine systemweite URI für diese Erweiterung geöffnet wird. Das URI-Schema ist entweder vscode oder vscode-insiders. Die URI-Autorität muss die Kennung der Erweiterung sein. Der Rest der URI ist beliebig.

"activationEvents": [
    "onUri"
]

Wenn die vscode.git-Erweiterung onUri als Aktivierungsereignis definiert, wird sie für alle folgenden geöffneten URIs aktiviert.

• vscode://vscode.git/init
• vscode://vscode.git/clone?url=https%3A%2F%2Fgithub.com%2FMicrosoft%2Fvscode-vsce.git
• vscode-insiders://vscode.git/init (für VS Code Insiders)

onWebviewPanel

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn VS Code einen Webview mit dem passenden viewType wiederherstellen muss.

Zum Beispiel die Deklaration von onWebviewPanel unten:

"activationEvents": [
    "onWebviewPanel:catCoding"
]

veranlasst die Erweiterung zur Aktivierung, wenn VS Code einen Webview mit dem viewType catCoding wiederherstellen muss. Der viewType wird im Aufruf von window.createWebviewPanel festgelegt und Sie benötigen ein weiteres Aktivierungsereignis (z. B. onCommand), um Ihre Erweiterung anfänglich zu aktivieren und den Webview zu erstellen.

onCustomEditor

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn VS Code einen benutzerdefinierten Editor mit dem passenden viewType erstellen muss.

Zum Beispiel die Deklaration von onCustomEditor unten:

"activationEvents": [
    "onCustomEditor:catCustoms.pawDraw"
]

veranlasst die Erweiterung zur Aktivierung, wenn VS Code einen benutzerdefinierten Editor mit dem viewType catCustoms.pawDraw wiederherstellen muss. Der viewType wird im customEditors-Beitragspunkt festgelegt und an einen Anbieter mit registerCustomEditorProvider gebunden.

Hinweis: Ab VS Code 1.74.0 benötigen benutzerdefinierte Editoren, die von Ihrer Erweiterung beigesteuert werden, keine entsprechende onCustomEditor-Aktivierungsereignis-Deklaration mehr, damit Ihre Erweiterung aktiviert wird.

onAuthenticationRequest

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn eine Erweiterung eine Authentifizierungssitzung (über die authentication.getSession() API) mit der passenden providerId anfordert.

Zum Beispiel die Deklaration von onAuthenticationRequest unten:

"activationEvents": [
    "onAuthenticationRequest:github"
]

veranlasst die Erweiterung zur Aktivierung, wenn VS Code eine AuthenticationSession vom Typ github abrufen muss.

Hinweis: Ab VS Code 1.74.0 benötigen Authentifizierungsanbieter, die von Ihrer Erweiterung beigesteuert werden, keine entsprechende onAuthenticationRequest-Aktivierungsereignis-Deklaration mehr, damit Ihre Erweiterung aktiviert wird.

onStartupFinished

Dieses Aktivierungsereignis wird ausgelöst und interessierte Erweiterungen werden aktiviert, **einige Zeit nach** dem Start von VS Code. Dies ähnelt dem *-Aktivierungsereignis, verlangsamt jedoch nicht den VS Code-Start. Derzeit wird dieses Ereignis ausgelöst, nachdem alle mit * aktivierten Erweiterungen ihre Aktivierung abgeschlossen haben.

"activationEvents": [
    "onStartupFinished"
]

onTaskType

onTaskType:type wird ausgelöst, wenn Aufgaben eines bestimmten Typs aufgelistet oder aufgelöst werden müssen.

"activationEvents": [
    "onTaskType:npm"
]

Hinweis: Ab VS Code 1.76.0 benötigen Aufgaben, die von Ihrer Erweiterung beigesteuert werden, keine entsprechende onTaskType-Aktivierungsereignis-Deklaration mehr, damit Ihre Erweiterung aktiviert wird.

onEditSession

onEditSession:scheme wird ausgelöst, wenn auf eine Bearbeitungssitzung mit dem angegebenen Schema zugegriffen wird.

"activationEvents": [
    "onEditSession:file"
]

onSearch

onSearch:scheme wird ausgelöst, wenn eine Suche im Ordner mit dem angegebenen Schema gestartet wird.

"activationEvents": [
    "onSearch:file"
]

onOpenExternalUri

Ein Aktivierungsereignis, das ausgelöst wird, wenn eine externe URI, wie z. B. ein http- oder https-Link, geöffnet wird.

"activationEvents": [
    "onOpenExternalUri"
]

onNotebook

onNotebook:type wird ausgelöst, wenn der angegebene Notebook-Dokumenttyp geöffnet wird.

"activationEvents": [
    "onNotebook:jupyter-notebook",
    "onNotebook:interactive"
]

onRenderer

onRenderer:id wird ausgelöst, wenn ein Notebook-Ausgaberenderer verwendet wird.

"activationEvents": [
    "onRenderer:ms-toolsai.jupyter-renderers"
]

onTerminal

onTerminal:shellType wird ausgelöst, wenn ein bestimmtes Terminal mit dem angegebenen Shell-Typ geöffnet wird.

"activationEvents": [
  "onTerminal:bash"
]

onTerminalProfile

onTerminalProfile:id wird ausgelöst, wenn ein bestimmtes Terminalprofil gestartet wird.

"activationEvents": [
    "onTerminalProfile:terminalTest.terminal-profile"
]

onTerminalShellIntegration

onTerminalShellIntegration:shellType wird ausgelöst, wenn ein Terminal mit dem angegebenen Shell-Typ Shell-Integration aktiviert hat.

"activationEvents": [
    "onTerminalShellIntegration:bash"
]

onWalkthrough

onWalkthrough:id wird ausgelöst, wenn der angegebene Walkthrough geöffnet wird.

"activationEvents": [
    "onWalkthrough:nodejsWelcome"
]

onIssueReporterOpened

Dieses Aktivierungsereignis wird ausgelöst, wenn der Issue Reporter geöffnet wird (z. B. durch Verwenden von Hilfe: Problem melden).

"activationEvents": [
    "onIssueReporterOpened"
]

onChatParticipant

Ein Aktivierungsereignis, das ausgelöst wird, wenn der angegebene Chat-Teilnehmer aufgerufen wird.

"activationEvents": [
    "onChatParticipant:my-chat-participant"
]

onLanguageModelTool

Ein Aktivierungsereignis, das ausgelöst wird, wenn das angegebene Sprachmodell-Tool aufgerufen wird.

"activationEvents": [
    "onLanguageModelTool:my-language-model-tool"
]

Start

Das Aktivierungsereignis * wird ausgelöst und interessierte Erweiterungen werden aktiviert, wenn VS Code startet.

Hinweis: Um eine hervorragende Benutzererfahrung zu gewährleisten, verwenden Sie dieses Aktivierungsereignis in Ihrer Erweiterung nur, wenn keine andere Kombination von Aktivierungsereignissen in Ihrem Anwendungsfall funktioniert.

"activationEvents": [
    "*"
]

Hinweis: Eine Erweiterung kann mehrere Aktivierungsereignisse abhören, und das ist dem Abhören von "*" vorzuziehen.

Hinweis: Eine Erweiterung muss eine activate()-Funktion aus ihrem Hauptmodul exportieren, und diese wird von VS Code nur einmal aufgerufen, wenn eines der angegebenen Aktivierungsereignisse ausgelöst wird. Außerdem sollte eine Erweiterung eine deactivate()-Funktion aus ihrem Hauptmodul exportieren, um Bereinigungsaufgaben beim Herunterfahren von VS Code durchzuführen. Eine Erweiterung muss ein Promise von deactivate() zurückgeben, wenn der Bereinigungsprozess asynchron ist. Eine Erweiterung kann undefined von deactivate() zurückgeben, wenn die Bereinigung synchron abläuft.