Xamarin.Forms Stepper

Das Beispiel herunterladen

Verwenden Sie einen Stepper, um einen numerischen Wert aus einem Wertebereich auszuwählen.

Die Xamarin.FormsStepper besteht aus zwei Schaltflächen, die mit Minus- und Pluszeichen beschriftet sind. Diese Schaltflächen können vom Benutzer so bearbeitet werden, dass inkrementell ein double Wert aus einem Wertebereich ausgewählt wird.

Definiert Stepper vier Eigenschaften vom Typ double:

• Increment ist der Betrag, um den ausgewählten Wert mit dem Standardwert 1 zu ändern.
• Minimum ist das Minimum des Bereichs mit dem Standardwert 0.
• Maximum ist das Maximum des Bereichs mit einem Standardwert von 100.
• Value ist der Wert des Schritts, der zwischen Minimum und liegen Maximum kann und den Standardwert 0 aufweist.

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

Warnung

Intern stellt sicher Stepper , dass Minimum kleiner als Maximumist. Wenn Minimum oder Maximum jemals so festgelegt sind, dass Minimum nicht kleiner als Maximumist, wird eine Ausnahme ausgelöst. Weitere Informationen zum Festlegen der Minimum Eigenschaften und Maximum finden Sie im Abschnitt Vorsichtsmaßnahmen .

Die Stepper -Eigenschaft wird so geerzt Value , dass sie sich zwischen Minimum und Maximumbefindet. Wenn die Minimum -Eigenschaft auf einen Wert festgelegt ist, der größer als die Value -Eigenschaft ist, legt die Stepper - Value Eigenschaft auf Minimumfest. Wenn auf einen Wert kleiner Valueals festgelegt ist, Maximum legt die StepperValue -Eigenschaft auf Maximumfest.

Stepper definiert ein ValueChanged Ereignis, das ausgelöst wird, wenn sich die Value -Eigenschaft ändert, entweder durch Benutzerbearbeitung oder Stepper wenn die Anwendung die Value Eigenschaft direkt festlegt. Ein ValueChanged Ereignis wird auch ausgelöst, wenn die Value -Eigenschaft wie im vorherigen Absatz beschrieben zwangsgefälkt wird.

Das ValueChangedEventArgs -Objekt, das das ValueChanged Ereignis begleitet, verfügt über zwei Eigenschaften vom Typ double: OldValue und NewValue. Zum Zeitpunkt des Auslösens des Ereignisses ist der Wert von NewValue mit der Value -Eigenschaft des Stepper -Objekts identisch.

Einfacher Schrittcode und -Markup

Das StepperDemos-Beispiel enthält drei Seiten, die funktional identisch sind, aber auf unterschiedliche Weise implementiert werden. Die erste Seite verwendet nur C#-Code, die zweite verwendet XAML mit einem Ereignishandler im Code, und die dritte Seite kann den Ereignishandler mithilfe der Datenbindung in der XAML-Datei vermeiden.

Erstellen eines Schritts im Code

Auf der Seite "Basic Stepper Code" im StepperDemos-Beispiel wird gezeigt, wie Ein Stepper - und zwei Label Objekte im Code erstellt werden:

public class BasicStepperCodePage : ContentPage
{
    public BasicStepperCodePage()
    {
        Label rotationLabel = new Label
        {
            Text = "ROTATING TEXT",
            FontSize = Device.GetNamedSize(NamedSize.Large, typeof(Label)),
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.CenterAndExpand
        };

        Label displayLabel = new Label
        {
            Text = "(uninitialized)",
            HorizontalOptions = LayoutOptions.Center,
            VerticalOptions = LayoutOptions.CenterAndExpand
        };

        Stepper stepper = new Stepper
        {
            Maximum = 360,
            Increment = 30,
            HorizontalOptions = LayoutOptions.Center
        };
        stepper.ValueChanged += (sender, e) =>
        {
            rotationLabel.Rotation = stepper.Value;
            displayLabel.Text = string.Format("The Stepper value is {0}", e.NewValue);
        };

        Title = "Basic Stepper Code";
        Content = new StackLayout
        {
            Margin = new Thickness(20),
            Children = { rotationLabel, stepper, displayLabel }
        };
    }
}

Die Stepper wird initialisiert, um eine Maximum Eigenschaft von 360 und eine Increment Eigenschaft von 30 zu haben. Wenn Sie den Stepper wert ändern, ändert sich der ausgewählte Wert inkrementell zwischen Minimum zu Maximum basierend auf dem Wert der Increment -Eigenschaft. Der ValueChanged Handler des Stepper verwendet die Value -Eigenschaft des stepper -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 des zweiten Labelfestzulegen. Diese beiden Ansätze zum Abrufen des aktuellen Werts von Stepper sind austauschbar.

Die folgenden Screenshots zeigen die Seite "Basic Stepper Code" :

Die zweite Label zeigt den Text "(nicht initialisiert)" an, bis der Stepper geändert wird, wodurch das erste ValueChanged Ereignis ausgelöst wird.

Erstellen eines Schritts in XAML

Die SEITE Basic Stepper XAML ist funktional identisch mit Basic Stepper Code , wird jedoch hauptsächlich in XAML implementiert:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="StepperDemo.BasicStepperXAMLPage"
             Title="Basic Stepper XAML">
    <StackLayout Margin="20">
        <Label x:Name="_rotatingLabel"
               Text="ROTATING TEXT"
               FontSize="Large"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand" />
        <Stepper Maximum="360"
                 Increment="30"
                 HorizontalOptions="Center"
                 ValueChanged="OnStepperValueChanged" />
        <Label x:Name="_displayLabel"
               Text="(uninitialized)"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand" />        
    </StackLayout>
</ContentPage>

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

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

    void OnStepperValueChanged(object sender, ValueChangedEventArgs e)
    {
        double value = e.NewValue;
        _rotatingLabel.Rotation = value;
        _displayLabel.Text = string.Format("The Stepper value is {0}", value);
    }
}

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

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

Wenn dem Stepper Objekt in der XAML-Datei ein Name mit einem x:Name Attribut (z. B. "stepper") gegeben wurde, könnte der Ereignishandler direkt auf dieses Objekt verweisen:

double value = stepper.Value;

Datenbindung der Stepper

Auf der Seite Grundlegende Stepperbindungen wird gezeigt, wie sie eine nahezu gleichwertige Anwendung schreiben, die den Value Ereignishandler mithilfe der Datenbindung eliminiert:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="StepperDemo.BasicStepperBindingsPage"
             Title="Basic Stepper Bindings">
    <StackLayout Margin="20">
        <Label Text="ROTATING TEXT"
               Rotation="{Binding Source={x:Reference _stepper}, Path=Value}"
               FontSize="Large"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand" />
        <Stepper x:Name="_stepper"
                 Maximum="360"
                 Increment="30"
                 HorizontalOptions="Center" />
        <Label Text="{Binding Source={x:Reference _stepper}, Path=Value, StringFormat='The Stepper value is {0:F0}'}"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand" />
    </StackLayout>
</ContentPage>

Die Rotation Eigenschaft des ersten Label ist an die Value -Eigenschaft von Steppergebunden, ebenso wie die Text Eigenschaft der zweiten Label mit einer StringFormat Spezifikation. Die Seite Basic Stepper Bindings funktioniert etwas anders als die beiden vorherigen Seiten: Wenn die Seite zuerst angezeigt wird, zeigt die zweite Label die Textzeichenfolge mit dem Wert an. Dies ist ein Vorteil der Verwendung der Datenbindung. Um Text ohne Datenbindung anzuzeigen, müssen Sie die Text Eigenschaft des Label -Ereignisses speziell initialisieren oder ein Auslösen des ValueChanged Ereignisses simulieren, indem Sie den Ereignishandler vom Klassenkonstruktor aufrufen.

Vorsichtsmaßnahmen

Der Wert der Minimum -Eigenschaft muss immer kleiner als der Wert der Maximum -Eigenschaft sein. Der folgende Codeausschnitt bewirkt, dass eine Stepper Ausnahme ausgelöst wird:

// Throws an exception!
Stepper stepper = new Stepper
{
    Minimum = 180,
    Maximum = 360
};

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

Stepper stepper = new Stepper
{
    Maximum = 360,
    Minimum = 180
};

Die Einstellung Maximum auf 360 ist kein Problem, da sie größer als der Standardwert Minimum 0 ist. Wenn Minimum festgelegt ist, ist der Wert kleiner als der Maximum Wert 360.

Das gleiche Problem besteht in XAML. Legen Sie die Eigenschaften in einer Reihenfolge fest, die sicherstellt, dass Maximum immer größer als Minimumist:

<Stepper Maximum="360"
         Minimum="180" ... />

Sie können die Minimum Werte und Maximum auf negative Zahlen festlegen, jedoch nur in einer Reihenfolge, in der Minimum immer kleiner als Maximumist:

<Stepper Minimum="-360"
         Maximum="-180" ... />

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 so geced, dass er innerhalb des Bereichs liegt, aber es wird keine Ausnahme ausgelöst. Dieser Code löst beispielsweise keine Ausnahme aus:

Stepper stepper = new Stepper
{
    Value = 180
};

Stattdessen wird die Value Eigenschaft auf den Maximum Wert 100 geerct.

Hier ist ein oben gezeigter Codeausschnitt:

Stepper stepper = new Stepper
{
    Maximum = 360,
    Minimum = 180
};

Wenn Minimum auf 180 festgelegt ist, wird auch Value auf 180 festgelegt.

Wenn ein ValueChanged Ereignishandler zu dem Zeitpunkt angefügt wurde, zu dem die Value Eigenschaft an etwas anderes als den Standardwert 0 gebunden ist, wird ein ValueChanged Ereignis ausgelöst. Hier ist ein Codeausschnitt von XAML:

<Stepper ValueChanged="OnStepperValueChanged"
         Maximum="360"
         Minimum="180" />

Wenn Minimum auf 180 festgelegt ist, Value wird auch auf 180 festgelegt, 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. Möglicherweise möchten Sie dem Handler code hinzufügen, der ValueChanged nach Werten anderer Elemente auf der Seite sucht null . Alternativ können Sie den ValueChanged Ereignishandler festlegen, nachdem die Stepper Werte initialisiert wurden.

Ähnliche Themen

• Beispiel für Stepper-Demos
• Schritt-API