SearchBar

Die .NET Multi-platform App UI (.NET MAUI) SearchBar ist ein Benutzereingabe-Steuerelement, das zur Initiierung einer Suche verwendet wird. Das SearchBar-Steuerelement unterstützt Platzhaltertext, Abfrageeingabe, Suchausführung und Abbruch. Der folgende iOS-Screenshot zeigt eine SearchBar-Abfrage, deren Ergebnisse in einem ListView angezeigt werden:

SearchBar definiert die folgenden Eigenschaften:

• CancelButtonColor ist ein Color, das die Farbe der Abbruch-Schaltfläche definiert.
• HorizontalTextAlignment ist ein TextAlignment-Enumerationswert, der die horizontale Ausrichtung des Abfragetextes definiert.
• SearchCommand ist ein ICommand, das die Bindung von Benutzeraktionen, wie Fingertipps oder Klicks, an Befehle ermöglicht, die in einem Viewmodel definiert sind.
• SearchCommandParameter ist ein object, das den Parameter angibt, der an den SearchCommand übergeben werden soll.
• VerticalTextAlignment ist ein TextAlignment-Enumerationswert, der die vertikale Ausrichtung des Abfragetextes definiert.

Diese Eigenschaften werden von BindableProperty-Objekten unterstützt, was bedeutet, dass sie Ziele von Datenbindungen sein können und formatiert werden können.

Darüber hinaus definiert SearchBar ein SearchButtonPressed-Ereignis, das ausgelöst wird, wenn die Suchschaltfläche angeklickt oder die Eingabetaste gedrückt wird.

SearchBar leitet sich von der Klasse InputView ab, von der sie die folgenden Eigenschaften erbt:

• CharacterSpacing, vom Typ double, legt den Abstand zwischen den Zeichen im eingegebenen Text fest.
• CursorPosition, vom Typ int, definiert die Position des Cursors innerhalb des Editors.
• FontAttributes, vom Typ FontAttributes, bestimmt die Textformatvorlage.
• FontAutoScalingEnabled, vom Typ bool, definiert, ob der Text Skalierungspräferenzen im Betriebssystem entspricht. Der Standardwert dieser Eigenschaft ist true.
• FontFamily, vom Typ string, definiert die Schriftartfamilie.
• FontSize, vom Typ double, definiert den Schriftgrad.
• IsReadOnly, vom Typ bool, legt fest, ob der Benutzer daran gehindert werden soll, Text zu ändern. Der Standardwert dieser Eigenschaft ist false.
• IsSpellCheckEnabled, vom Typ bool, steuert, ob die Rechtschreibprüfung aktiviert ist.
• IsTextPredictionEnabled, vom Typ bool, steuert, ob Textvorhersage und automatische Textkorrektur aktiviert ist.
• Keyboard, vom Typ Keyboard, gibt die Softeingabetastatur an, die beim Eingeben von Text angezeigt wird.
• MaxLength, vom Typ int, definiert die maximale Eingabelänge.
• Placeholder, vom Typ string, definiert den Text, der angezeigt wird, wenn das Steuerelement leer ist.
• PlaceholderColor, vom Typ Color, definiert die Farbe des Platzhaltertextes.
• SelectionLength, vom Typ int, stellt die Länge des markierten Texts innerhalb des Steuerelements dar.
• Text, vom Typ string, definiert den in das Steuerelement eingegebenen Text.
• TextColor, vom Typ Color, definiert die Farbe des eingegebenen Textes.
• TextTransform, vom Typ TextTransform, gibt die Schreibweise des eingegebenen Textes an.

Diese Eigenschaften werden von BindableProperty-Objekten unterstützt, was bedeutet, dass sie Ziele von Datenbindungen sein können und formatiert werden können.

Darüber hinaus definiert InputView ein TextChanged-Ereignis, das ausgelöst wird, wenn sich der Text in Entry ändert. Das TextChangedEventArgs-Objekt, das das TextChanged-Ereignis begleitet, hat die Eigenschaften NewTextValue und OldTextValue, die den neuen bzw. alten Text angeben.

Erstellen einer Suchleiste

Um eine Suchleiste zu erstellen, erstellen Sie ein SearchBar-Objekt und setzen dessen Placeholder-Eigenschaft auf einen Text, der den/die Benutzer*in zur Eingabe eines Suchbegriffs auffordert.

Im folgenden Beispiel wird gezeigt, wie ein SearchBar erstellt wird.

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

Der entsprechende C#-Code lautet:

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

Hinweis

Unter iOS kann die Softeingabetastatur ein Texteingabefeld abdecken, wenn sich das Feld am unteren Rand des Bildschirms befindet, wodurch es schwierig ist, Text einzugeben. In einer .NET MAUI iOS-App scrollen Seiten jedoch automatisch, wenn die Softeingabetastatur ein Texteingabefeld abdecken würde, sodass sich das Feld über der Bildschirmtastatur befindet. Die KeyboardAutoManagerScroll.Disconnect-Methode im Microsoft.Maui.Platform-Namespace kann aufgerufen werden, um dieses Standardverhalten zu deaktivieren. Die KeyboardAutoManagerScroll.Connect-Methode kann aufgerufen werden, um das Verhalten erneut zu aktivieren, nachdem sie deaktiviert wurde.

Durchführen einer Suche mit Ereignishandlern

Eine Suche kann mit dem SearchBar-Steuerelement ausgeführt werden, indem ein Ereignishandler an eines der folgenden Ereignisse angehängt wird:

• SearchButtonPressed, die aufgerufen wird, wenn der/die Benutzer*in entweder auf die Schaltfläche Suchen klickt oder die Eingabetaste drückt.
• TextChanged, wird immer dann aufgerufen, wenn der Text im Abfragefeld geändert wird. Diese Eigenschaft wird von der InputView-Klasse geerbt.

Das folgende XAML-Beispiel zeigt einen Eventhandler, der an das TextChanged-Ereignis angehängt ist und ein ListView verwendet, um Suchergebnisse anzuzeigen:

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

In diesem Beispiel wird das Ereignis TextChanged auf einen Ereignishandler namens OnTextChanged gesetzt. Dieser Handler befindet sich in der CodeBehind-Datei:

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

In diesem Beispiel wird eine DataService-Klasse mit einer GetSearchResults-Methode verwendet, um Elemente zurückzugeben, die einer Abfrage entsprechen. Der Text-Eigenschaftswert des SearchBar-Steuerelements wird an die GetSearchResults-Methode übergeben und das Ergebnis wird zur Aktualisierung der ItemsSource-Eigenschaft des ListView-Steuerelements verwendet. Der Gesamteffekt ist, dass die Suchergebnisse in der ListView angezeigt werden.

Durchführen einer Suche mithilfe eines Viewmodels

Eine Suche kann ohne Ereignishandler ausgeführt werden, indem die SearchCommand-Eigenschaft an eine ICommand-Implementierung gebunden wird. Für weitere Informationen über die Befehlsgebung siehe Befehlsgebung.

Das folgende Beispiel zeigt eine Viewmodel-Klasse, die eine ICommand-Eigenschaft namens PerformSearch enthält:

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();
        }
    }
}

Hinweis

Das Viewmodel setzt das Vorhandensein einer DataService-Klasse voraus, die in der Lage ist, Suchen durchzuführen.

Im folgenden XAML-Beispiel wird die Klasse SearchViewModel verwendet:

<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 diesem Beispiel wird die BindingContext auf eine Instanz der Klasse SearchViewModel gesetzt. Die SearchBar.SearchCommand-Eigenschaft bindet an die PerformSearch-Viewmodel-Eigenschaft, und die SearchCommandParameter-Eigenschaft bindet an die SearchBar.Text-Eigenschaft. In ähnlicher Weise ist die Eigenschaft ListView.ItemsSource an die Eigenschaft SearchResults des Viewmodels gebunden.

Ausblenden und Anzeigen der Bildschirmtastatur

Die Klasse SoftInputExtensions im Namespace Microsoft.Maui bietet eine Reihe von Erweiterungsmethoden, die die Interaktion mit der Bildschirmtastatur auf Steuerelementen unterstützen, die die Texteingabe unterstützen. Die Klasse enthält die folgenden Methoden:

• IsSoftInputShowing, um festzustellen, ob das Gerät derzeit die Bildschirmtastatur anzeigt.
• HideSoftInputAsync, wodurch versucht wird, die Soft-Eingabe-Tastatur auszublenden, wenn sie gerade angezeigt wird.
• ShowSoftInputAsync, wodurch versucht wird, die Soft-Eingabe-Tastatur einzublenden, wenn sie derzeit verborgen ist.

Das folgende Beispiel zeigt, wie man die Bildschirmtastatur auf einem SearchBar mit dem Namen searchBar ausblendet, wenn sie gerade angezeigt wird:

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