使用建议的 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 安装后，你需要退出并通过命令行使用 code-insiders . --enable-proposed-api=<YOUR-EXTENSION-ID> 在你的项目文件夹中重新启动 VS Code Insiders。

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

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