Proposed API の使用

Visual Studio Code では、拡張機能 API の互換性を重要視しています。API の破壊的な変更を避けるために最大限の努力を払い、拡張機能の作者は公開された拡張機能が引き続き動作することを期待できます。しかし、これは私たちに大きな制約を与えます。一度 API を導入すると、簡単には変更できなくなります。

Proposed API は、私たちの問題を解決します。Proposed API は、VS Code に実装されていますが、安定版 API として公開されていない不安定な API のセットです。これらは、変更される可能性があり、Insiders ディストリビューションでのみ利用可能であり、公開された拡張機能では使用できません。それにもかかわらず、拡張機能の作者は、ローカル開発でこれらの新しい API をテストし、VS Code チームが API を反復するためのフィードバックを提供できます。最終的に、Proposed API は安定版 API に組み込まれ、すべての拡張機能で利用できるようになります。

Proposed API の使用

ローカル拡張機能開発で Proposed API をテストする手順は次のとおりです。

• Insiders リリースの VS Code を使用してください。
• package.json に、"enabledApiProposals": ["<proposalName>"] を追加します。
• 対応する vscode.proposed.<proposalName>.d.ts ファイルをプロジェクトのソースロケーションにコピーします。

@vscode/dts CLI ユーティリティを使用すると、拡張機能開発用に最新の vscode.proposed.<proposalName>.d.ts をすばやくダウンロードできます。これは、package.json ファイルにリストされている proposals によって定義ファイルをダウンロードします。

> 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.dokyumento.jp/api/advanced-topics/using-proposed-api

Proposed API を使用したサンプルがあります: proposed-api-sample。

Proposed API の非互換性

main ブランチでは、vscode.proposed.<proposalName>.d.ts は常に vscode.d.ts と互換性があります。ただし、@types/vscode を使用するプロジェクトに vscode.proposed.<proposal>.d.ts を追加すると、最新の 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 で変更されている可能性があるため、注意してください。

Proposed API を使用した拡張機能の共有

Marketplace で Proposed API を使用して拡張機能を公開することはできませんが、拡張機能をパッケージ化して共有することで、同僚と拡張機能を共有することはできます。

拡張機能をパッケージ化するには、vsce package を実行して拡張機能の VSIX ファイルを作成します。その後、この VSIX ファイルを他のユーザーと共有して、VS Code に拡張機能をインストールできます。

VSIX ファイルから拡張機能をインストールするには、拡張機能ビューに移動し、... 省略記号の [表示とその他のアクション] ボタンを選択し、[VSIX からインストール] を選択します。

[VSIX からインストール] メニュー項目を選択する様子を以下の短いビデオで示します。

Proposed API を使用する拡張機能の場合、拡張機能を有効にするには、さらにいくつかの手順が必要です。VSIX からインストールした後、プロジェクトフォルダーで code-insiders . --enable-proposed-api=<YOUR-EXTENSION-ID> を使用してコマンドラインから VS Code Insiders を終了して再起動する必要があります。

Proposed API を使用する拡張機能を VS Code Insiders の起動ごとに常に使用できるように設定する場合は、[Preferences: Configure Runtime Arguments] コマンドを実行して .vscode-insiders/argv.json ファイルを編集し、有効にする拡張機能のリストを設定できます。

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