使用提议的 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.<proposal>.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>
。
如果您想设置每次启动 VS Code Insiders 时都可使用您使用提议 API 的扩展,可以运行“首选项:配置运行时参数”命令,编辑 .vscode-insiders/argv.json
文件来设置已启用扩展的列表。
{
...
"enable-proposed-api": ["<YOUR-EXTENSION-ID>"]
}