使用提議的 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.com.tw/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 時都可以使用，您可以執行首選項: 配置執行時引數命令來編輯 .vscode-insiders/argv.json 檔案，以設定啟用的擴充套件列表。

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