활성화 이벤트

활성화 이벤트는 package.json 파일의 activationEvents 필드에 선언하는 JSON 선언 세트입니다. 확장 매니페스트. **활성화 이벤트**가 발생하면 확장이 활성화됩니다. 사용 가능한 모든 **활성화 이벤트** 목록입니다.

package.json 확장 매니페스트의 모든 필드에 대한 참조도 제공합니다.

onLanguage

이 활성화 이벤트는 특정 언어를 확인하는 파일이 열릴 때마다 발생하며 관심 있는 확장이 활성화됩니다.

"activationEvents": [
    "onLanguage:python"
]

onLanguage 이벤트는 언어 식별자 값을 사용합니다.

activationEvents 배열에 별도의 onLanguage 항목으로 여러 언어를 선언할 수 있습니다.

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

참고: VS Code 1.74.0부터 확장으로 제공되는 언어는 확장이 활성화되기 위해 해당 onLanguage 활성화 이벤트 선언이 필요하지 않습니다.

또한, 확장이 언어가 사용되기 전에 활성화되어야 하는 경우, 이를 보장하기 위해 일반 onLanguage 활성화 이벤트를 사용할 수 있습니다.

"activationEvents": [
    "onLanguage"
]

참고: 확장이 사용자에게 필요할 때만 활성화하는 것이 가장 좋습니다. 확장이 언어의 하위 집합에서 작동하는 경우, 모든 언어에서 활성화하는 것보다 사용자에게 해당 하위 집합을 나열하는 것이 좋습니다.

onCommand

이 활성화 이벤트는 명령이 호출될 때마다 발생하며 관심 있는 확장이 활성화됩니다.

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

참고: VS Code 1.74.0부터 확장으로 제공되는 명령은 확장이 활성화되기 위해 해당 onCommand 활성화 이벤트 선언이 필요하지 않습니다.

onDebug

이 활성화 이벤트는 디버그 세션이 시작되기 전에 발생하며 관심 있는 확장이 활성화됩니다.

"activationEvents": [
    "onDebug"
]

다음은 네 가지 더 세분화된 onDebug 활성화 이벤트입니다.

onDebugAdapterProtocolTracker

onDebugAdapterProtocolTracker는 특정 유형의 디버그 세션이 시작되려고 하고 디버그 프로토콜 추적기가 필요할 수 있을 때마다 발생합니다.

onDebugDynamicConfigurations

이 활성화 이벤트는 사용자가 "디버그 선택 및 시작" 명령 등을 통해 UI에서 요청할 때 동적 디버그 구성을 제공하기 위해 DebugConfigurationProvider의 provideDebugConfigurations 메서드가 호출되기 직전에 발생합니다.

이 활성화 이벤트의 존재는 확장이 동적 디버그 구성을 제공한다는 신호로 사용됩니다.

onDebugInitialConfigurations

이 활성화 이벤트는 launch.json을 생성해야 할 때마다 DebugConfigurationProvider의 provideDebugConfigurations 메서드가 호출되기 직전에 발생하여 초기 디버그 구성을 제공합니다.

onDebugResolve

onDebugResolve:type은 지정된 유형에 대한 DebugConfigurationProvider의 resolveDebugConfiguration 메서드가 호출되기 직전에 발생합니다.

간단히 말해: 디버그 확장의 활성화가 가벼우면 onDebug를 사용하십시오. 무거우면 onDebugInitialConfigurations 및/또는 onDebugResolve를 사용하십시오. DebugConfigurationProvider가 해당 메서드 provideDebugConfigurations 및/또는 resolveDebugConfiguration을 구현하는지 여부에 따라 달라집니다. 이러한 메서드에 대한 자세한 내용은 디버그 구성 제공자 사용을 참조하십시오.

workspaceContains

workspaceContains:path는 폴더가 열리고 해당 폴더에 glob 패턴과 일치하는 파일이 하나 이상 포함되어 있을 때마다 발생하며 관심 있는 확장이 활성화됩니다.

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

onFileSystem

onFileSystem:scheme은 특정 *스키마*의 파일 또는 폴더를 읽을 때마다 발생하며 관심 있는 확장이 활성화됩니다. 일반적으로 이는 file-스키마이지만 사용자 지정 파일 시스템 제공자를 사용하면 ftp 또는 ssh와 같은 더 많은 스키마가 사용됩니다.

"activationEvents": [
    "onFileSystem:sftp"
]

onView

이 활성화 이벤트는 VS Code 사이드바에서 지정된 ID의 보기가 확장될 때마다 발생하며 관심 있는 확장이 활성화됩니다. 기본 보기에는 활성화 이벤트가 발생하지 않습니다.

아래 활성화 이벤트는 nodeDependencies ID를 가진 보기가 보일 때마다 발생합니다.

"activationEvents": [
    "onView:nodeDependencies"
]

참고: VS Code 1.74.0부터 확장으로 제공되는 보기는 확장이 활성화되기 위해 해당 onView 활성화 이벤트 선언이 필요하지 않습니다.

onUri

이 활성화 이벤트는 해당 확장에 대한 시스템 전체 URI가 열릴 때마다 발생하며 관심 있는 확장이 활성화됩니다. URI 스키마는 vscode 또는 vscode-insiders로 고정됩니다. URI 권한은 확장의 식별자여야 합니다. URI의 나머지 부분은 임의입니다.

"activationEvents": [
    "onUri"
]

vscode.git 확장이 onUri를 활성화 이벤트로 정의하는 경우, 다음 URI 중 하나가 열릴 때 활성화됩니다.

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

onWebviewPanel

이 활성화 이벤트는 VS Code가 일치하는 viewType으로 웹뷰를 복원해야 할 때마다 발생하며 관심 있는 확장이 활성화됩니다.

예를 들어, 아래 onWebviewPanel 선언은

"activationEvents": [
    "onWebviewPanel:catCoding"
]

VS Code가 catCoding viewType의 웹뷰를 복원해야 할 때 확장을 활성화하며, viewType은 window.createWebviewPanel 호출에서 설정됩니다. 확장을 처음 활성화하고 웹뷰를 만들려면 다른 활성화 이벤트(예: onCommand)가 필요합니다.

onCustomEditor

이 활성화 이벤트는 VS Code가 일치하는 viewType으로 사용자 지정 편집기를 만들어야 할 때마다 발생하며 관심 있는 확장이 활성화됩니다.

예를 들어, 아래 onCustomEditor 선언은

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

VS Code가 catCustoms.pawDraw viewType의 사용자 지정 편집기를 복원해야 할 때 확장을 활성화하며, viewType은 customEditors 기여 포인트에서 설정되고 registerCustomEditorProvider를 사용하여 공급자에 바인딩됩니다.

참고: VS Code 1.74.0부터 확장으로 제공되는 사용자 지정 편집기는 확장이 활성화되기 위해 해당 onCustomEditor 활성화 이벤트 선언이 필요하지 않습니다.

onAuthenticationRequest

이 활성화 이벤트는 확장이 일치하는 providerId로 인증 세션(authentication.getSession() API를 통해)을 요청할 때마다 발생하며 관심 있는 확장이 활성화됩니다.

예를 들어, 아래 onAuthenticationRequest 선언은

"activationEvents": [
    "onAuthenticationRequest:github"
]

VS Code가 github 유형의 AuthenticationSession을 검색해야 할 때 확장을 활성화합니다.

참고: VS Code 1.74.0부터 확장으로 제공되는 인증 공급자는 확장이 활성화되기 위해 해당 onAuthenticationRequest 활성화 이벤트 선언이 필요하지 않습니다.

onStartupFinished

이 활성화 이벤트는 VS Code가 시작된 **이후 얼마 지나지 않아** 발생하며 관심 있는 확장이 활성화됩니다. 이는 * 활성화 이벤트와 유사하지만 VS Code 시작 시간을 늦추지 않습니다. 현재 이 이벤트는 *로 활성화된 모든 확장이 활성화된 후에 발생합니다.

"activationEvents": [
    "onStartupFinished"
]

onTaskType

onTaskType:type은 특정 유형의 작업 목록을 가져오거나 해결해야 할 때마다 발생합니다.

"activationEvents": [
    "onTaskType:npm"
]

참고: VS Code 1.76.0부터 확장으로 제공되는 작업은 확장이 활성화되기 위해 해당 onTaskType 활성화 이벤트 선언이 필요하지 않습니다.

onEditSession

onEditSession:scheme은 지정된 스키마로 편집 세션에 액세스할 때 발생합니다.

"activationEvents": [
    "onEditSession:file"
]

onSearch

onSearch:scheme은 지정된 스키마가 있는 폴더에서 검색이 시작될 때 발생합니다.

"activationEvents": [
    "onSearch:file"
]

onOpenExternalUri

외부 URI(예: http 또는 https 링크)가 열릴 때마다 발생하는 활성화 이벤트입니다.

"activationEvents": [
    "onOpenExternalUri"
]

onNotebook

onNotebook:type은 지정된 노트북 문서 유형이 열릴 때 발생합니다.

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

onRenderer

onRenderer:id는 노트북 출력 렌더러가 사용될 때 발생합니다.

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

onTerminal

onTerminal:shellType은 지정된 쉘 유형의 터미널이 열릴 때 발생합니다.

"activationEvents": [
  "onTerminal:bash"
]

onTerminalProfile

onTerminalProfile:id는 지정된 터미널 프로필이 시작될 때 발생합니다.

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

onTerminalShellIntegration

onTerminalShellIntegration:shellType은 쉘 통합이 활성화된 지정된 쉘 유형의 터미널이 열릴 때 발생합니다.

"activationEvents": [
    "onTerminalShellIntegration:bash"
]

onWalkthrough

onWalkthrough:id는 지정된 walkthrough가 열릴 때 발생합니다.

"activationEvents": [
    "onWalkthrough:nodejsWelcome"
]

onIssueReporterOpened

문제 보고기가 열릴 때(예: **도움말: 문제 보고** 사용) 발생하는 활성화 이벤트입니다.

"activationEvents": [
    "onIssueReporterOpened"
]

onChatParticipant

지정된 채팅 참가자가 호출될 때 발생하는 활성화 이벤트입니다.

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

onLanguageModelTool

지정된 언어 모델 도구가 호출될 때 발생하는 활성화 이벤트입니다.

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

시작

* 활성화 이벤트는 VS Code가 시작될 때마다 발생하며 관심 있는 확장이 활성화됩니다.

참고: 훌륭한 사용자 경험을 보장하기 위해, 사용 사례에서 다른 활성화 이벤트 조합으로 해결되지 않는 경우에만 이 활성화 이벤트를 확장 프로그램에서 사용하십시오.

"activationEvents": [
    "*"
]

참고: 확장은 여러 활성화 이벤트에 수신 대기할 수 있으며, 이는 "*"에 수신 대기하는 것보다 선호됩니다.

참고: 확장은 메인 모듈에서 activate() 함수를 내보내야 하며, 지정된 활성화 이벤트 중 하나가 발생할 때 VS Code에 의해 **단 한 번만** 호출됩니다. 또한, 확장은 VS Code 종료 시 정리 작업을 수행하기 위해 메인 모듈에서 deactivate() 함수를 내보내야 합니다. 정리 프로세스가 비동기인 경우 확장은 deactivate()에서 Promise를 반환해야 합니다. 정리가 동기적으로 실행되는 경우 확장은 deactivate()에서 undefined를 반환할 수 있습니다.

12/10/2025