自動提案ボックス

AutoSuggestBox を使用して、ユーザーが入力時に選択する候補の一覧を提供します。

自動提案ボックス

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

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

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

解剖学

自動提案ボックスのエントリ ポイントは、省略可能なヘッダーと、省略可能なヒント テキストを含むテキスト ボックスで構成されます。

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

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

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

推奨事項

• 自動提案ボックスを使用して検索を実行し、入力したテキストに検索結果が存在しない場合は、検索結果として 1 行の "結果なし" メッセージを表示して、ユーザーが検索要求が実行されたことを知るようにします。

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

自動提案ボックスを作成する

WinUI 3 ギャラリー アイコン

WinUI 3 ギャラリー アプリには、WinUI コントロールと機能の対話型の例が含まれています。 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 プロパティには、リストから選択された項目が含まれています。

いずれの場合も、イベント args 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 を検索に使用する

AutoSuggestBox を使用して、ユーザーが入力時に選択する候補の一覧を提供します。

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

<AutoSuggestBox QueryIcon="Find"/>

"検索" アイコンが付いた AutoSuggestBox を次に示します。

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

関連資料

• テキスト コントロール
• スペル チェック
• TextBox クラス
• Windows。Ui。Xaml.Controls PasswordBox クラス
• String.Length プロパティ