Controle deslizante

A interface do usuário do aplicativo multiplataforma .NET (.NET MAUI) Slider é uma barra horizontal que você pode manipular para selecionar um valor de um double intervalo contínuo.

Slider define as propriedades a seguir:

• Minimum, do tipo double, é o mínimo do intervalo, com um valor padrão de 0.
• Maximum, do tipo double, é o máximo do intervalo, com um valor padrão de 1.
• Value, do tipo double, é o valor do controle deslizante, que pode variar entre Minimum e e Maximum tem um valor padrão de 0.
• MinimumTrackColor, do tipo Color, é a cor da barra no lado esquerdo do polegar.
• MaximumTrackColor, do tipo Color, é a cor da barra no lado direito do polegar.
• ThumbColor do tipo Color, é a cor do polegar.
• ThumbImageSource, do tipo , é a imagem a ser usada para o polegar, do tipo ImageSourceImageSource.
• DragStartedCommand, do tipo ICommand, que é executado no início de uma ação de arrastar.
• DragCompletedCommand, do tipo ICommand, que é executado no final de uma ação de arrastar.

Essas propriedades são apoiadas por BindableProperty objetos. A Value propriedade tem um modo de associação padrão de , o que significa que ela é adequada como uma fonte de BindingMode.TwoWayvinculação em um aplicativo que usa o padrão MVVM (Model-View-ViewModel).

Observação

As ThumbColor propriedades e ThumbImageSource são mutuamente exclusivas. Se ambas as propriedades estiverem definidas, a ThumbImageSource propriedade terá precedência.

O Slider coage o Value imóvel para que ele fique entre Minimum e Maximum, inclusive. Se a propriedade for definida como um valor maior que a propriedade, a SliderMinimumValue propriedade será definida Value como Minimum. Da mesma forma, se Maximum for definido como um valor menor que Value, defina Slider a Value propriedade como Maximum. Internamente, a Slider garantia é menor que MinimumMaximum. Se Minimum ou Maximum alguma vez forem definidos de modo que Minimum não seja inferior a , uma exceção é levantada Maximum. Para obter mais informações sobre como definir as Minimum propriedades e Maximum , consulte Precauções.

Slider Define um ValueChanged evento que é gerado quando as Value alterações, por meio da manipulação do usuário do Slider ou quando o programa define a Value propriedade diretamente. Um ValueChanged evento também é gerado quando a Value propriedade é coagida conforme descrito no parágrafo anterior. O ValueChangedEventArgs objeto que acompanha o ValueChanged evento tem OldValue e NewValue propriedades, do tipo double. No momento em que o evento é gerado, o valor de NewValue é o mesmo que a Value propriedade do Slider objeto.

Slider também define DragStarted e eventos, que são gerados no início e DragCompleted no final da ação de arrastar. Ao contrário do evento, os eventos e DragCompleted só são gerados por meio da manipulação do usuário do .ValueChangedSliderDragStarted Quando o evento é acionado, o DragStartedDragStartedCommand, do tipo ICommand, é executado. Da mesma forma, quando o evento é acionado, o DragCompletedDragCompletedCommand, do tipo ICommand, é executado.

Aviso

Não use opções de layout horizontal irrestrito de Center, Startou End com Slider. Mantenha a configuração padrão HorizontalOptions de , e não use uma largura de FillAuto ao colocar Slider um Grid layout.

Criar um controle deslizante

O exemplo a seguir mostra como criar um Slider, com dois Label objetos:

<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"
                ValueChanged="OnSliderValueChanged" />
        <Label x:Name="displayLabel"
               Text="(uninitialized)"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
    </StackLayout>
</ContentPage>

Neste exemplo, o Slider é inicializado para ter uma Maximum propriedade de 360. O segundo Label exibe o texto "(não inicializado)" até que o seja manipulado, o que faz com que o Slider primeiro ValueChanged evento seja gerado.

O arquivo code-behind contém o manipulador para o ValueChanged evento:

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

O ValueChanged manipulador do usa a Valueslider propriedade do objeto para definir a propriedade do primeiro Label e usa o String.Format método com a propriedade dos argumentos de evento para definir a TextRotationNewValue propriedade do Slider segundo:Label

Também é possível que o manipulador de eventos obtenha o que está disparando o Slider evento por meio do sender argumento. A Value propriedade contém o valor atual:

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

Se o Slider objeto recebeu um nome no arquivo XAML com um x:Name atributo (por exemplo, "slider"), o manipulador de eventos poderia fazer referência a esse objeto diretamente:

double value = slider.Value;

O código C# equivalente para criar um 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);
};

Os dados vinculam um controle deslizante

O ValueChanged manipulador de eventos pode ser eliminado usando a vinculação de dados para responder à alteração de Slider valor:

<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 Source={x:Reference slider},
                                  Path=Value}"
               FontSize="18"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
        <Slider x:Name="slider"
                Maximum="360" />
        <Label x:Name="displayLabel"
               Text="{Binding Source={x:Reference slider},
                              Path=Value,
                              StringFormat='The Slider value is {0:F0}'}"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
    </StackLayout>
</ContentPage>

Neste exemplo, a Rotation propriedade do primeiro Label está vinculada à Value propriedade do , assim como a Text propriedade do Slidersegundo Label com uma StringFormat especificação. Quando a página aparece pela primeira vez, a segunda Label exibe a cadeia de texto com o valor. Para exibir texto sem associação de dados, você precisaria inicializar especificamente a Text propriedade do ou simular um disparo do ValueChanged evento chamando o manipulador de eventos do construtor de Label classe.

Precauções

O valor do imóvel deve ser sempre menor que o valor do MinimumMaximum imóvel. O exemplo a seguir faz com que o Slider gere uma exceção:

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

O compilador C# gera código que define essas duas propriedades em sequência e, quando a Minimum propriedade é definida como 10, ela é maior que o valor padrão Maximum de 1. Você pode evitar a exceção nesse caso definindo a Maximum propriedade primeiro:

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

Neste exemplo, definir Maximum como 20 não é um problema porque é maior que o valor padrão Minimum de 0. Quando Minimum é definido, o valor é menor que o Maximum valor de 20.

O mesmo problema existe em XAML. As propriedades devem ser definidas em uma ordem que garanta que seja sempre maior que MaximumMinimum:

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

Você pode definir os Minimum valores e Maximum para números negativos, mas somente em uma ordem em que Minimum é sempre menor que Maximum:

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

A Value propriedade é sempre maior ou igual ao Minimum valor e menor ou igual a Maximum. Se Value for definido como um valor fora desse intervalo, o valor será coagido a ficar dentro do intervalo, mas nenhuma exceção será gerada. Por exemplo, o exemplo a seguir não gerará uma exceção:

Slider slider = new Slider
{
    Value = 10
};

Em vez disso, a Value propriedade é coagida ao Maximum valor de 1.

Um exemplo anterior definido Maximum como 20 e Minimum 10:

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

Quando Minimum é definido como 10, em seguida Value , também é definido como 10.

Se um ValueChanged manipulador de eventos tiver sido anexado no momento em que a propriedade for coagida a Value algo diferente de seu valor padrão de 0, um ValueChanged evento será gerado:

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

Quando Minimum é definido como 10, também é definido como 10, Value e o ValueChanged evento é gerado. Isso pode ocorrer antes que o restante da página tenha sido construído, e o manipulador pode tentar fazer referência a outros elementos na página que ainda não foram criados. Talvez você queira adicionar algum código ao ValueChanged manipulador que verifica null valores de outros elementos na página. Ou, você pode definir o ValueChanged manipulador de eventos depois que os Slider valores foram inicializados.