使用 Proposed API

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

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

使用 Proposed API

以下是在本地扩展开发中测试 Proposed 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

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

Proposed API 不兼容性

在 main 分支上，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 的 main 分支下载 vscode.d.ts。
• 使用 @types/vscode@<version>，并使用 npx @vscode/dts dev <version> 从 microsoft/vscode 的旧分支下载 vscode.proposed.<proposal>.d.ts。但是请注意，API 可能在最新版本的 VS Code Insiders 中已更改。

分享使用 Proposed API 的扩展

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

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

要从 VSIX 文件安装扩展，请进入“扩展”视图，选择“...”省略号“视图和更多操作”按钮，然后选择“从 VSIX 安装”。

选择“从 VSIX 安装”菜单项的操作如下图短视频所示。

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

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

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