SearchBox.SuggestionsRequested イベント

  • リファレンス

定義

名前空間:
Windows.UI.Xaml.Controls
編集

ユーザーのクエリ テキストが変更され、アプリが検索ウィンドウに表示する新しい候補を提供する必要がある場合に発生します。

// Register
event_token SuggestionsRequested(TypedEventHandler<SearchBox, SearchBoxSuggestionsRequestedEventArgs const&> const& handler) const;

// Revoke with event_token
void SuggestionsRequested(event_token const* cookie) const;

// Revoke with event_revoker
SearchBox::SuggestionsRequested_revoker SuggestionsRequested(auto_revoke_t, TypedEventHandler<SearchBox, SearchBoxSuggestionsRequestedEventArgs const&> const& handler) const;
public event TypedEventHandler<SearchBox,SearchBoxSuggestionsRequestedEventArgs> SuggestionsRequested;
function onSuggestionsRequested(eventArgs) { /* Your code */ }
searchBox.addEventListener("suggestionsrequested", onSuggestionsRequested);
searchBox.removeEventListener("suggestionsrequested", onSuggestionsRequested);
- or -
searchBox.onsuggestionsrequested = onSuggestionsRequested;
Public Custom Event SuggestionsRequested As TypedEventHandler(Of SearchBox, SearchBoxSuggestionsRequestedEventArgs) 
<SearchBox SuggestionsRequested="eventhandler"/>

イベントの種類

TypedEventHandler<SearchBox,SearchBoxSuggestionsRequestedEventArgs>

注釈

いくつかのソースから候補を取得できます。

  • それらを自分で定義できます。 たとえば、自動車メーカーの一覧を作成できます。
  • アプリがローカル ファイルを検索する場合は、Windows から取得できます。
  • Web サービスまたはサーバーから取得できます。

提案を表示するためのユーザー エクスペリエンスのガイドラインについては、「検索の ガイドラインとチェックリスト」を参照してください。

LocalContentSuggestionSettings を使用すると、数行のコードで、Windows からのローカル ファイルに基づいて提案を追加できます。 または、検索ボックス コントロールの SuggestionsRequested イベントに登録し、別のソース (ローカル定義リストや Web サービスなど) から取得した候補で構成される独自の候補のリストを作成することもできます。

検索候補を追加する方法を示すコード例については、 SearchBox コントロールのサンプルをダウンロードしてください。 このサンプルでは、3 つの可能なソースすべてを使用して検索候補を追加する方法と、入力メソッド エディター (IME) によって生成されたクエリ テキストの代替形式を使用して東アジア言語の候補を追加する方法を示します。 (日本語または中国語のユーザーがアプリを使用する場合は、クエリ テキストの代替手段を使用することをお勧めします)。

検索候補の種類

アプリで表示できる候補には、ユーザーがクエリを調整するのに役立つ候補 (クエリ候補) と、クエリの実際の結果である候補 (結果候補) の 2 種類があります。 一方または両方の種類の候補を表示することもできます。

クエリ候補を指定し、ユーザーがクエリ候補を選択した場合、アプリの検索結果ページに選択した絞り込まれたクエリの結果を表示して、アプリが応答する必要があります。

結果候補を指定する場合は、 ResultSuggestionChosen イベント ハンドラーを登録して、ユーザーがいずれかの結果候補を選択したときに応答できるようにし、その結果をユーザーに表示できるようにする必要もあります。

アプリによって提供された候補の表示

候補を取得したら、 それらを SearchSuggestionsRequest に追加して表示します。SearchSuggestionCollection。

クエリ候補と結果候補の両方を表示する場合は、候補の種類 (クエリまたは結果) で候補をグループ化し、 AppendSearchSeparator を使用してグループを分離する必要があります。 各区切り記号は候補の代わりに使用され、その後に少なくとも 1 つの候補が続き、表示できる候補の数が減る必要があります。

候補内のすべてのテキスト フィールド (テキスト、詳細テキスト、画像代替テキストなど) の最大長は 512 文字です。

提案を使用してユーザーに適切な検索エクスペリエンスを作成する方法の詳細については、「 検索のガイドラインとチェックリスト」を参照してください。

SuggestionsRequested イベントを非同期的に処理する

SuggestionsRequested イベントに非同期的に応答する場合は、検索候補リストを編集する前に SearchSuggestionsRequestDeferral オブジェクトを取得する必要があります。 クイック スタート: 方法を示す アプリへの検索の追加に関するページ の例を次に示します。

public async static void SearchBox_SuggestionsRequested(
    SearchBox sender, 
    SearchBoxSuggestionsRequestedEventArgs args)
{

    // This object lets us edit the SearchSuggestionCollection asynchronously. 
    var deferral = args.Request.GetDeferral();

    try { 

        // Retrieve the system-supplied suggestions.
        var suggestions = args.Request.SearchSuggestionCollection;

        var groups = await SampleDataSource.GetGroupsAsync();
        foreach (var group in groups)
        {
            var matchingItems = group.Items.Where(
                item => item.Title.StartsWith(
                    args.QueryText, StringComparison.CurrentCultureIgnoreCase));

            foreach (var item in matchingItems)
            {
                suggestions.AppendQuerySuggestion(item.Title);
            }
        }

        foreach (string alternative in args.LinguisticDetails.QueryTextAlternatives)
        {
            if (alternative.StartsWith(
                args.QueryText, StringComparison.CurrentCultureIgnoreCase))
            {
                suggestions.AppendQuerySuggestion(alternative); 
            }
        }
    }
    finally {
        deferral.Complete();
    }

}

適用対象

こちらもご覧ください