自動提案ボックス

  • [アーティクル]

AutoSuggestBox を使って、ユーザーが入力と同時に選べる候補リストを表示します。

自動提案ボックス

これは適切なコントロールですか?

候補の一覧を使ってテキストを検索できる、シンプルでカスタマイズ可能なコントロールが必要な場合は、自動提案ボックスを使います。

適切なテキスト コントロールの選択の詳細については、「テキスト コントロール」の記事をご覧ください。

構造

自動提案ボックスのエントリ ポイントは、オプションのヘッダーとオプションのヒント テキスト付きのテキスト ボックスで構成されます。

自動提案コントロールのエントリ ポイントの例

自動提案結果の一覧には、ユーザーがテキストの入力を開始すると自動的に内容が入力されます。 結果の一覧は、テキスト入力ボックスの上または下に表示されます。 [すべてクリア] ボタンも表示されます。

展開された自動提案コントロールの例

推奨事項

  • 自動提案ボックスを使って検索を実行したときに、入力したテキストに対応する検索結果が存在しなかった場合は、"検索結果が見つかりませんでした" という 1 行を表示します。これにより、ユーザーは検索要求が実行されたことがわかります。

    検索結果のない自動提案ボックスの例

UWP と WinUI 2

重要

この記事の情報と例は、Windows アプリ SDKと WinUI 3 を使用するアプリ向けに最適化されていますが、一般に WinUI 2 を使用する UWP アプリに適用されます。 プラットフォーム固有の情報と例については、UWP API リファレンスを参照してください。

このセクションには、UWP または WinUI 2 アプリでコントロールを使用するために必要な情報が含まれています。

このコントロールの API は 、Windows.UI.Xaml.Controls 名前空間に存在します。

最新の WinUI 2 を使用して、すべてのコントロールの最新のスタイルとテンプレートを取得することをお勧めします。 WinUI 2.2 以降には、角丸みを使用するこのコントロール用の新しいテンプレートが含まれています。 詳しくは、「角の半径」をご覧ください。

自動提案ボックスの作成

WinUI 3 ギャラリー アプリを開き、AutoSuggestBox の動作を確認します。

WinUI 3 ギャラリー アプリには、ほとんどの WinUI 3 コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを入手するか、GitHub でソース コードを取得します。

AutoSuggestBox を使うには、3 つのユーザー操作に応答する必要があります。

  • テキストの変更 - ユーザーがテキストを入力したときに、候補リストを更新します。
  • 候補の選択 - ユーザーが候補リストで候補を選んだときに、テキスト ボックスを更新します。
  • クエリの送信 - ユーザーがクエリを送信したときに、クエリの結果を表示します。

テキストの変更

テキスト ボックスの内容が更新されるたびに、TextChanged イベントが発生します。 イベント引数 Reason プロパティを使って、変更がユーザー入力によって生じたものかどうかを調べます。 変更の理由が UserInput の場合、入力に基づいてデータをフィルター処理します。 次に、フィルター処理されたデータを AutoSuggestBox の ItemsSource に設定し、候補リストを更新します。

候補リストでの項目の表示方法を制御するには、DisplayMemberPath または ItemTemplate を使うことができます。

  • データ項目の単一のプロパティのテキストを表示するには、DisplayMemberPath プロパティを設定し、候補リストに表示するオブジェクトのプロパティを選択します。
  • リストの各項目に対してカスタマイズした外観を定義するには、ItemTemplate プロパティを使います。

候補の選択

ユーザーがキーボードを使って候補リスト内を移動したときは、テキスト ボックス内のテキストを更新して合わせる必要があります。

TextMemberPath プロパティを設定し、テキスト ボックスに表示するデータ オブジェクトのプロパティを選択します。 TextMemberPath を指定した場合、テキスト ボックスは自動的に更新されます。 通常は、DisplayMemberPath と TextMemberPath に同じ値を指定する必要があるため、候補リストとテキスト ボックスのテキストは同じです。

単純ではないプロパティを表示する必要がある場合、SuggestionChosen イベントを処理し、選択した項目に基づいてカスタム テキストをテキスト ボックスに入力します。

クエリの送信

QuerySubmitted イベントを処理し、アプリに適したクエリ操作を実行して、ユーザーに結果を表示します。

ユーザーがクエリ文字列をコミットすると、QuerySubmitted イベントが発生します。 ユーザーは次のいずれかの方法でクエリをコミットできます。

  • テキスト ボックスにフォーカスがあるときに、Enter キーを押すか、クエリ アイコンをクリックします。 イベント引数の ChosenSuggestion プロパティは null です。
  • 候補リストにフォーカスがあるときに、Enter キーを押すか、項目をクリックまたはタップします。 イベント引数の ChosenSuggestion プロパティには、一覧から選択された項目が含まれています。

いずれの場合も、イベント引数の QueryText プロパティにはテキスト ボックスのテキストが含まれています。

必須のイベント ハンドラーを使った簡単な AutoSuggestBox を次に示します。

<AutoSuggestBox PlaceholderText="Search" QueryIcon="Find" Width="200"
                TextChanged="AutoSuggestBox_TextChanged"
                QuerySubmitted="AutoSuggestBox_QuerySubmitted"
                SuggestionChosen="AutoSuggestBox_SuggestionChosen"/>

private void AutoSuggestBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
{
    // Only get results when it was a user typing,
    // otherwise assume the value got filled in by TextMemberPath
    // or the handler for SuggestionChosen.
    if (args.Reason == AutoSuggestionBoxTextChangeReason.UserInput)
    {
        //Set the ItemsSource to be your filtered dataset
        //sender.ItemsSource = dataset;
    }
}


private void AutoSuggestBox_SuggestionChosen(AutoSuggestBox sender, AutoSuggestBoxSuggestionChosenEventArgs args)
{
    // Set sender.Text. You can use args.SelectedItem to build your text string.
}


private void AutoSuggestBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
{
    if (args.ChosenSuggestion != null)
    {
        // User selected an item from the suggestion list, take an action on it here.
    }
    else
    {
        // Use args.QueryText to determine what to do.
    }
}

AutoSuggestBox を使って、ユーザーが入力と同時に選べる候補リストを表示します。

既定では、テキスト入力ボックスにはクエリ ボタンが表示されません。 QueryIcon プロパティを設定し、テキスト ボックスの右側に指定したアイコンが表示されるボタンを追加することができます。 たとえば、AutoSuggestBox を一般的な検索ボックスと同様の外観にするには、次のような "検索" アイコンを追加します。

<AutoSuggestBox QueryIcon="Find"/>

ここでは、AutoSuggestBox に "検索" アイコンが付いています。

検索アイコンを使用した自動提案コントロールの例。

サンプル コードを入手する