Condividi tramite

SearchBar

  • Articolo

L'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) SearchBar è un controllo di input utente usato per avviare una ricerca. Il SearchBar controllo supporta testo segnaposto, input di query, esecuzione della ricerca e annullamento. Lo screenshot iOS seguente mostra una SearchBar query con i risultati visualizzati in :ListView

Screenshot di un controllo SearchBar.

SearchBar definisce le proprietà seguenti:

  • CancelButtonColor è un Color oggetto che definisce il colore del pulsante Annulla.
  • HorizontalTextAlignment è un TextAlignment valore di enumerazione che definisce l'allineamento orizzontale del testo della query.
  • SearchCommand è un oggetto ICommand che consente l'associazione di azioni utente, ad esempio tocco di dito o clic, ai comandi definiti in un modello di visualizzazione.
  • SearchCommandParameter è un object oggetto che specifica il parametro che deve essere passato a SearchCommand.
  • VerticalTextAlignment è un TextAlignment valore di enumerazione che definisce l'allineamento verticale del testo della query.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere destinazioni di data binding e stili.

Definisce inoltre SearchBar un SearchButtonPressed evento, che viene generato quando si fa clic sul pulsante di ricerca o viene premuto il tasto INVIO.

SearchBar deriva dalla InputView classe da cui eredita le proprietà seguenti:

  • CharacterSpacing, di tipo double, imposta la spaziatura tra i caratteri nel testo immesso.
  • CursorPosition, di tipo int, definisce la posizione del cursore all'interno dell'editor.
  • FontAttributes, di tipo FontAttributes, determina lo stile del testo.
  • FontAutoScalingEnabled, di tipo bool, definisce se il testo rifletterà le preferenze di ridimensionamento impostate nel sistema operativo. Il valore predefinito di questa proprietà è true.
  • FontFamily, di tipo string, definisce la famiglia di caratteri.
  • FontSize, di tipo double, definisce le dimensioni del carattere.
  • IsReadOnly, di tipo bool, definisce se l'utente deve essere impedito di modificare il testo. Il valore predefinito di questa proprietà è false.
  • IsSpellCheckEnabled, di tipo bool, controlla se il controllo ortografico è abilitato.
  • IsTextPredictionEnabled, di tipo bool, controlla se è abilitata la stima del testo e la correzione automatica del testo.
  • Keyboard, di tipo Keyboard, specifica la tastiera di input soft visualizzata quando si immette testo.
  • MaxLength, di tipo int, definisce la lunghezza massima di input.
  • Placeholder, di tipo string, definisce il testo visualizzato quando il controllo è vuoto.
  • PlaceholderColor, di tipo Color, definisce il colore del testo segnaposto.
  • SelectionLength, di tipo int, rappresenta la lunghezza del testo selezionato all'interno del controllo .
  • Text, di tipo string, definisce il testo immesso nel controllo .
  • TextColor, di tipo Color, definisce il colore del testo immesso.
  • TextTransform, di tipo TextTransform, specifica la combinazione di maiuscole e minuscole del testo immesso.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere destinazioni di data binding e stili.

Definisce inoltre InputView un TextChanged evento, che viene generato quando il testo nelle Entry modifiche. L'oggetto TextChangedEventArgs che accompagna l'evento TextChanged ha NewTextValue proprietà e OldTextValue , che specificano rispettivamente il testo nuovo e precedente.

Per creare una barra di ricerca, creare un SearchBar oggetto e impostarne la Placeholder proprietà sul testo che indica all'utente di immettere un termine di ricerca.

L'esempio XAML seguente illustra come creare un oggetto SearchBar:

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

Il codice C# equivalente è il seguente:

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

Nota

In iOS, la tastiera di input flessibile può coprire un campo di input di testo quando il campo si trova vicino alla parte inferiore dello schermo, rendendo difficile l'immissione di testo. Tuttavia, in un'app .NET MAUI iOS, le pagine scorrono automaticamente quando la tastiera di input flessibile copriva un campo di immissione di testo, in modo che il campo si trova sopra la tastiera di input soft. Il KeyboardAutoManagerScroll.Disconnect metodo, nello spazio dei Microsoft.Maui.Platform nomi , può essere chiamato per disabilitare questo comportamento predefinito. Il KeyboardAutoManagerScroll.Connect metodo può essere chiamato per riabilitare il comportamento dopo che è stato disabilitato.

Eseguire una ricerca con gestori eventi

È possibile eseguire una ricerca usando il SearchBar controllo associando un gestore eventi a uno degli eventi seguenti:

  • SearchButtonPressed, che viene chiamato quando l'utente fa clic sul pulsante di ricerca o preme il tasto INVIO.
  • TextChanged, che viene chiamato ogni volta che viene modificato il testo nella casella di query. Questo evento viene ereditato dalla InputView classe .

L'esempio XAML seguente mostra un gestore eventi associato all'evento TextChanged e usa un ListView oggetto per visualizzare i risultati della ricerca:

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

In questo esempio l'evento TextChanged viene impostato su un gestore eventi denominato OnTextChanged. Questo gestore si trova nel file code-behind:

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

In questo esempio viene usata una DataService classe con un GetSearchResults metodo per restituire gli elementi che corrispondono a una query. Il SearchBar valore della proprietà del Text controllo viene passato al GetSearchResults metodo e il risultato viene utilizzato per aggiornare la ListView proprietà del ItemsSource controllo. L'effetto complessivo è che i risultati della ListViewricerca vengono visualizzati in .

Eseguire una ricerca usando un modello di visualizzazione

Una ricerca può essere eseguita senza gestori eventi associando la SearchCommand proprietà a un'implementazione ICommand . Per altre informazioni sui comandi, vedere Comando.

Nell'esempio seguente viene illustrata una classe viewmodel contenente una ICommand proprietà denominata 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

Il modello di visualizzazione presuppone l'esistenza di una DataService classe in grado di eseguire ricerche.

L'esempio XAML seguente usa la SearchViewModel classe :

<ContentPage ...>
    <ContentPage.BindingContext>
        <viewmodels:SearchViewModel />
    </ContentPage.BindingContext>
    <StackLayout>
        <SearchBar x:Name="searchBar"
                   SearchCommand="{Binding PerformSearch}"
                   SearchCommandParameter="{Binding Text, Source={x:Reference searchBar}}"/>
        <ListView x:Name="searchResults"
                  ItemsSource="{Binding SearchResults}" />
    </StackLayout>
</ContentPage>

In questo esempio l'oggetto BindingContext è impostato su un'istanza della SearchViewModel classe . La SearchBar.SearchCommand proprietà viene associata alla PerformSearch proprietà viewmodel e la SearchCommandParameter proprietà viene associata alla SearchBar.Text proprietà . Analogamente, la ListView.ItemsSource proprietà è associata alla SearchResults proprietà del modello di visualizzazione.

Nascondere e visualizzare la tastiera di input soft

La SoftInputExtensions classe, nello spazio dei Microsoft.Maui nomi , fornisce una serie di metodi di estensione che supportano l'interazione con la tastiera di input soft sui controlli che supportano l'input di testo. La classe definisce i metodi seguenti:

  • IsSoftInputShowing, che verifica se il dispositivo mostra attualmente la tastiera di input soft.
  • HideSoftInputAsync, che tenterà di nascondere la tastiera di input soft se è attualmente visualizzata.
  • ShowSoftInputAsync, che tenterà di visualizzare la tastiera di input soft se è attualmente nascosta.

Nell'esempio seguente viene illustrato come nascondere la tastiera di input soft in un SearchBar oggetto denominato searchBar, se è attualmente visualizzato:

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