Barra de búsqueda

La interfaz de usuario de aplicación multiplataforma de .NET (.NET MAUI) SearchBar es un control de entrada de usuario que se usa para iniciar una búsqueda. El control SearchBar admite texto de marcador, entrada de consulta, ejecución de búsqueda y cancelación. La siguiente captura de pantalla de iOS muestra una consulta SearchBar con los resultados presentados en un ListView.

SearchBar define las siguientes propiedades:

• CancelButtonColor es un Color que define el color del botón cancelar.
• HorizontalTextAlignment es un valor de enumeración TextAlignment que define la alineación horizontal del texto de la consulta.
• SearchCommand es un ICommand que permite enlazar acciones de usuario, como pulsaciones de dedo o clics, a los comandos definidos en un modelo de vista.
• SearchCommandParameteres un objeto object que especifica el parámetro que se debe pasar al SearchCommand.
• VerticalTextAlignment es un valor de enumeración TextAlignment que define la alineación vertical del texto de consulta.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

Además, SearchBar define un evento SearchButtonPressed, que se genera cuando se hace clic en el botón de búsqueda o se pulsa la tecla Enter.

SearchBar se deriva de la clase InputView, de la que hereda las propiedades siguientes:

• CharacterSpacing, del tipo double, es el espaciado entre los caracteres del texto introducidos.
• CursorPosition, de tipo int, define la posición del cursor dentro del editor.
• FontAttributes, de tipo FontAttributes, determina el estilo de texto.
• FontAutoScalingEnabled, de tipo bool, define si el texto reflejará las preferencias de escalado establecidas en el sistema operativo. El valor predeterminado de esta propiedad es true.
• FontFamily, del tipo string, define la familia de fuentes.
• FontSize, de tipo double, define el tamaño de fuente.
• IsReadOnly, de tipo bool, define si se debe impedir que el usuario modifique el texto. El valor predeterminado de esta propiedad es false.
• IsSpellCheckEnabled, de tipo bool, controla si la revisión ortográfica está habilitada.
• IsTextPredictionEnabled, de tipo bool, controla si la predicción de texto y la corrección automática de texto están habilitadas.
• Keyboard, de tipo Keyboard, especifica el teclado de entrada de texto que se muestra al escribir texto.
• MaxLength, de tipo int, define la longitud máxima de entrada.
• Placeholder, de tipo string, define el texto que se muestra cuando el control está vacío.
• PlaceholderColor, del tipo Color, define el color del texto del marcador de posición.
• SelectionLength, de tipo int, representa la longitud del texto seleccionado dentro del control.
• Text, de tipo string, define el texto escrito en el control.
• TextColor, de tipo Color, define el color del texto especificado.
• TextTransform, de tipo TextTransform, especifica el uso de mayúsculas y minúsculas del texto introducido.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

Además, InputView define un evento TextChanged, que se genera cuando cambia el texto de Entry. El objeto TextChangedEventArgs que acompaña al evento TextChanged tiene propiedades NewTextValue y OldTextValue, que especifican el texto nuevo y antiguo, respectivamente.

Crear una SearchBar

Para crear una barra de búsqueda, crea un objeto SearchBar y establece su propiedad Placeholder en texto, que indique al usuario que escriba un término de búsqueda.

En el siguiente ejemplo de XAML se muestra cómo crear una SearchBar.

<SearchBar Placeholder="Search items..." />

El código de C# equivalente es el siguiente:

SearchBar searchBar = new SearchBar { Placeholder = "Search items..." };

Nota:

En iOS, el teclado virtual puede cubrir un campo de entrada de texto cuando el campo está cerca de la parte inferior de la pantalla, haciendo difícil introducir texto. Sin embargo, en una aplicación .NET MAUI iOS, las páginas se desplazan automáticamente cuando el teclado táctil cubre un campo de texto, de modo que el campo quede por encima del teclado táctil. Puede llamarse el método KeyboardAutoManagerScroll.Disconnect, en el espacio de nombres Microsoft.Maui.Platform, para deshabilitar este comportamiento predeterminado. Puede llamarse al método KeyboardAutoManagerScroll.Connect para volver a habilitar el comportamiento después de deshabilitarlo.

Realizar una búsqueda con controladores de eventos

Una búsqueda se puede ejecutar mediante el control SearchBar adjuntando un controlador de eventos a uno de los eventos siguientes:

• SearchButtonPressed, al que se llama cuando el usuario hace clic en el botón de búsqueda o presiona la tecla ENTRAR.
• TextChanged, que se llama cada vez que se cambia el texto del cuadro de consulta. Este evento se hereda de la clase InputView.

En el ejemplo XAML siguiente se muestra un controlador de eventos asociado al evento TextChanged y se usa ListView para mostrar los resultados de la búsqueda:

<SearchBar TextChanged="OnTextChanged" />
<ListView x:Name="searchResults" >

En este ejemplo, el evento TextChanged se establece en un controlador de eventos denominado OnTextChanged. Este controlador se encuentra en el archivo de código subyacente:

void OnTextChanged(object sender, EventArgs e)
{
    SearchBar searchBar = (SearchBar)sender;
    searchResults.ItemsSource = DataService.GetSearchResults(searchBar.Text);
}

En este ejemplo, se usa una clase DataService con un método GetSearchResults para devolver elementos que coinciden con una consulta. El valor de propiedad SearchBar del control Text se pasa al método GetSearchResults y el resultado se usa para actualizar la propiedad ListView del control ItemsSource. El efecto general es que los resultados de la búsqueda se muestran en ListView.

Realizar una búsqueda usando un ViewModel

Una búsqueda se puede ejecutar sin controladores de eventos enlazando la propiedad SearchCommand a una implementación ICommand. Para obtener más información sobre los comandos, consulta Comandos.

En el ejemplo siguiente se muestra una clase viewmodel que contiene una propiedad ICommand denominada PerformSearch:

public class SearchViewModel : INotifyPropertyChanged
{
    public event PropertyChangedEventHandler PropertyChanged;

    protected virtual void NotifyPropertyChanged([CallerMemberName] string propertyName = "")
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }

    public ICommand PerformSearch => new Command<string>((string query) =>
    {
        SearchResults = DataService.GetSearchResults(query);
    });

    private List<string> searchResults = DataService.Fruits;
    public List<string> SearchResults
    {
        get
        {
            return searchResults;
        }
        set
        {
            searchResults = value;
            NotifyPropertyChanged();
        }
    }
}

Nota:

El modelo de vista supone la existencia de una clase DataService capaz de realizar búsquedas.

En el ejemplo XAML siguiente se consume la clase SearchViewModel:

<ContentPage ...
             xmlns:viewmodels="clr-namespace:SearchBarDemos.ViewModels"
             x:DataType="viewmodels:SearchViewModel">
    <ContentPage.BindingContext>
        <viewmodels:SearchViewModel />
    </ContentPage.BindingContext>
    <StackLayout>
        <SearchBar x:Name="searchBar"
                   SearchCommand="{Binding PerformSearch}"
                   SearchCommandParameter="{Binding Text, x:DataType='SearchBar', Source={x:Reference searchBar}}"/>
        <ListView x:Name="searchResults"
                  ItemsSource="{Binding SearchResults}" />
    </StackLayout>
</ContentPage>

En el ejemplo, BindingContext se establece en una instancia de la clase SearchViewModel. La propiedad SearchBar.SearchCommand se enlaza a la propiedad PerformSearch de viewmodel y la propiedad SearchCommandParameter se enlaza a la propiedad SearchBar.Text. De forma similar, la propiedad ListView.ItemsSource se enlaza a la propiedad SearchResults del viewmodel.

Ocultar y mostrar el teclado en pantalla

La clase SoftInputExtensions, en el espacio de nombres Microsoft.Maui, proporciona una serie de métodos de extensión que admiten la interacción con el teclado virtual en los controles que admiten la entrada de texto. La clase define los métodos siguientes:

• IsSoftInputShowing, que comprueba si el dispositivo muestra actualmente el teclado de entrada táctil.
• HideSoftInputAsync, que intentará ocultar el teclado de entrada suave si está actualmente visible.
• ShowSoftInputAsync, que intentará mostrar el teclado en pantalla si actualmente está oculto.

En el ejemplo siguiente se muestra cómo ocultar el teclado virtual en un objeto SearchBar denominado searchBar, si está visible.

if (searchBar.IsSoftInputShowing())
   await searchBar.HideSoftInputAsync(System.Threading.CancellationToken.None);