Schieberegler

Die .NET Multi-Platform App UI (.NET MAUI) Slider ist eine horizontale Leiste, die Sie bearbeiten können, um einen Wert aus einem double fortlaufenden Bereich auszuwählen.

Slider definiert die folgenden Eigenschaften:

• Minimum, vom Typ double, ist das Minimum des Bereichs mit dem Standardwert 0.
• Maximum, vom Typ double, ist das Maximum des Bereichs, wobei der Standardwert 1 ist.
• Valueist der doubleWert des Schiebereglers, der zwischen Minimum und Maximum dem Standardwert 0 liegen kann.
• MinimumTrackColor, vom Typ Color, ist die Balkenfarbe auf der linken Seite des Daumens.
• MaximumTrackColor, vom Typ Color, ist die Balkenfarbe auf der rechten Seite des Daumens.
• ThumbColor vom Typ Color stellt die Daumenfarbe dar.
• ThumbImageSource, vom Typ ImageSource, ist das Bild, das für den Daumen vom Typ ImageSourceverwendet werden soll.
• DragStartedCommand, vom Typ ICommand, der am Anfang einer Ziehaktion ausgeführt wird.
• DragCompletedCommand, vom Typ ICommand, der am Ende einer Ziehaktion ausgeführt wird.

Diese Eigenschaften werden von BindableProperty Objekten unterstützt. Die Value Eigenschaft verfügt über einen Standardbindungsmodus von BindingMode.TwoWay, was bedeutet, dass sie als Bindungsquelle in einer Anwendung geeignet ist, die das Model-View-ViewModel (MVVM)-Muster verwendet.

Die Slider zwingt die Value-Eigenschaft, sodass sie zwischen Minimum und Maximum, einschließlich, liegt. Wenn die Minimum Eigenschaft auf einen Wert festgelegt ist, der größer als die Value Eigenschaft ist, wird die SliderValue Eigenschaft auf Minimum festgelegt. Entsprechend, wenn Maximum auf einen Wert kleiner als Value gesetzt ist, dann setzt Slider die Eigenschaft Value auf Maximum. Intern wird durch Slider sichergestellt, dass Minimum kleiner als Maximum ist. Wenn Minimum oder Maximum jemals so festgelegt werden, dass Minimum nicht kleiner als Maximum ist, wird eine Ausnahme ausgelöst. Weitere Informationen zum Festlegen der Eigenschaften Minimum und Maximum finden Sie unter Vorsichtsmaßnahmen.

Slider definiert ein ValueChanged-Ereignis, das beim Value-Ändern ausgelöst wird, entweder durch die Benutzermanipulation des Slider oder wenn das Programm die Value-Eigenschaft direkt festlegt. Ein ValueChanged Ereignis wird auch ausgelöst, wenn die Value Eigenschaft, wie im vorherigen Absatz beschrieben, zwangsweise angewendet wird. Das ValueChangedEventArgs Objekt, das das ValueChanged Ereignis begleitet, hat OldValue und NewValue Eigenschaften vom Typ double. Beim Auslösen des Ereignisses entspricht der Wert NewValue der Value Eigenschaft des Slider Objekts.

Slider definiert DragStarted und DragCompleted Ereignisse, die am Anfang und Ende der Ziehaktion ausgelöst werden. Im Gegensatz zu dem ValueChanged-Ereignis werden die DragStarted- und DragCompleted-Ereignisse nur durch die Benutzermanipulation der Slider ausgelöst. Wenn das DragStarted Ereignis ausgelöst wird, wird DragStartedCommand, vom Typ ICommand, ausgeführt. Wenn das DragCompleted Ereignis ausgelöst wird, wird der DragCompletedCommand, vom Typ ICommand, ausgeführt.

Schieberegler erstellen

Das folgende Beispiel zeigt, wie Sie ein Slider, mit zwei Label Objekten erstellen:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="SliderDemos.BasicSliderXamlPage"
             Title="Basic Slider XAML"
             Padding="10, 0">
    <StackLayout>
        <Label x:Name="rotatingLabel"
               Text="ROTATING TEXT"
               FontSize="18"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
        <Slider Maximum="360"
                SemanticProperties.Description="Rotation angle"
                ValueChanged="OnSliderValueChanged" />
        <Label x:Name="displayLabel"
               Text="(uninitialized)"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
    </StackLayout>
</ContentPage>

In diesem Beispiel ist die Slider so initialisiert, dass sie eine Maximum Eigenschaft von 360 hat. Im zweiten Label wird der Text "(nicht initialisiert)" angezeigt, bis die Slider Manipulation erfolgt, wodurch das erste ValueChanged Ereignis ausgelöst wird.

Die CodeBehind-Datei enthält den Handler für das ValueChanged Ereignis:

public partial class BasicSliderXamlPage : ContentPage
{
    public BasicSliderXamlPage()
    {
        InitializeComponent();
    }

    void OnSliderValueChanged(object sender, ValueChangedEventArgs args)
    {
        double value = args.NewValue;
        rotatingLabel.Rotation = value;
        displayLabel.Text = String.Format("The Slider value is {0}", value);
    }
}

Der ValueChanged Handler der Slider Objekt verwendet die Value Eigenschaft des slider Objekts, um die Rotation Eigenschaft des ersten Label festzulegen, und verwendet die String.Format Methode mit der NewValue Eigenschaft der Ereignisargumente, um die Text Eigenschaft der zweiten Labelfestzulegen:

Es ist auch möglich, dass der Ereignishandler das Slider, das das Ereignis auslöst, über das sender Argument erhält. Die Value Eigenschaft enthält den aktuellen Wert:

double value = ((Slider)sender).Value;

Wenn dem Slider Objekt in der XAML-Datei ein Name mit einem x:Name Attribut (z. B. "slider") gegeben wurde, kann der Ereignishandler direkt auf dieses Objekt verweisen:

double value = slider.Value;

Der entsprechende C#-Code zum Erstellen einer Slider Datei lautet:

Slider slider = new Slider
{
    Maximum = 360
};
slider.ValueChanged += (sender, args) =>
{
    rotationLabel.Rotation = slider.Value;
    displayLabel.Text = String.Format("The Slider value is {0}", args.NewValue);
};

Datenbindung eines Schiebereglers

Der ValueChanged Ereignishandler kann mithilfe der Datenbindung eliminiert werden, um auf die Änderung des Slider Werts zu reagieren:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="SliderDemos.BasicSliderBindingsPage"
             Title="Basic Slider Bindings"
             Padding="10, 0">
    <StackLayout>
        <Label Text="ROTATING TEXT"
               Rotation="{Binding x:DataType='Slider',
                                  Source={x:Reference slider},
                                  Path=Value}"
               FontSize="18"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
        <Slider x:Name="slider"
                Maximum="360" />
        <Label x:Name="displayLabel"
               Text="{Binding x:DataType='Slider',
                              Source={x:Reference slider},
                              Path=Value,
                              StringFormat='The Slider value is {0:F0}'}"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
    </StackLayout>
</ContentPage>

In diesem Beispiel ist die Rotation Eigenschaft der ersten Label an die Value Eigenschaft der Slider, wie die Text Eigenschaft des zweiten Label mit einer StringFormat Spezifikation gebunden ist. Wenn die Seite zum ersten Mal angezeigt wird, zeigt die zweite Label die Textzeichenfolge mit dem Wert an. Um Text ohne Datenbindung anzuzeigen, müssen Sie die Text Eigenschaft des Label Objekts explizit initialisieren oder das Auslösen des ValueChanged Ereignisses simulieren, indem Sie den Ereignishandler aus dem Klassenkonstruktor aufrufen.

Vorsichtsmaßnahmen

Der Wert der Minimum Eigenschaft muss immer kleiner als der Wert der Maximum Eigenschaft sein. Das folgende Beispiel verursacht, dass Slider eine Ausnahme auslöst:

// Throws an exception!
Slider slider = new Slider
{
    Minimum = 10,
    Maximum = 20
};

Der C#-Compiler generiert Code, der diese beiden Eigenschaften in Sequenz festlegt, und wenn die Minimum Eigenschaft auf 10 festgelegt ist, ist sie größer als der Standardwert Maximum von 1. Sie können die Ausnahme in diesem Fall vermeiden, indem Sie die Maximum Eigenschaft zuerst festlegen:

Slider slider = new Slider
{
    Maximum = 20,
    Minimum = 10
};

In diesem Beispiel ist die Einstellung Maximum auf 20 kein Problem, da sie größer als der Standardwert Minimum 0 ist. Wenn Minimum festgelegt ist, ist der Wert kleiner als der von Maximum festgelegte Wert von 20.

Dasselbe Problem besteht in XAML. Die Eigenschaften müssen in einer Reihenfolge festgelegt werden, die sicherstellt, dass dies Maximum immer größer ist als Minimum:

<Slider Maximum="20"
        Minimum="10" ... />

Sie können die Minimum und Maximum Werte auf negative Zahlen festlegen, jedoch nur in einer Anordnung, in der Minimum immer kleiner als Maximum ist.

<Slider Minimum="-20"
        Maximum="-10" ... />

Die Value Eigenschaft ist immer größer oder gleich dem Minimum Wert und kleiner als oder gleich Maximum. Wenn Value auf einen Wert außerhalb dieses Bereichs festgelegt ist, wird der Wert erzwungen, innerhalb des Bereichs zu liegen, aber es wird keine Ausnahme ausgelöst. Im folgenden Beispiel wird beispielsweise keine Ausnahme ausgelöst:

Slider slider = new Slider
{
    Value = 10
};

Stattdessen wird die Value Eigenschaft auf den Maximum Wert 1 festgelegt.

Ein vorheriges Beispiel setzte Maximum auf 20 und Minimum auf 10.

Slider slider = new Slider
{
    Maximum = 20,
    Minimum = 10
};

Wenn Minimum auf 10 gesetzt ist, wird Value ebenfalls auf 10 gesetzt.

Wenn ein ValueChanged Ereignishandler zum Zeitpunkt, zu dem die Value Eigenschaft an einen anderen Wert als den Standardwert 0 umgewandelt wird, angefügt wurde, wird ein ValueChanged Ereignis ausgelöst:

<Slider ValueChanged="OnSliderValueChanged"
        Maximum="20"
        Minimum="10" />

Wenn Minimum auf 10 gesetzt wird, wird Value ebenfalls auf 10 gesetzt, und das ValueChanged Ereignis wird ausgelöst. Dies kann vorkommen, bevor der Rest der Seite erstellt wurde, und der Handler versucht möglicherweise, auf andere Elemente auf der Seite zu verweisen, die noch nicht erstellt wurden. Sie könnten Code zum ValueChanged-Handler hinzufügen, der null-Werte anderer Elemente auf der Seite überprüft. Alternativ können Sie den ValueChanged Ereignishandler festlegen, nachdem die Slider Werte initialisiert wurden.