使用提议的 API

在 Visual Studio Code 中，我们非常重视扩展 API 的兼容性。我们尽最大努力避免破坏性的 API 更改，并确保插件开发者开发的插件能够持续稳定运行。然而，这给我们带来了巨大的限制：一旦我们引入一个 API，就很难再对其进行更改。

建议的 API（Proposed APIs）为我们解决了这个问题。建议的 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 时都能自动启用，您可以运行首选项：配置运行时参数 (Preferences: Configure Runtime Arguments) 命令来编辑 .vscode-insiders/argv.json 文件，设置已启用插件的列表。

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