常用功能

通用功能是构建扩展的重要基础。几乎所有扩展都会用到其中一些功能。以下是如何利用这些功能的说明。

命令

命令是 VS Code 工作的核心。您可以打开命令面板来执行命令，将自定义快捷键绑定到命令，或者右键单击以在上下文菜单中调用命令。

扩展可以：

使用 vscode.commands API 注册并执行命令。
使用 contributes.commands 贡献点在命令面板中提供命令。

在扩展指南 / 命令主题中了解有关命令的更多信息。

配置

扩展可以使用 contributes.configuration 贡献点贡献特定于扩展的设置，并使用 workspace.getConfiguration API 读取这些设置。

快捷键

扩展可以添加自定义快捷键。请参阅 contributes.keybindings 和快捷键主题了解更多信息。

扩展可以注册自定义上下文菜单项，这些项会在右键单击时显示在 VS Code UI 的不同部分。请参阅 contributes.menus 贡献点了解更多信息。

数据存储

有五种数据存储选项：

ExtensionContext.workspaceState：一种工作区存储，您可以向其中写入键/值对。VS Code 会管理该存储，并在再次打开同一工作区时还原它。
ExtensionContext.globalState：一种全局存储，您可以向其中写入键/值对。VS Code 会管理该存储，并在每次扩展激活时还原它。您可以通过在 globalState 上使用 setKeysForSync 方法设置同步键，有选择地同步全局存储中的键/值对。
ExtensionContext.storageUri：一个指向本地目录的工作区特定存储 URI，您的扩展对该目录拥有读/写权限。如果您需要存储只能从当前工作区访问的大型文件，这是一个不错的选择。
ExtensionContext.globalStorageUri：一个指向本地目录的全局存储 URI，您的扩展对该目录拥有读/写权限。如果您需要存储可从所有工作区访问的大型文件，这是一个不错的选择。
ExtensionContext.secrets：用于存储机密（或任何敏感信息）的全局存储，这些信息将被加密。它们不会在不同机器间同步。对于 VS Code 桌面版，这利用了 Electron 的 safeStorage API。对于 Web 版 VS Code，这使用了双密钥加密 (DKE) 实现。

扩展上下文可在扩展入口文件的 activate 函数中使用。

setKeysForSync 示例

如果您的扩展需要在不同机器之间保留某些用户状态，请使用 vscode.ExtensionContext.globalState.setKeysForSync 将该状态提供给设置同步。

您可以使用以下模式：

// on activate
const versionKey = 'shown.version';
context.globalState.setKeysForSync([versionKey]);

// later on show page
const currentVersion = context.extension.packageJSON.version;
const lastVersionShown = context.globalState.get(versionKey);
if (isHigher(currentVersion, lastVersionShown)) {
    context.globalState.update(versionKey, currentVersion);
}

通过共享已关闭或已查看的标志，在机器间共享状态有助于避免用户在不同实例中重复看到欢迎页或更新页的问题。

显示通知

几乎所有扩展在某些时候都需要向用户展示信息。VS Code 提供了三个用于显示不同严重级别通知消息的 API：

快速选择 (Quick Pick)

使用 vscode.QuickPick API，您可以轻松收集用户输入或让用户从多个选项中进行选择。QuickInput 示例演示了该 API。

文件选择器

扩展可以使用 window.showOpenDialog API 打开系统文件选择器并选择文件或文件夹。

输出通道

输出面板显示一系列 OutputChannel，它们非常适合用于日志记录。您可以使用 window.createOutputChannel API 轻松利用它。

进度 API

您可以使用 vscode.Progress API 向用户报告进度更新。

使用 ProgressLocation 选项，进度可以显示在不同位置：

在通知区域
在源代码管理视图中
VS Code 窗口中的常规进度

进度示例演示了此 API。

5/28/2026