次の方法で共有

自動提案ボックス

  • [アーティクル]

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 を使用します。

  • データ項目の 1 つのプロパティのテキストを表示するには、DisplayMemberPath プロパティを設定して、提案リストに表示するオブジェクトのプロパティを選択します。
  • リスト内の各項目のカスタム検索を定義するには、ItemTemplate プロパティを使用します。

選択した候補

ユーザーがキーボードを使用して候補リスト内を移動する場合は、テキスト ボックス内のテキストを一致するように更新する必要があります。

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

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

送信されたクエリ

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

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

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

いずれの場合も、イベント引数 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 を次に示します。

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

サンプル コードの入手