Barra deslizante

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

Slider define as seguintes propriedades:

• 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 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 ImageSource, é a imagem a ser usada para o polegar, do tipo ImageSource.
• 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 arraste.

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

O Slider coagi a Value propriedade para que ela seja entre Minimum e Maximum, inclusive. Se a propriedade Minimum for definida como um valor maior que a propriedade Value, Slider definirá a propriedade Value como Minimum. Da mesma forma, se Maximum for definido como um valor menor que Value, então Slider , definirá a Value propriedade como Maximum. Internamente, Slider garante que Minimum seja menor que Maximum. Se Minimum ou Maximum estiverem definidos de modo que Minimum não seja menor que Maximum, uma exceção é levantada. Para obter mais informações sobre como definir as propriedades Minimum e Maximum, consulte Precauções.

Slider define um ValueChanged evento que é gerado quando o Value é alterado, seja por manipulação do usuário do Slider ou quando o programa define a propriedade Value 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 NewValue é o mesmo que a Value propriedade do Slider objeto.

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

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

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

O arquivo code-behind contém o manipulador do 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);
    }
}

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

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

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

Se o Slider objeto receber um nome no arquivo XAML com um x:Name atributo (por exemplo, "controle deslizante"), o manipulador de eventos poderá referenciar 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);
};

Associar dados a um controle deslizante

O ValueChanged manipulador de eventos pode ser eliminado usando a associação de dados para responder à alteração do 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 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>

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

Precauções

O valor da Minimum propriedade deve ser sempre menor que o valor da Maximum propriedade. No exemplo a seguir, a Slider gera 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, é maior que o valor padrão Maximum de 1. Nesse caso, você pode evitar a exceção 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 no XAML. As propriedades devem ser definidas em uma ordem que garanta que Maximum seja sempre maior que Minimum:

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

Você pode definir os valores Minimum e Maximum como números negativos, mas somente em uma ordem em que Minimum seja sempre menor que Maximum.

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

A Value propriedade é sempre maior ou igual ao Minimum valor e menor que 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, também Value é definido como 10.

Se um ValueChanged manipulador de eventos tiver sido anexado no momento em que a Value propriedade é coagida a 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, Value também é definido como 10 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 manipulador ValueChanged que verifica os valores null de outros elementos na página. Ou você pode definir o ValueChanged manipulador de eventos depois que os Slider valores forem inicializados.