VSCode插件需掌握五大核心事件机制：一、activationEvents中onCommand实现按需激活；二、TextDocumentChangeEvent捕获文档内容变更；三、window.onDidChangeActiveTextEditor监听编辑器切换；四、workspace.onDidSaveTextDocument响应手动保存；五、configuration.onChange监听配置变更。
如果您正在开发 VSCode 插件，但无法准确响应编辑器状态变化、文档修改或用户交互行为，则可能是由于对 VSCode 扩展 API 中的事件模型理解不充分。以下是 VSCode 插件中必须掌握的核心事件机制及其典型使用方式：
本文运行环境：MacBook Pro，macOS Sequoia。
一、activationEvents 中的 onCommand 事件
该事件定义插件在何种命令被触发时激活，避免插件过早加载，提升启动性能。它声明于 package.json 的 activationEvents 字段中，属于声明式事件注册机制。
1、在 package.json 的 activationEvents 数组中添加字符串格式的命令 ID，例如 "onCommand:extension.sayHello"。
2、确保该命令 ID 与 extension.ts 中 registerCommand 调用时传入的第一个参数完全一致。
3、插件仅在用户执行对应命令（如通过 Command Palette 输入）时才完成 activate 函数调用。
二、TextDocumentChangeEvent 事件
该事件由 workspace.onDidChangeTextDocument 方法返回的事件监听器触发，用于捕获任意打开文档内容变更，包括键入、粘贴、撤销等所有文本修改动作。
1、在 activate 函数中调用 vscode.workspace.onDidChangeTextDocument。
2、传入回调函数，接收 TextDocumentChangeEvent 类型参数，其 event.document 属性提供当前变更文档实例。
3、通过 event.contentChanges 获取变更范围和新旧文本片段，注意：不要直接依赖 event.document.getText() 的即时结果，应使用 contentChanges[0].text 获取插入内容。
三、window.onDidChangeActiveTextEditor 事件
该事件监听当前焦点编辑器实例的切换，适用于需要根据活动编辑器语言模式、路径或方案动态调整 UI 或逻辑的场景。
1、调用 vscode.window.onDidChangeActiveTextEditor 注册监听器。
2、回调函数接收 TextEditor | undefined 参数，需判断是否为 null 再访问 viewColumn、document 等属性。
3、每次切换标签页、拆分编辑器或打开新文件都会触发，但不保证 document 已完成加载，建议结合 workspace.onDidOpenTextDocument 做二次确认。
四、workspace.onDidSaveTextDocument 事件
该事件在用户显式保存文档后触发，可用于执行格式化后处理、同步到外部服务或生成衍生文件等操作。
1、使用 vscode.workspace.onDidSaveTextDocument 注册监听。
2、回调接收 TextDocument 对象，可通过 document.uri.fsPath 获取绝对路径。
3、此事件不响应自动保存（Auto Save）触发的写入，仅响应用户主动按 Cmd+S / Ctrl+S 或菜单选择“保存”动作。
五、configuration.onChange 事件
该事件监听 VSCode 设置项（settings.json 或用户/工作区配置）变更，使插件能实时响应用户偏好调整。
1、调用 vscode.workspace.onDidChangeConfiguration，传入过滤器字符串数组，例如 ["myExtension.enableFeature"]。
2、回调函数接收 ConfigurationChangeEvent 参数，调用 event.affectsConfiguration("myExtension.enableFeature") 判断是否相关。
3、事件不会携带新值，需在回调内重新调用 workspace.getConfiguration("myExtension").get("enableFeature") 获取当前值。
