提案 API の使用

Visual Studio Codeにおいて、私たちは拡張機能APIの互換性を非常に重視しています。APIの破壊的変更を避けるために最善を尽くしており、公開された拡張機能がそのまま動作し続けることを拡張機能開発者は期待できるはずです。しかし、このことは私たちに大きな制約を課します。一度APIを導入すると、後から簡単に変更することができなくなるからです。

「提案されたAPI（Proposed APIs）」は、この問題を解決するためのものです。これらはVS Codeに実装されているものの、安定版APIとして一般公開されていない不安定な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.dokyumento.jp/api/advanced-topics/using-proposed-api

提案されたAPIを使用したサンプルとして、proposed-api-sample があります。

提案されたAPIの非互換性

メインブランチでは、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 メインブランチから vscode.d.ts をダウンロードする。
• @types/vscode@<version> を使用し、同時に npx @vscode/dts dev <version> を使用して、microsoft/vscode の古いブランチから vscode.proposed.<proposal>.d.ts をダウンロードする。ただし、VS Code Insidersの最新版ではAPIが変更されている可能性があるため注意してください。

提案されたAPIを使用する拡張機能の共有

提案されたAPIを使用する拡張機能をマーケットプレイスで公開すべきではありませんが、パッケージ化して共有することで、同僚や知人と共有することは可能です。

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

VSIXファイルから拡張機能をインストールするには、拡張機能ビューで ... (表示とその他のアクション) ボタンを選択し、VSIXからインストール... (Install from VSIX) を選択します。

VSIXからインストール メニュー項目の選択手順については、以下の短い動画をご覧ください。

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

提案されたAPIを使用する拡張機能をVS Code Insidersの起動のたびに常に利用可能にしたい場合は、基本設定: ランタイム引数の構成 (Preferences: Configure Runtime Arguments) コマンドを実行して .vscode-insiders/argv.json ファイルを編集し、有効な拡張機能のリストを設定することができます。

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