使用提议的 API

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

提议的 API 为我们解决了这个问题。提议的 API 是一组在 VS Code 中实现但未作为稳定 API 公开给公众使用的不稳定 API。它们 **可能会发生变化**，**仅在 Insider 版本中可用**，并且 **不能在已发布的扩展中使用**。但是，扩展作者可以在本地开发中测试这些新 API，并为 VS Code 团队提供反馈，以便迭代 API。最终，提议的 API 会进入稳定 API，并可供所有扩展使用。

使用提议的 API

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

• 使用 Insider 版本的 VS Code。
• 在你的 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 Insider 的最新版本中发生更改。

使用提议的 API 共享扩展

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

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

要从 VSIX 文件安装扩展，你需要进入扩展视图，选择 **...** 省略号 **查看更多操作** 按钮，然后选择 **从 VSIX 安装**。

下面的短视频显示了选择 **从 VSIX 安装** 菜单项的过程。

对于使用提议的 API 的扩展，还需要进行一些步骤才能启用你的扩展。从你的 VSIX 安装后，你需要退出并从命令行重新启动 VS Code Insider，在你的项目文件夹中运行 code-insiders . --enable-proposed-api=<YOUR-EXTENSION-ID>。

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

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