Cuadro combinado y cuadro de lista

Usa un cuadro combinado (también conocido como lista desplegable) para presentar una lista de elementos entre los que un usuario puede seleccionar. Un cuadro combinado se inicia en un estado compacto y se amplía para mostrar una lista de elementos seleccionables. Un cuadro de lista es similar a un cuadro combinado, pero no es contraíble y no tiene un estado compacto. Puedes obtener más información sobre los cuadros de lista al final de este artículo.

Cuando se cierra el cuadro combinado, o bien se muestra la selección actual o bien está vacío si no hay ningún elemento seleccionado. Cuando el usuario amplía el cuadro combinado, este muestra la lista de elementos seleccionables.

¿Es este el control adecuado?

• Use una lista desplegable para permitir que los usuarios seleccionen un valor único de un conjunto de elementos que se pueden representar adecuadamente con líneas de texto únicas.
• Use una lista o vista de cuadrícula en lugar de un cuadro combinado para mostrar los elementos que contienen varias líneas de texto o imágenes.
• Cuando haya menos de cinco elementos, considere la posibilidad de usar botones de radio (si solo se puede seleccionar un elemento) o casillas (si se pueden seleccionar varios elementos).
• Use un cuadro combinado cuando los elementos de selección sean de importancia secundaria en el flujo de la aplicación. Si bien se recomienda la opción predeterminada para la mayoría de los usuarios en la mayoría de las situaciones, mostrar todos los elementos mediante una vista de lista puede atraer más atención a las opciones de la necesaria. Puede ahorrar espacio y minimizar las distracciones con un cuadro combinado.

Ejemplos

Un cuadro combinado en su estado compacto puede mostrar un encabezado.

Aunque los cuadros combinados se expanden para admitir longitudes de cadena más largas, evite cadenas excesivamente largas que sean difíciles de leer.

Si la colección de un cuadro combinado es lo suficientemente larga, aparecerá una barra de desplazamiento para acomodarla. Agrupe los elementos de forma lógica en la lista.

Recomendaciones

• Limite el contenido del texto de los elementos del cuadro combinado a una sola línea.
• Ordene los elementos en un cuadro combinado en el orden más lógico. Agrupe las opciones relacionadas y coloque las opciones más comunes en la parte superior. Ordene los nombres en orden alfabético, los números en orden numérico y las fechas en orden cronológico.

Cuadros de lista

Un cuadro de lista permite al usuario elegir un solo elemento o varios elementos de una colección. Los cuadros de lista son similares a las listas desplegables, salvo que los cuadros de lista siempre están abiertos, no existe un estado compacto (no expandido) para un cuadro de lista. Es posible desplazarse por los elementos de la lista si no hay espacio para mostrar todo.

¿Es un cuadro de lista el control adecuado?

• Un cuadro de lista puede ser útil cuando los elementos de la lista son lo suficientemente importantes como para mostrarlos de forma destacada y cuando hay suficiente espacio en la pantalla para mostrar la lista completa.
• Un cuadro de lista debe llamar la atención del usuario sobre el conjunto completo de alternativas en una elección importante. Por el contrario, una lista desplegable atrae inicialmente la atención del usuario hacia el elemento seleccionado.
• Evite usar un cuadro de lista si:
  • Hay un número muy reducido de elementos para la lista. Un cuadro de lista de selección única que siempre tiene las mismas 2 opciones podría presentarse mejor como botones de radio. Considere también la posibilidad de usar botones de radio cuando haya 3 o 4 elementos estáticos en la lista.
  • El cuadro de lista es de selección única y siempre tiene las mismas 2 opciones en las que una puede estar implícita como contraria de la otra, por ejemplo, "activado" y "desactivado". Use una sola casilla o un conmutador de alternancia.
  • Hay un gran número de elementos. Una mejor opción para las listas largas es la vista de cuadrícula y la vista de lista. Para listas muy largas de datos agrupados, se prefiere el zoom semántico.
  • Los elementos son valores numéricos contiguos. Si ese es el caso, considere la posibilidad de usar un control deslizante.
  • Los elementos de selección son de importancia secundaria en el flujo de la aplicación o se recomienda la opción predeterminada para la mayoría de los usuarios en la mayoría de las situaciones. En su lugar, use una lista desplegable.

Recomendaciones para cuadros de lista

• El intervalo ideal de elementos en un cuadro de lista es de 3 a 9.
• Un cuadro de lista funciona bien cuando sus elementos pueden variar de forma dinámica.
• Si es posible, configure el tamaño de un cuadro de lista de modo que no sea necesario desplazarse ni recorrer su lista de elementos.
• Verifique que esté claro el propósito del cuadro de lista y qué elementos están seleccionados actualmente.
• Reserve los efectos visuales y las animaciones para respuestas táctiles y para el estado seleccionado de los elementos.
• Limite el contenido del texto del elemento del cuadro de lista a una sola línea. Si los elementos son objetos visuales, puede personalizar el tamaño. Si un elemento contiene varias líneas de texto o imágenes, use en su lugar una vista de cuadrícula o una vista de lista.
• Use la fuente predeterminada a menos que las directrices de marca indiquen usar otra.
• No use un cuadro de lista para realizar comandos o para mostrar u ocultar dinámicamente otros controles.

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.

• API de UWP: clase ComboBox, propiedad IsEditable, propiedad Text, evento TextSubmitted, clase ListBox
• Abra la aplicación WinUI 2 Gallery y vea ComboBox en acción. La aplicación WinUI 2 Gallery incluye ejemplos interactivos de la mayoría de los controles, características y funcionalidades de WinUI 2. Obtenga la aplicación en Microsoft Store u obtenga el código fuente en GitHub.

WinUI 2.2 o versiones posteriores incluye una nueva plantilla para este control que usa esquinas redondeadas. Para obtener más información, consulta Radio de redondeo.

Creación de un cuadro combinado

• API importantes: clase ComboBox, propiedad IsEditable, propiedad Text, evento TextSubmitted, clase ListBox

Abra la aplicación WinUI 3 Gallery y vea ComboBox 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.

Puedes rellenar el cuadro combinado mediante la adición de objetos directamente a la colección Items o el enlace de la propiedad ItemsSource a un origen de datos. Los elementos agregados al elemento ComboBox se ajustan en contenedores ComboBoxItem.

Este es un cuadro combinado simple con los elementos agregados en XAML.

<ComboBox Header="Colors" PlaceholderText="Pick a color" Width="200">
    <x:String>Blue</x:String>
    <x:String>Green</x:String>
    <x:String>Red</x:String>
    <x:String>Yellow</x:String>
</ComboBox>

En el ejemplo siguiente se muestra cómo enlazar un cuadro combinado a una colección de objetos FontFamily.

<ComboBox x:Name="FontsCombo" Header="Fonts" Height="44" Width="296"
          ItemsSource="{x:Bind fonts}" DisplayMemberPath="Source"/>

ObservableCollection<FontFamily> fonts = new ObservableCollection<FontFamily>()
{
    fonts.Add(new FontFamily("Arial"));
    fonts.Add(new FontFamily("Courier New"));
    fonts.Add(new FontFamily("Times New Roman"));
};

Selección de elementos

Igual que ListView y GridView, ComboBox deriva de Selector, por lo que puedes obtener la selección del usuario de la misma manera estándar.

Puedes obtener o establecer el elemento seleccionado del cuadro combinado mediante la propiedad SelectedItem y obtener o establecer el índice del elemento seleccionado mediante el uso de la propiedad SelectedIndex.

Para obtener el valor de una propiedad determinada en el elemento de datos seleccionado, puedes usar la propiedad SelectedValue. En este caso, establece SelectedValuePath para especificar la propiedad del elemento seleccionado de la que se obtiene el valor.

Sugerencia

Si estableces SelectedItem o SelectedIndex para indicar la selección predeterminada, se produce una excepción si la propiedad se establece antes de que se rellene la colección Items del cuadro combinado. A menos que definas los elementos en XAML, es mejor controlar el evento Loaded del cuadro combinado y establecer SelectedItem o SelectedIndex en el controlador de eventos Loaded.

Puedes enlazar a estas propiedades en XAML o controlar el evento SelectionChanged para responder a los cambios de selección.

En el código del controlador de eventos, puedes obtener el elemento seleccionado a partir de la propiedad SelectionChangedEventArgs.AddedItems. Puedes obtener el elemento seleccionado anteriormente, si lo hay, a partir de la propiedad SelectionChangedEventArgs.RemovedItems. Las colecciones AddedItems y RemovedItems contienen solo 1 elemento porque el cuadro combinado no es compatible con la selección múltiple.

En este ejemplo se muestra cómo controlar el evento SelectionChanged y cómo enlazar al elemento seleccionado.

<StackPanel>
    <ComboBox x:Name="colorComboBox" Width="200"
              Header="Colors" PlaceholderText="Pick a color"
              SelectionChanged="ColorComboBox_SelectionChanged">
        <x:String>Blue</x:String>
        <x:String>Green</x:String>
        <x:String>Red</x:String>
        <x:String>Yellow</x:String>
    </ComboBox>

    <Rectangle x:Name="colorRectangle" Height="30" Width="100"
               Margin="0,8,0,0" HorizontalAlignment="Left"/>

    <TextBlock Text="{x:Bind colorComboBox.SelectedIndex, Mode=OneWay}"/>
    <TextBlock Text="{x:Bind colorComboBox.SelectedItem, Mode=OneWay}"/>
</StackPanel>

private void ColorComboBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    string colorName = e.AddedItems[0].ToString();
    Color color;
    switch (colorName)
    {
        case "Yellow":
            color = Colors.Yellow;
            break;
        case "Green":
            color = Colors.Green;
            break;
        case "Blue":
            color = Colors.Blue;
            break;
        case "Red":
            color = Colors.Red;
            break;
    }
    colorRectangle.Fill = new SolidColorBrush(color);
}

SelectionChanged y navegación de teclado

De manera predeterminada, el evento SelectionChanged se produce cuando un usuario hace clic en Entrar, o lo pulsa o presiona, en un elemento de la lista para confirmar su selección, y se cierra el cuadro combinado. La selección no cambia cuando el usuario navega por la lista abierta del cuadro combinado con las teclas de dirección del teclado.

Para crear un cuadro combinado que se "actualice en directo" mientras el usuario se desplaza por la lista abierta con las teclas de dirección (como un menú desplegable de fuente), establece SelectionChangedTrigger en Siempre. Esto provoca que el evento SelectionChanged se produzca cuando cambia el foco a otro elemento de la lista abierta.

Cambio de comportamiento del elemento seleccionado

En Windows 10, versión 1809 (SDK 17763) o versiones posteriores, el comportamiento de los elementos seleccionados se actualiza para admitir los cuadros combinados editables.

Antes de SDK 17763, el valor de la propiedad SelectedItem (y, por lo tanto, SelectedValue y SelectedIndex) debía estar en la colección Items del cuadro combinado. Con el ejemplo anterior, establece los resultados de colorComboBox.SelectedItem = "Pink" en:

• SelectedItem = null
• SelectedItem = null
• SelectedIndex = -1

En SDK 17763 y versiones posteriores, el valor de la propiedad SelectedItem (y, por lo tanto, SelectedValue y SelectedIndex) no hace falta que esté en la colección Items del cuadro combinado. Con el ejemplo anterior, establece los resultados de colorComboBox.SelectedItem = "Pink" en:

• SelectedItem = Pink
• SelectedValue = Pink
• SelectedIndex = -1

Búsqueda de texto

Los cuadros combinados admiten de forma automática la búsqueda dentro de sus colecciones. A medida que los usuarios escriben caracteres en un teclado físico mientras se centran en un cuadro combinado abierto o cerrado, los candidatos que coincidan con la cadena del usuario se incorporan a la vista. Esta funcionalidad es especialmente útil al navegar por una lista larga. Por ejemplo, cuando se interactúa con un menú desplegable que contiene una lista de estados, los usuarios pueden presionar la tecla "w" para mostrar "Washington" para la selección rápida. En el texto de búsqueda no se distinguen mayúsculas de minúsculas.

Puedes establecer la propiedad IsTextSearchEnabled en false para deshabilitar esta función.

Realización de un cuadro combinado editable

Importante

Esta característica requiere Windows 10, versión 1809 (SDK 17763) o una versión posterior.

De manera predeterminada, un cuadro combinado permite al usuario seleccionar de una lista predefinida de opciones. Sin embargo, hay casos en los que la lista solo contiene un subconjunto de valores válidos y el usuario debe ser capaz de escribir otros valores que no aparezcan. Para ello, puedes hacer que el cuadro combinado sea editable.

Para hacer que un cuadro combinado sea editable, establece la propiedad IsEditable en true. Luego, controla el evento TextSubmitted para que funcione con el valor que ha introducido el usuario.

De manera predeterminada, el valor de SelectedItem se actualiza cuando el usuario confirma texto personalizado. Puedes invalidar este comportamiento estableciendo Handled en true en los argumentos del evento TextSubmitted. Cuando el evento está marcado como controlado, el cuadro combinado no realizará ninguna acción adicional después del evento y permanecerá en el estado de edición. SelectedItem no se actualizará.

En este ejemplo se muestra un cuadro combinado editable simple. La lista contiene cadenas sencillas, y cualquier valor que haya introducido el usuario se usa tal como se ha introducido.

Un selector de "nombres usados recientemente" permite al usuario introducir cadenas personalizadas. La lista "RecentlyUsedNames" contiene algunos valores entre los que el usuario puede elegir, pero también puede agregar un nuevo valor personalizado. La propiedad "CurrentName" representa el nombre introducido actualmente.

<ComboBox IsEditable="true"
          ItemsSource="{x:Bind RecentlyUsedNames}"
          SelectedItem="{x:Bind CurrentName, Mode=TwoWay}"/>

Texto enviado

Puedes controlar el evento TextSubmitted para que funcione con el valor que ha introducido el usuario. En el controlador del evento, se suele validar que el valor que el usuario introduce es válido. Después, usa el valor en la aplicación. En función de la situación, también podrías agregar el valor a la lista de opciones del cuadro combinado para un uso futuro.

El evento TextSubmitted se produce cuando se cumplen estas condiciones:

• La propiedad IsEditable es true.
• El usuario escribe el texto que no coincide con una entrada existente en la lista del cuadro combinado.
• El usuario presiona Entrar o mueve el foco en el cuadro combinado.

No se produce el evento TextSubmitted si el usuario escribe texto y luego navega hacia arriba o hacia abajo por la lista.

Ejemplo: validación de la entrada y uso de forma local

En este ejemplo, un selector de tamaño de fuente contiene un conjunto de valores correspondiente a la rampa de tamaño de fuente, pero el usuario puede escribir tamaños de fuente que no estén en la lista.

Cuando el usuario agrega un valor que no está en la lista, el tamaño de fuente se actualiza, pero el valor no se agrega a la lista de tamaños de fuente.

Si el valor recién escrito no es válido, usa el elemento SelectedValue para revertir la propiedad Text al último valor correcto conocido.

<ComboBox x:Name="fontSizeComboBox"
          IsEditable="true"
          ItemsSource="{x:Bind ListOfFontSizes}"
          TextSubmitted="FontSizeComboBox_TextSubmitted"/>

private void FontSizeComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSubmittedEventArgs e)
{
    if (byte.TryParse(e.Text, out double newValue))
    {
        // Update the app's font size.
        _fontSize = newValue;
    }
    else
    {
        // If the item is invalid, reject it and revert the text.
        // Mark the event as handled so the framework doesn't update the selected item.
        sender.Text = sender.SelectedValue.ToString();
        e.Handled = true;
    }
}

Ejemplo: validación de la entrada y adición a una lista

En este caso, un "selector de color favorito" contiene los colores favoritos más comunes (rojo, azul, verde, naranja), pero el usuario puede escribir un color favorito que no esté en la lista. Cuando el usuario agrega un color válido (por ejemplo, rosa), el color recién introducido se agrega a la lista y se establece como el "color favorito" activo.

<ComboBox x:Name="favoriteColorComboBox"
          IsEditable="true"
          ItemsSource="{x:Bind ListOfColors}"
          TextSubmitted="FavoriteColorComboBox_TextSubmitted"/>

private void FavoriteColorComboBox_TextSubmitted(ComboBox sender, ComboBoxTextSubmittedEventArgs e)
{
    if (IsValid(e.Text))
    {
        FavoriteColor newColor = new FavoriteColor()
        {
            ColorName = e.Text,
            Color = ColorFromStringConverter(e.Text)
        }
        ListOfColors.Add(newColor);
    }
    else
    {
        // If the item is invalid, reject it but do not revert the text.
        // Mark the event as handled so the framework doesn't update the selected item.
        e.Handled = true;
    }
}

bool IsValid(string Text)
{
    // Validate that the string is: not empty; a color.
}

Obtener el código de ejemplo

• Muestra de la Galería WinUI: vea todos los controles XAML en un formato interactivo.

Artículos relacionados

• Controles de texto
• Directrices sobre revisión ortográfica
• Clase TextBox
• Clase PasswordBox
• Propiedad String.Length