自動建議方塊

使用 AutoSuggestBox 提供讓使用者在輸入時可從中選取建議的清單。

這是正確的控制項嗎？

如果您想要一個簡單的可自訂控制項，允許使用建議清單進行文字搜尋，請選擇自動建議方塊。

如需如何選擇正確文字控制項的詳細資訊，請參閱文字控制項文章。

結構

自動建議方塊的入口點由可選標題和帶有可選提示文字的文字方塊組成：

只要使用者開始輸入文本，自動建議結果清單就會自動填入。 結果清單可以顯示在文字輸入方塊的上方或下方。 出現「全部清除」按鈕：

建議

• 當使用自動建議方塊執行搜尋並且輸入的文字不存在搜尋結果時，顯示單行「無結果」訊息作為結果，以便使用者知道他們的搜尋請求已執行：

  

UWP 和 WinUI 2

重要

本文中的資訊和範例針對使用 Windows App SDK 和 WinUI 3 的應用程式進行了最佳化，但通常適用於使用 WinUI 2 的 UWP 應用程式。 如需平台特定資訊和範例，請參閱 UWP API 參考。

本節包含您在 UWP 或 WinUI 2 應用程式中使用控制項所需的資訊。

此控制項的 API 位在 Windows.UI.Xaml.Controls 命名空間中。

• UWP API：AutoSuggestBox 類別、TextChanged 事件、SuggestionChose 事件、QuerySubmitted 事件
• 開啟 WinUI 2 資源庫應用程式，並查看 AutoSuggestBox 運作情形。 WinUI 2 資源庫應用程式包含大部分 WinUI 2 控制項、特性和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 Github 上取得原始程式碼。

建議使用最新的 WinUI 2 來取得所有控制項的最新樣式和範本。 WinUI 2.2 或更新版本包含此使用圓角之控制項的新範本。 如需詳細資訊，請參閱圓角半徑。

建立自動建議方塊

• 重要 API：AutoSuggestBox 類別、TextChanged 事件、SuggestionChose 事件、QuerySubmitted 事件

開啟 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 進行搜尋

使用 AutoSuggestBox 提供讓使用者在輸入時可從中選取建議的清單。

文字輸入方塊預設不會顯示查詢按鈕。 您可以設定 QueryIcon 屬性，以在文字方塊右側新增具有指定圖示的按鈕。 例如，若要讓 AutoSuggestBox 看起來像是典型的搜尋方塊，請加入「Find」圖示，就像這樣：

<AutoSuggestBox QueryIcon="Find"/>

以下是具有「尋找」圖示的 AutoSuggestBox。

取得範例程式碼

• WinUI 資源庫範例 - 以互動式格式查看所有 XAML 控制項。
• AutoSuggestBox 範例

相關文章

• 文字控制項
• 拼字檢查
• TextBox 類別 \(英文\)
• Windows.UI.Xaml.Controls PasswordBox 類別
• String.Length 屬性 \(部分機器翻譯\)