使用建议的 API

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

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

使用建议的 API

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

@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.github.net.cn/api/advanced-topics/using-proposed-api

有一个使用建议的 API 的示例：proposal-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下载。vscode.d.tsmicrosoft/vscode
  • 使用@types/vscode@<version>并使用从 的旧分支npx @vscode/dts dev <version>下载. 但是，请小心，因为最新版本的 VS Code Insiders 中的 API 可能已更改。vscode.proposed.<proposal>.d.tsmicrosoft/vscode

使用建议的 API 共享扩展

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

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

要从 VSIX 文件安装扩展，您需要进入扩展视图，选择...省略号视图和更多操作按钮，然后选择从 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>"]
}
11/1/2023