Compartir vía

Cuadro de sugerencias automáticas

  • Artículo

Use un AutoSuggestBox para proporcionar una lista de sugerencias para que un usuario seleccione entre mientras escribe.

Cuadro de sugerencias automáticas

¿Es este el control adecuado?

Si desea un control simple y personalizable que permita la búsqueda de texto con una lista de sugerencias, elija un cuadro de sugerencias automática.

Para obtener más información sobre cómo elegir el control de texto correcto, consulta el artículo Controles de texto.

Anatomía

El punto de entrada del cuadro de sugerencias automáticas consta de un encabezado opcional y un cuadro de texto con texto de sugerencia opcional:

Ejemplo del punto de entrada para el control de sugerencias automáticas

La lista de resultados de sugerencias automáticas se rellena automáticamente una vez que el usuario empieza a escribir texto. La lista de resultados puede aparecer encima o debajo del cuadro de entrada de texto. Aparece un botón "Borrar todo":

Ejemplo del control de sugerencias automáticas expandida

Recomendaciones

  • Al usar el cuadro de sugerencias automáticas para realizar búsquedas y no existen resultados de búsqueda para el texto especificado, muestre un mensaje de línea única "Sin resultados" como resultado para que los usuarios sepan que se ejecutó su solicitud de búsqueda:

    Ejemplo de un cuadro de sugerencias automáticas sin resultados de búsqueda

UWP y WinUI 2

Importante

La información y los ejemplos de este artículo están optimizados para aplicaciones que usan el SDK de Aplicaciones para Windows y WinUI 3, pero generalmente son aplicables a las aplicaciones para UWP que usan WinUI 2. Consulte el material de referencia de las API de UWP para obtener información y ejemplos específicos de la plataforma.

Esta sección contiene información que necesita para usar el control en una aplicación para UWP o WinUI 2.

Existen API para este control en el espacio de nombres Windows.UI.Xaml.Controls.

Se recomienda usar la versión más reciente de WinUI 2 para obtener los estilos, las plantillas y las características más actuales de todos los controles. WinUI 2.2 o de versiones posteriores incluye una nueva plantilla para este control que usa esquinas redondeadas. Para obtener más información, consulta Radio de redondeo.

Crear un cuadro de sugerencias automáticas

Abra la aplicación Galería de WinUI 3 y vea AutoSuggestBox en acción.

La aplicación WinUI 3 Gallery incluye ejemplos interactivos de la mayoría de los controles, características y funcionalidades de WinUI 3. Obtenga la aplicación de Microsoft Store u obtenga el código fuente en GitHub.

Para usar autoSuggestBox, debe responder a 3 acciones de usuario.

  • Texto cambiado: cuando el usuario escribe texto, actualice la lista de sugerencias.
  • Sugerencia elegida: cuando el usuario elige una sugerencia en la lista de sugerencias, actualice el cuadro de texto.
  • Consulta enviada: cuando el usuario envía una consulta, muestre los resultados de la consulta.

Texto cambiado

El evento TextChanged se produce siempre que se actualiza el contenido del cuadro de texto. Use la propiedad event args Reason para determinar si el cambio se debe a la entrada del usuario. Si el motivo del cambio es UserInput, filtre los datos en función de la entrada. A continuación, establezca los datos filtrados como ItemsSource del AutoSuggestBox para actualizar la lista de sugerencias.

Para controlar cómo se muestran los elementos en la lista de sugerencias, puede usar DisplayMemberPath o ItemTemplate.

  • Para mostrar el texto de una sola propiedad del elemento de datos, establezca la propiedad DisplayMemberPath para elegir qué propiedad del objeto se va a mostrar en la lista de sugerencias.
  • Para definir una búsqueda personalizada para cada elemento de la lista, use la propiedad ItemTemplate.

Sugerencia elegida

Cuando un usuario navega por la lista de sugerencias mediante el teclado, debe actualizar el texto del cuadro de texto para que coincida.

Puede establecer la propiedad TextMemberPath para elegir qué propiedad del objeto de datos se va a mostrar en el cuadro de texto. Si especifica un TextMemberPath, el cuadro de texto se actualiza automáticamente. Normalmente, debe especificar el mismo valor para DisplayMemberPath y TextMemberPath, por lo que el texto es el mismo en la lista de sugerencias y el cuadro de texto.

Si necesita mostrar más de una propiedad simple, controle el evento SuggestionChosen para rellenar el cuadro de texto con texto personalizado basado en el elemento seleccionado.

Consulta enviada

Controla el evento QuerySubmitted para realizar una acción de consulta adecuada para la aplicación y mostrar el resultado al usuario.

El evento QuerySubmitted se produce cuando un usuario confirma una cadena de consulta. El usuario puede confirmar una consulta de una de estas maneras:

  • Mientras el foco está en el cuadro de texto, presione Entrar o haga clic en el icono de consulta. La propiedad event args ChosenSuggestion es null.
  • Mientras el foco está en la lista de sugerencias, presione Entrar, haga clic o pulse un elemento. La propiedad Rgs ChosenSuggestion del evento contiene el elemento seleccionado en la lista.

En todos los casos, la propiedad QueryText del evento contiene el texto del cuadro de texto.

Este es un AutoSuggestBox sencillo con los controladores de eventos necesarios.

<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.
    }
}

Use un AutoSuggestBox para proporcionar una lista de sugerencias para que un usuario seleccione entre mientras escribe.

De manera predeterminada, el cuadro de entrada de texto no muestra un botón de consulta. Puede establecer la propiedad QueryIcon para agregar un botón con el icono especificado en el lado derecho del cuadro de texto. Por ejemplo, para que el AutoSuggestBox tenga el aspecto de un cuadro de búsqueda típico, agrega un icono "Buscar", como este.

<AutoSuggestBox QueryIcon="Find"/>

Este es un AutoSuggestBox con un icono de "buscar".

Ejemplo de control de sugerencias automáticas con un icono de búsqueda.

Obtener el código de ejemplo