Xamarin.Forms Stepper

Article
07/13/2023

Utilisez un pas à pas pour sélectionner une valeur numérique à partir d’une plage de valeurs.

Le Xamarin.FormsStepper se compose de deux boutons étiquetés avec des signes moins et plus. Ces boutons peuvent être manipulés par l’utilisateur pour sélectionner de manière incrémentielle une double valeur à partir d’une plage de valeurs.

Définit Stepper quatre propriétés de type double:

Increment est la quantité par laquelle modifier la valeur sélectionnée par, avec une valeur par défaut de 1.
Minimum est le minimum de la plage, avec une valeur par défaut de 0.
Maximum est la valeur maximale de la plage, avec une valeur par défaut de 100.
Value est la valeur du pas à pas, qui peut être comprise entre Minimum et Maximum et a une valeur par défaut de 0.

Toutes ces propriétés sont soutenues par BindableProperty des objets . La Value propriété a un mode de liaison par défaut de BindingMode.TwoWay, ce qui signifie qu’elle convient en tant que source de liaison dans une application qui utilise l’architecture Model-View-ViewModel (MVVM).

Avertissement

En interne, le Stepper garantit que Minimum est inférieur à Maximum. Si Minimum ou Maximum sont jamais définis de sorte que Minimum n’ait pas la Maximumvaleur inférieure à , une exception est levée. Pour plus d’informations sur la définition des propriétés et Maximum , consultez la Minimum section Précautions.

force Stepper la Value propriété afin qu’elle soit comprise entre Minimum et Maximum, inclusive. Si la Minimum propriété est définie sur une valeur supérieure à la Value propriété , définit Stepper la Value propriété sur Minimum. De même, si Maximum est défini sur une valeur inférieure Valueà , Stepper affecte à Maximumla propriété la Value valeur .

Stepper définit un ValueChanged événement qui est déclenché lorsque le Value change, soit par manipulation par l’utilisateur de ou Stepper lorsque l’application définit directement la Value propriété. Un ValueChanged événement est également déclenché lorsque la Value propriété est sous la force, comme décrit dans le paragraphe précédent.

L’objet ValueChangedEventArgs qui accompagne l’événement ValueChanged a deux propriétés, de type doubleet OldValueNewValue. Au moment où l’événement est déclenché, la valeur de NewValue est identique à la Value propriété de l’objet Stepper .

Code et balisage stepper de base

L’exemple StepperDemos contient trois pages qui sont fonctionnellement identiques, mais qui sont implémentées de différentes manières. La première page utilise uniquement du code C#, la seconde utilise XAML avec un gestionnaire d’événements dans le code, et la troisième est en mesure d’éviter le gestionnaire d’événements à l’aide de la liaison de données dans le fichier XAML.

Création d’une stepper dans le code

La page Code pas à pas de base de l’exemple StepperDemos montre comment créer un Stepper et deux Label objets dans le code :

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

Le Stepper est initialisé pour avoir une Maximum propriété de 360 et une Increment propriété de 30. La manipulation de modifie Stepper la valeur sélectionnée de façon incrémentielle entre Minimum en Maximum en fonction de la valeur de la Increment propriété . Le ValueChanged gestionnaire de utilise Stepper la Value propriété de l’objet stepper pour définir la Rotation propriété du premier Label et utilise la string.Format méthode avec la NewValue propriété des arguments d’événement pour définir la Text propriété du second Label. Ces deux approches pour obtenir la valeur actuelle de sont Stepper interchangeables.

Les captures d’écran suivantes montrent la page Code pas à pas de base :

La seconde Label affiche le texte « (non initialisé) » jusqu’à ce que le Stepper soit manipulé, ce qui provoque le déclenchement du premier ValueChanged événement.

Création d’une stepper en XAML

La page XAML stepper de base est fonctionnellement la même que le code stepper de base , mais implémentée principalement en XAML :

<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>

Le fichier code-behind contient le gestionnaire de l’événement ValueChanged :

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

Il est également possible pour le gestionnaire d’événements d’obtenir le Stepper qui déclenche l’événement via l’argument sender . La Value propriété contient la valeur actuelle :

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

Si un nom a été attribué à l’objet Stepper dans le fichier XAML avec un x:Name attribut (par exemple, « pas à pas »), le gestionnaire d’événements peut référencer cet objet directement :

double value = stepper.Value;

Liaison de données du stepper

La page Liaisons pas à pas de base montre comment écrire une application presque équivalente qui élimine le gestionnaire d’événements à l’aide de la Valueliaison de données :

<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>

La Rotation propriété du premier Label est liée à la Value propriété du Stepper, tout comme la Text propriété du second Label avec une StringFormat spécification. La page Liaisons pas à pas de base fonctionne un peu différemment des deux pages précédentes : lorsque la page apparaît pour la première fois, la deuxième Label affiche la chaîne de texte avec la valeur . Il s’agit d’un avantage de l’utilisation de la liaison de données. Pour afficher du texte sans liaison de données, vous devez initialiser spécifiquement la Text propriété du Label ou simuler un déclenchement de l’événement ValueChanged en appelant le gestionnaire d’événements à partir du constructeur de classe.

Précautions

La valeur de la Minimum propriété doit toujours être inférieure à la valeur de la Maximum propriété . L’extrait de code suivant provoque le Stepper déclenchement d’une exception :

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

Le compilateur C# génère du code qui définit ces deux propriétés dans l’ordre, et lorsque la propriété a la Minimum valeur 180, elle est supérieure à la valeur par défaut Maximum de 100. Vous pouvez éviter l’exception dans ce cas en définissant d’abord la Maximum propriété :

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

La définition Maximum de la valeur 360 n’est pas un problème, car elle est supérieure à la valeur par défaut Minimum de 0. Quand Minimum est défini, la valeur est inférieure à la Maximum valeur de 360.

Le même problème existe en XAML. Définissez les propriétés dans un ordre qui garantit que Maximum est toujours supérieur à Minimum:

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

Vous pouvez définir les Minimum valeurs et Maximum sur des nombres Maximumnégatifs, mais uniquement dans un ordre où Minimum est toujours inférieur à :

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

La Value propriété est toujours supérieure ou égale à la Minimum valeur et inférieure ou égale à Maximum. Si Value est défini sur une valeur en dehors de cette plage, la valeur est alors de force pour se trouver à l’intérieur de la plage, mais aucune exception n’est levée. Par exemple, ce code ne lève pas d’exception :

Stepper stepper = new Stepper
{
    Value = 180
};

Au lieu de cela, la Value propriété est convertie de force à la Maximum valeur 100.

Voici un extrait de code ci-dessus :

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

Quand Minimum est défini sur 180, est Value également défini sur 180.

Si un ValueChanged gestionnaire d’événements a été attaché au moment où la Value propriété est liée à quelque chose d’autre que sa valeur par défaut de 0, un ValueChanged événement est déclenché. Voici un extrait de code XAML :

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

Quand Minimum est défini sur 180, Value est également défini sur 180 et l’événement ValueChanged est déclenché. Cela peut se produire avant la construction du reste de la page, et le gestionnaire peut tenter de référencer d’autres éléments de la page qui n’ont pas encore été créés. Vous souhaiterez peut-être ajouter du code au ValueChanged gestionnaire qui recherche null les valeurs d’autres éléments sur la page. Vous pouvez également définir le gestionnaire d’événements ValueChanged une fois les Stepper valeurs initialisées.