Visual Studio Codeのコマンドパレットでリスト(Quick Pick)を出す方法

Visual Studio Codeの拡張機能を作るにあたり、いくつかのAPIが公開されている。

Visual Studio Code API Reference

今回はこの中から、コマンドパレットでリストを出して、アイテムを選んでもらうためのAPIをご紹介。こんなの↓

Contents

1 文字列リスト(Quick Pick)を出す方法
2 ラベルと説明文のアイテムリストを出す方法
- 2.1 QuickPickItem
- 2.2 QuickPickOptions – matchOnDescription

文字列リスト(Quick Pick)を出す方法

API集ではリストのことをQuick Pickと呼んでいる。コマンドが呼ばれた時などにQuick Pickを出し、アイテムを選んでもらうにはshowQuickPick()を使う。

showQuickPick()には、単に文字列のリストを表示するか、ラベルと説明文のあるアイテムのリストを表示するかで二種類あり、まずは文字列リストを表示する方法を解説する。

showQuickPick(items: string[] | Thenable<string[]>, options?: QuickPickOptions): Thenable<string>

items : string[] : 表示したい文字列を複数渡す
items : Thenable<string[]> : 表示する文字列を取得できた後にリストを表示したいときに使う
options? : QuickPickOptions : Quick PickのUIについてのオプション。
Thenable<string> : 返り値には、選択された文字列をThenableで受け取ることになるから、then()で受けて使おう。

items : string[]

これは一番単純なQuick Pickの使い方で、例えば、”a”, “b”, “c”という選択肢を出すならこう使う。

vscode.window.showQuickPick(["a", "b", "c"]);

1	vscode.window.showQuickPick(["a", "b", "c"]);

items : Thenable<string[]>

Quick Pickのアイテムの取得に時間がかかるとき、取得が終わってかQuick Pickを表示してほしいはず。そんな時はこちらの引数を使う。

例えば、使用可能なコマンドを全て取ってきてQuick Pickで選ばせたいとき、コマンドの取得には少し時間がかかるから、こちらの使い方がうってつけだ。

"]var commands = vscode.commands.getCommands();

vscode.window.showQuickPick(commands);

"]var commands = vscode.commands.getCommands();

vscode.window.showQuickPick(commands);

このコードを実行すると、コマンドの取得中はコマンドパレットの下に読込中を示すバーが出てきて、読み込みが終わるとこのようなQuick Pickが表示される。

options? : QuickPickOptions

matchOnDescriptionとplaceHolderという２つのプロパティを持つ型

matchOnDescription? : boolean : Quick Pickのアイテムの説明文も検索対象にするかどうか
placeHolder? : string : Quick Pick表示中にコマンドパレットに表示する文字列

中々これだけの説明では要領を得ないから、placeHolderだけ解説しよう。matchOnDescriptionは後ほど。

placeHolderに文字列を設定してshowQuickPick()に渡すと、”どのアイテムを選びますか？”みたいなユーザーへのメッセージを表示することができる。

var commands = vscode.commands.getCommands();

var options: vscode.QuickPickOptions = {　placeHolder: "What command do you use?"　};

vscode.window.showQuickPick(commands, options);

var commands = vscode.commands.getCommands();

var options: vscode.QuickPickOptions = {　placeHolder: "What command do you use?"　};

vscode.window.showQuickPick(commands, options);

このコードを実行すると、”What command do you use?”と表示してくれる。

Thenable<string>

返り値の解説。

ユーザーがQuick Pickのアイテムを選んだ後、どういう処理をするかを簡単に設定できるようになっている。

例えば、コマンド一覧から選んでもらったコマンドの名前をメッセージに出すならこう。

var commands = vscode.commands.getCommands();

vscode.window
    .showQuickPick(commands)
    .then(selectedCommand => vscode.window.showInformationMessage(selectedCommand));

var commands = vscode.commands.getCommands();

vscode.window

.showQuickPick(commands)

.then(selectedCommand => vscode.window.showInformationMessage(selectedCommand));

コマンドを選ぶと……

メッセージが表示される。

ラベルと説明文のアイテムリストを出す方法

showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options?: QuickPickOptions): Thenable<T>

T extends QuickPickItem : Quick Pickに表示するアイテムの型を指定する。
引数や戻り値は文字列リストのときと型が違うだけ

QuickPickItem

この型は、Quick Pickに表示するアイテムのラベルと説明文を持っている。

label : string : アイテムのラベル
description : string : アイテムの説明文

このQuickPickItemを使うと、このようなQuick Pickを作ることができる。

var item1: vscode.QuickPickItem = { label: "三四郎", description: "オールナイトニッポンがオモロイ" };
var item2: vscode.QuickPickItem = { label: "トレンディエンジェル", description: "M1おめでとう！" };
var item3: vscode.QuickPickItem = { label: "メイプル超合金", description: "ダークホース" };

vscode.window.showQuickPick([item1, item2, item3]);

var item1: vscode.QuickPickItem = { label: "三四郎", description: "オールナイトニッポンがオモロイ" };

var item2: vscode.QuickPickItem = { label: "トレンディエンジェル", description: "M1おめでとう！" };

var item3: vscode.QuickPickItem = { label: "メイプル超合金", description: "ダークホース" };

vscode.window.showQuickPick([item1, item2, item3]);

QuickPickOptions – matchOnDescription

最後に、後回しにしていたオプションを紹介する。

このオプションを有効にすると、QuickPickItemで指定したDescriptionもフィルタリング対象にできる。使い方はこうなる。

var item1: vscode.QuickPickItem = { label: "三四郎", description: "オールナイトニッポンがオモロイ" };
var item2: vscode.QuickPickItem = { label: "トレンディエンジェル", description: "M1おめでとう！" };
var item3: vscode.QuickPickItem = { label: "メイプル超合金", description: "ダークホース" };

var options: vscode.QuickPickOptions = { matchOnDescription: true };

vscode.window.showQuickPick([item1, item2, item3], options);