Cuadro de sugerencias automáticas

  • Artículo

Usa un AutoSuggestBox para proporcionar una lista de sugerencias para que el usuario seleccione una a medida que escribe.

Un cuadro de sugerencias automáticas

¿Es este el control adecuado?

Si quieres un control simple y personalizable que permita la búsqueda de texto con una lista de sugerencias, elige un cuadro de sugerencias automáticas.

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 de un cuadro de texto con la sugerencia opcional:

Ejemplo de punto de entrada para el control de la sugerencia automática

La lista de resultados de sugerencias automáticas se rellena automáticamente cuando el usuario comienza 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 de control ampliado de la sugerencia automática

Recomendaciones

  • Cuando se usa un cuadro de sugerencias automáticas para realizar búsquedas y no existen resultados para el texto escrito, se muestra el mensaje de una línea "No hay resultados", para que los usuarios sepan que su solicitud se ha ejecutado:

    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.

Las API de este control existen 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 y plantillas más actuales para todos los controles. WinUI 2.2 o posterior 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, las características y la funcionalidad de WinUI 3. Obtenga la aplicación en Microsoft Store o el código fuente en GitHub.

Para usar un AutoSuggestBox, debes responder a 3 acciones del usuario.

  • Cambio de texto: actualizar la lista de sugerencias a medida que el usuario escribe texto.
  • Elección de sugerencia: Actualizar el cuadro de texto cuando el usuario seleccione una sugerencia de la lista de sugerencias.
  • Envío de consultas: cuando el usuario envíe una consulta, mostrar los resultados de la misma.

Cambio de texto

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

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

  • Para mostrar el texto de una sola propiedad de tu elemento de datos, establece la propiedad DisplayMemberPath para elegir qué propiedad del objeto mostrar en la lista de sugerencias.
  • Para definir un aspecto personalizado para cada elemento en la lista, usa la propiedad ItemTemplate.

Elección de sugerencia

Cuando un usuario navega por la lista de sugerencias con el teclado, debes actualizar el texto en el cuadro de texto para que ambos coincidan.

Puedes establecer la propiedad TextMemberPath para elegir qué propiedad del objeto de datos mostrar en el cuadro de texto. Si especificas un TextMemberPath, el cuadro de texto se actualiza automáticamente. Normalmente debes especificar el mismo valor para DisplayMemberPath y TextMemberPath para que el texto de la lista de sugerencias y el del cuadro de texto sea el mismo.

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

Envío de consultas

Gestiona el evento QuerySubmitted para realizar una acción de consulta adecuada para tu 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, presiona Entrar o haz clic en el icono de la consulta. La propiedad de los argumentos del evento ChosenSuggestion es null.
  • Mientras el foco está en la lista de sugerencias, presiona Entrar, haz clic o pulsa en un elemento. La propiedad de los argumentos del evento ChosenSuggestion contiene el elemento que se seleccionó en la lista.

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

Este es un AutoSuggestBox simple 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.
    }
}

Usa un AutoSuggestBox para proporcionar una lista de sugerencias para que el usuario seleccione una a medida que escribe.

De manera predeterminada, el cuadro de entrada de texto no muestra un botón de consulta. Puedes establecer la propiedad QueryIcon para agregar un botón con el icono especificado en la parte derecha 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"/>

Aquí se muestra un AutoSuggestBox con un icono 'Buscar'.

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

Obtención del código de ejemplo