자동 제안 상자

  • 아티클

AutoSuggestBox를 사용하여 입력과 동시에 선택할 수 있는 제안 사항 목록을 사용자에게 제공합니다.

An auto suggest box

올바른 컨트롤인가요?

제안 목록과 함께 텍스트 검색을 허용하는 간단하고 사용자 지정 가능한 컨트롤을 원하는 경우 자동 제안 상자를 선택합니다.

올바른 텍스트 컨트롤을 선택하는 방법에 대한 자세한 내용은 텍스트 컨트롤 문서를 참조하세요.

구조

자동 제안 상자의 진입점은 선택적 헤더와 선택적 힌트 텍스트가 있는 텍스트 상자로 구성됩니다.

Example of the entry point for auto-suggest control

자동 제안 결과 목록은 사용자가 텍스트를 입력하기 시작하면 자동으로 채워집니다. 결과 목록은 텍스트 입력란 위 또는 아래에 표시할 수 있습니다. "모두 지우기" 버튼이 나타납니다.

Example of the expanded auto-suggest control

권장 사항

  • 자동 제안 상자를 사용하여 검색을 수행하고 입력한 텍스트에 대한 검색 결과가 없는 경우, 사용자가 검색 요청이 실행되었음을 알 수 있도록 한 줄 "결과 없음" 메시지를 결과로 표시합니다.

    Example of an auto suggest box with no search results

UWP 및 WinUI 2

Important

이 문서의 정보 및 예제는 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입니다.

Example of auto-suggest control with a find icon.

샘플 코드 가져오기