常用功能

通用功能是扩展的重要构建块。几乎所有扩展都使用其中一些功能。以下是如何利用它们。

命令

命令是 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。对于 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 来显示不同严重级别的通知消息

快速选择

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

文件选择器

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

输出通道

输出面板显示 OutputChannel 的集合，这对于日志记录非常有用。您可以使用 window.createOutputChannel API 轻松利用它。

进度 API

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

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

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

进度示例说明了此 API。

12/10/2025