使用提案 (Proposed) API

在 Visual Studio Code，我們非常重視擴充功能 API 的相容性。我們盡最大努力避免破壞性的 API 變更，讓擴充功能開發者可以預期已發布的擴充功能能夠持續運作。然而，這對我們造成了極大的限制：一旦我們引入了某個 API，就無法輕易地進行更改。

提案 API (Proposed APIs) 為我們解決了這個問題。提案 API 是一組不穩定的 API，它們已在 VS Code 中實作，但不會像穩定版 API 那樣公開給大眾使用。這些 API 可能會有所變更，僅適用於 Insiders 版本，且不應在已發布的擴充功能中使用。儘管如此，擴充功能開發者可以在本地開發中測試這些新 API，並提供回饋給 VS Code 團隊以進行迭代。最終，提案 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 的不相容性

在 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 安裝 (Install from VSIX)。

選擇從 VSIX 安裝選單項目的操作示範如下方短片所示。

對於使用提案 API 的擴充功能，啟用擴充功能還需要額外的步驟。在從 VSIX 安裝後，您需要關閉並透過命令列重新啟動 VS Code Insiders，並在專案資料夾中使用 code-insiders . --enable-proposed-api=<YOUR-EXTENSION-ID> 指令。

如果您希望在使用提案 API 的擴充功能時，每次啟動 VS Code Insiders 都能自動啟用，可以執行偏好設定：設定執行階段引數 (Preferences: Configure Runtime Arguments) 指令，編輯 .vscode-insiders/argv.json 檔案，並設定已啟用擴充功能的清單。

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