Cursore

L'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) Slider è una barra orizzontale che è possibile modificare per selezionare un double valore da un intervallo continuo.

Slider definisce le proprietà seguenti:

• Minimum, di tipo double, è il minimo dell'intervallo, con un valore predefinito pari a 0.
• Maximum, di tipo double, è il valore massimo dell'intervallo, con un valore predefinito pari a 1.
• Value, di tipo double, è il valore del dispositivo di scorrimento, che può variare tra Minimum e Maximum e ha un valore predefinito pari a 0.
• MinimumTrackColor, di tipo Color, è il colore della barra sul lato sinistro del pollice.
• MaximumTrackColor, di tipo Color, è il colore della barra sul lato destro del pollice.
• ThumbColor di tipo Color, è il colore del pollice.
• ThumbImageSource, di tipo ImageSource, è l'immagine da usare per il pollice, di tipo ImageSource.
• DragStartedCommand, di tipo ICommand, che viene eseguito all'inizio di un'azione di trascinamento.
• DragCompletedCommand, di tipo ICommand, che viene eseguito alla fine di un'azione di trascinamento.

Queste proprietà sono supportate da BindableProperty oggetti . La Value proprietà ha una modalità di associazione predefinita di BindingMode.TwoWay, il che significa che è adatto come origine di associazione in un'applicazione che usa il modello Model-View-ViewModel (MVVM).

Il Slider costringe la proprietà Value affinché sia compresa tra Minimum e Maximum, inclusi. Se la Minimum proprietà è impostata su un valore maggiore della Value proprietà , la SliderValue proprietà viene impostata su Minimum. Analogamente, se Maximum è impostato su un valore minore di Value, Slider la Value proprietà viene impostata su Maximum. Slider garantisce internamente che Minimum sia minore di Maximum. Se Minimum o Maximum sono mai impostati in modo che Minimum non sia minore di Maximum, viene generata un'eccezione. Per altre informazioni sull'impostazione delle Minimum proprietà e Maximum , vedere Precauzioni.

Slider definisce un ValueChanged evento che viene generato quando il Value cambia, sia tramite la modifica dell'oggetto Slider sia quando il programma imposta direttamente la proprietà Value. Un evento ValueChanged viene generato anche quando la proprietà Value viene coercita come descritto nel paragrafo precedente. L'oggetto ValueChangedEventArgs che accompagna l'evento ValueChanged ha OldValue proprietà e NewValue , di tipo double. Al momento della generazione dell'evento, il valore di NewValue è uguale alla Value proprietà dell'oggetto Slider .

Slider definisce anche gli eventi DragStarted e DragCompleted, che sono attivati all'inizio e alla fine dell'azione di trascinamento. A differenza dell'evento ValueChanged, gli eventi DragStarted e DragCompleted vengono generati solo tramite la manipolazione da parte dell'utente di Slider. Quando l'evento DragStarted viene generato, DragStartedCommand di tipo ICommand viene eseguito. Analogamente, quando viene generato l'evento DragCompleted, DragCompletedCommand di tipo ICommand, viene eseguito.

Creare un dispositivo di scorrimento

Nell'esempio seguente viene illustrato come creare un Slideroggetto con due Label oggetti :

<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 questo esempio, viene Slider inizializzato per avere una Maximum proprietà pari a 360. Il secondo Label visualizza il testo "(non inizializzato)" fino a quando l'oggetto Slider non viene modificato, il che provoca l'attivazione del primo evento ValueChanged.

Il file code-behind contiene il gestore per l'evento ValueChanged :

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

Il ValueChanged gestore dell'oggetto Slider utilizza la Value proprietà dell'oggetto slider per impostare la Rotation proprietà del primo Label e utilizza il String.Format metodo con la NewValue proprietà degli argomenti dell'evento per impostare la Text proprietà del secondo Labeloggetto :

È anche possibile che il gestore eventi ottenga il Slider che attiva l'evento tramite l'argomento sender. La Value proprietà contiene il valore corrente:

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

Se all'oggetto Slider è stato assegnato un nome nel file XAML con un x:Name attributo ,ad esempio "slider", il gestore eventi potrebbe fare riferimento direttamente a tale oggetto:

double value = slider.Value;

Il codice C# equivalente per la creazione di un Slider è:

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

Associare dati a un cursore

Il ValueChanged gestore eventi può essere eliminato usando il data binding per rispondere alla modifica del Slider valore:

<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 questo esempio, la Rotation proprietà del primo Label è associata alla Value proprietà di Slider, come è la Text proprietà del secondo Label con una StringFormat specifica. Quando viene visualizzata la prima pagina, la seconda Label visualizza la stringa di testo con il valore . Per visualizzare testo senza data binding, è necessario inizializzare in modo specifico la Text proprietà dell'oggetto Label o simulare una generazione dell'evento ValueChanged chiamando il gestore eventi dal costruttore della classe.

Precauzioni

Il valore della Minimum proprietà deve essere sempre minore del valore della Maximum proprietà. L'esempio seguente provoca un'eccezione nel componente Slider:

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

Il compilatore C# genera codice che imposta queste due proprietà in sequenza e quando la Minimum proprietà è impostata su 10, è maggiore del valore predefinito Maximum 1. È possibile evitare l'eccezione in questo caso impostando prima la Maximum proprietà :

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

In questo esempio l'impostazione Maximum su 20 non è un problema perché è maggiore del valore predefinito Minimum 0. Quando Minimum è impostato, il valore è minore del Maximum valore di 20.

Lo stesso problema esiste in XAML. Le proprietà devono essere impostate in un ordine che garantisce che Maximum sia sempre maggiore di Minimum:

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

È possibile impostare i Minimum valori e Maximum su numeri negativi, ma solo in un ordine in cui Minimum è sempre minore di Maximum:

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

La Value proprietà è sempre maggiore o uguale al Minimum valore e minore o uguale a Maximum. Se Value è impostato su un valore esterno a tale intervallo, il valore verrà costretto a trovarsi all'interno dell'intervallo, ma non viene generata alcuna eccezione. Ad esempio, l'esempio seguente non genera un'eccezione:

Slider slider = new Slider
{
    Value = 10
};

Invece, la proprietà Value è coercita al Maximum valore di 1.

In un esempio precedente, Maximum è stato impostato su 20 e Minimum su 10:

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

Quando Minimum è impostato su 10, Value viene impostato anche su 10.

Se un ValueChanged gestore eventi è stato associato al momento in cui la Value proprietà è associata a un valore diverso dal valore predefinito 0, viene generato un ValueChanged evento:

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

Quando Minimum è impostato su 10, Value viene impostato anche su 10 e viene generato l'evento ValueChanged . Questo problema può verificarsi prima che il resto della pagina sia stato costruito e il gestore potrebbe tentare di fare riferimento ad altri elementi nella pagina che non sono ancora stati creati. Potresti voler aggiungere del codice al gestore ValueChanged che controlla i valori degli altri elementi nella pagina. In alternativa, è possibile impostare il gestore eventi ValueChanged dopo l'inizializzazione dei valori Slider.