使用建議的 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.dev.org.tw/api/advanced-topics/using-proposed-api

這有一個使用建議的 API 的範例：proposed-api-sample。

建議的 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 中變更。

使用建議的 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>"]
}