使用提议的 API

在 Visual Studio Code 中，我们非常重视扩展 API 的兼容性。我们会尽最大努力避免破坏性的 API 更改，扩展作者可以预期已发布的扩展将继续正常工作。然而，这给我们的限制很大：一旦我们引入了一个 API，我们就很难再更改它了。

提议的 API 为我们解决了这个问题。提议的 API 是一组不稳定的 API，它们在 VS Code 中实现，但不会像稳定 API 那样向公众公开。它们可能发生更改，仅在 Insiders 发行版中可用，并且不能在已发布的扩展中使用。尽管如此，扩展作者仍然可以在本地开发中测试这些新 API，并为 VS Code 团队提供反馈，以便他们迭代 API。最终，提议的 API 将会纳入稳定 API，并可供所有扩展使用。

使用提议的 API

以下是在本地扩展开发中测试提议的 API 的步骤：

• 使用 VS Code 的 Insiders 版本。
• 在您的 package.json 中，添加 "enabledApiProposals": ["<proposalName>"]。
• 将相应的 vscode.proposed.<proposalName>.d.ts 文件复制到您项目的源位置。

@vscode/dts CLI 工具允许您快速下载最新的 vscode.proposed.<proposalName>.d.ts 用于扩展开发。它会根据您 package.json 文件中列出的提议下载定义文件。

> npx @vscode/dts dev
Downloading vscode.proposed.languageStatus.d.ts
To:   /Users/Me/Code/MyExtension/vscode.proposed.languageStatus.d.ts
From: https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.languageStatus.d.ts
Read more about proposed API at: https://vscode.js.cn/api/advanced-topics/using-proposed-api

有一个使用提议 API 的示例：proposed-api-sample。

提议 API 不兼容

在主分支上，vscode.proposed.<proposalName>.d.ts 始终与 vscode.d.ts 兼容。但是，当您将 vscode.proposed.<proposal>.d.ts 添加到使用 @types/vscode 的项目中时，最新的 vscode.proposed.<proposal>.d.ts 可能与 @types/vscode 中的版本不兼容。

您可以通过以下任一方式解决此问题：

• 移除对 @types/vscode 的依赖，并使用 npx @vscode/dts main 从 microsoft/vscode 主分支下载 vscode.d.ts。
• 使用 @types/vscode@<version>，同时使用 npx @vscode/dts dev <version> 从 microsoft/vscode 的旧分支下载 vscode.proposed.<proposal>.d.ts。但请注意，API 可能在最新版本的 VS Code Insiders 中已发生更改。

共享使用提议 API 的扩展

虽然您无法在 Marketplace 上发布使用提议 API 的扩展，但仍可以通过打包和共享您的扩展与同行共享您的扩展。

要打包您的扩展，您可以运行 vsce package 来创建扩展的 VSIX 文件。然后，您可以将此 VSIX 文件共享给他人，让他们在自己的 VS Code 中安装该扩展。

要从 VSIX 文件安装扩展，请转到“扩展”视图，选择...（更多操作）按钮，然后选择从 VSIX 安装。

在下面的短视频中展示了选择从 VSIX 安装菜单项。

对于使用提议 API 的扩展，还有几个额外的步骤来启用您的扩展。从 VSIX 安装后，您需要退出 VS Code Insiders，然后从命令行启动它，并在您的项目文件夹中运行 code-insiders . --enable-proposed-api=<YOUR-EXTENSION-ID>。

如果您想让使用提议 API 的扩展在每次启动 VS Code Insiders 时都可以使用，您可以运行首选项: 配置运行时参数命令来编辑 .vscode-insiders/argv.json 文件，以设置启用的扩展列表。

{
    ...
    "enable-proposed-api": ["<YOUR-EXTENSION-ID>"]
}