概要

VSCode の機能拡張でエクスプローラー上からコンテキストメニュー経由で実行するコマンドを実装した際、呼び出されるコマンドが受け取る引数の説明が公式ドキュメントに無く、またそのパターンもやや特殊であった。

公式リファレンスには package.json の menu に設定する値として explorer/context が使えることは書かれているが、そのコンテキストメニューからコマンドが呼び出されたときの引数についての説明がない。

ここではその調査結果をまとめる。

調査時点での VSCode のバージョン

Version: 1.96.2 (Universal)

引数について

基本的には第1引数に vscode.Uri 型の値、第2引数に vscode.Uri[] 型の値が渡される。

つまりコマンドを実行する関数の定義は以下の様な感じになる。

export function my_command_from_explorer(uri: vscode.Uri, selectedFiles?: vscode.Uri[])
{
  console.log( uri.fsPath );
}

vscode.Uri はクラス。詳細は公式リファレンスを参照。

分かりにくい仕様として条件によって渡される引数のパターンが異なる問題があった。具体的には以下の条件が影響する。

これらのパターンの調査結果は以下の様になる。

コンテキストメニューを開いた場所	当該アイテムの選択状態	他の選択状態	第1引数	第2引数
空白部分	-	無視される	ワークスペースフォルダー	`[]`
ファイル	選択状態	無し	当該ファイル	`["当該ファイル"]`
〃	非選択状態	無し	当該ファイル	`["当該ファイル"]`
〃	選択状態	有り	当該ファイル	`["当該ファイル", ..."選択中のファイルやフォルダ"]`
〃	非選択状態	有り	当該ファイル	`["当該ファイル"]`

※表中の「ファイル」は「ディレクトリ」の場合も同様であるため「ファイルまたはディレクトリ」と読み替え可能

表だと分かりにくいため、以下特徴的な仕様について説明する。

エクスプローラーの空白部分でコンテキストメニューを開いた場合、ワークスペースフォルダ自体が処理対象となる。

エクスプローラーの空白部分とは下図の赤点線で囲んだ部分のこと。

この時エクスプローラー上でファイルやフォルダが選択状態にあっても無視され、ルートフォルダのパスが渡される。ユーザーが GUI の状態からこの内部仕様を予測するのは難しい。

もし実行するコマンドが破壊的な処理¹を行うならばユーザーの期待を裏切った上に、大きな損失を与える事になるだろう。

破壊的¹なコマンドを提供するならばユーザーに事前に適切なダイアログを提示すべきだろう。

調査の結果から以下の条件を満たすとき、エクスプローラーの空白部分からコンテキストメニューが起動されたと判定出来る。

プログラム側はこの条件を元に警告を出すことが出来る。

例えばエクスプローラーの選択状態が下図の状態を例とする。

この時 memo.md を右クリックしてコンテキストメニューからコマンドを実行した場合、第1引数にも第2引数にも memo.md しか渡されない。

つまり以下の様になる。

しかし edited-state.diff の上でコンテキストメニューを開いた場合以下の様になる。

※ 読みやすさのために相対パスにしているが実際には絶対パスで渡される

この仕様は比較的理解できる仕様であり、また破壊的な処理¹であってもポインタが指し示すファイル・ディレクトリのみが対象となるためユーザーの意図に反することは無いだろう。

選択された他のファイル・ディレクトリが対象とならないことについての疑問も、再度の選択されたファイル・ディレクトリ上から実行すれば処理対象となるため、比較的短期間で経験的な理解を獲得すると思われる。

右クリックしたファイル・ディレクトリの状態が:	第2引数の値
選択状態である	他の選択状態のファイル・ディレクトリも含んだリストになる
非選択状態である	右クリックしたファイル・ディレクトリのみからなるリストになる

プログラムからはユーザーがいずれの状態で操作を行ったのかを判定することは出来無い²。