Xamarin.Forms Deslizante
Use um Stepper para selecionar um valor numérico de um intervalo de valores.
O Xamarin.FormsStepper
consiste em dois botões rotulados com sinais de menos e mais. Esses botões podem ser manipulados pelo usuário para selecionar incrementalmente um double
valor de um intervalo de valores.
O Stepper
define quatro propriedades do tipo double
:
Increment
é a quantidade pela qual alterar o valor selecionado, com um valor padrão de 1.Minimum
é o mínimo do intervalo, com um valor padrão de 0.Maximum
é o máximo do intervalo, com um valor padrão de 100.Value
é o valor do stepper, que pode variar entreMinimum
eMaximum
e tem um valor padrão de 0.
Todas essas propriedades são apoiadas por BindableProperty
objetos. A Value
propriedade tem um modo de vinculação padrão de BindingMode.TwoWay
, o que significa que ela é adequada como uma fonte de vinculação em um aplicativo que usa a arquitetura MVVM (Model-View-ViewModel).
Aviso
Internamente, a Stepper
garantia é menor que Minimum
Maximum
. 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 propriedades e Maximum
, consulte a Minimum
seção Precauções.
O Stepper
coage o Value
imóvel para que ele fique entre Minimum
e Maximum
, inclusive. Se a Minimum
propriedade for definida como um valor maior que a Value
propriedade, a Stepper
propriedade será definida Value
como Minimum
. Da mesma forma, se Maximum
for definido como um valor menor que Value
, defina Stepper
a Value
propriedade como Maximum
.
Stepper
Define um ValueChanged
evento que é acionado quando as Value
alterações, por meio da manipulação do Stepper
usuário do ou quando o aplicativo define a Value
propriedade diretamente. Um ValueChanged
evento também é disparado quando a Value
propriedade é coagida conforme descrito no parágrafo anterior.
O ValueChangedEventArgs
objeto que acompanha o ValueChanged
evento tem duas propriedades, ambas do tipo double
: OldValue
e NewValue
. No momento em que o evento é acionado, o valor de NewValue
é o mesmo que a Value
propriedade do Stepper
objeto.
Código e marcação básicos do Stepper
O exemplo contém três páginas que são funcionalmente idênticas, mas são implementadas de maneiras diferentes. A primeira página usa apenas código C#, a segunda usa XAML com um manipulador de eventos no código e a terceira é capaz de evitar o manipulador de eventos usando a vinculação de dados no arquivo XAML.
Criando um Stepper no código
A página Basic Stepper Code no exemplo mostra como criar um Stepper
e dois Label
objetos no código:
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 }
};
}
}
O Stepper
é inicializado para ter uma Maximum
propriedade de 360 e uma Increment
propriedade de 30. A manipulação altera Stepper
o valor selecionado incrementalmente entre Minimum
para Maximum
com base no valor da Increment
propriedade. O ValueChanged
manipulador do Stepper
usa a stepper
Value
propriedade do objeto para definir a Rotation
propriedade do primeiro Label
e usa o string.Format
método com a NewValue
propriedade dos argumentos de evento para definir a Text
propriedade do segundo Label
. Essas duas abordagens para obter o valor atual do Stepper
são intercambiáveis.
As capturas de tela a seguir mostram a página Basic Stepper Code :
O segundo Label
exibe o texto "(não inicializado)" até que o seja manipulado, o Stepper
que faz com que o primeiro ValueChanged
evento seja disparado.
Criando um Stepper em XAML
A página XAML do Stepper Básico é funcionalmente igual ao Basic Stepper Code, mas implementada principalmente em 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>
O arquivo code-behind contém o manipulador para o ValueChanged
evento:
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);
}
}
Também é possível que o manipulador de eventos obtenha o Stepper
que está disparando o evento por meio do sender
argumento. A Value
propriedade contém o valor atual:
double value = ((Stepper)sender).Value;
Se o Stepper
objeto recebeu um nome no arquivo XAML com um x:Name
atributo (por exemplo, "stepper"), o manipulador de eventos poderia fazer referência a esse objeto diretamente:
double value = stepper.Value;
Vinculação de dados ao Stepper
A página Basic Stepper Bindings mostra como escrever um aplicativo quase equivalente que elimina o manipulador de eventos usando a Value
Vinculação de Dados:
<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>
A Rotation
propriedade do primeiro Label
está vinculada à Value
propriedade do Stepper
, assim como a Text
propriedade do segundo Label
com uma StringFormat
especificação. A página Basic Stepper Bindings funciona de forma um pouco diferente das duas páginas anteriores: quando a página aparece pela primeira vez, a segunda Label
exibe a cadeia de texto com o valor. Esse é um benefício do uso da vinculação de dados. Para exibir texto sem associação de dados, você precisaria inicializar especificamente a Text
propriedade do Label
ou simular um disparo do ValueChanged
evento chamando o manipulador de eventos do construtor de classe.
Precauções
O valor do Minimum
imóvel deve ser sempre menor que o valor do Maximum
imóvel. O trecho de código a seguir faz com que o Stepper
gere uma exceção:
// Throws an exception!
Stepper stepper = new Stepper
{
Minimum = 180,
Maximum = 360
};
O compilador C# gera código que define essas duas propriedades em sequência e, quando a Minimum
propriedade é definida como 180, ela é maior que o valor padrão Maximum
de 100. Você pode evitar a exceção nesse caso definindo a Maximum
propriedade primeiro:
Stepper stepper = new Stepper
{
Maximum = 360,
Minimum = 180
};
Definir Maximum
como 360 não é um problema porque é maior do que o valor padrão Minimum
de 0. Quando Minimum
é definido, o valor é menor que o Maximum
valor de 360.
O mesmo problema existe em XAML. Defina as propriedades em uma ordem que garanta que Maximum
seja sempre maior que Minimum
:
<Stepper Maximum="360"
Minimum="180" ... />
Você pode definir os Minimum
valores e Maximum
para números negativos, mas somente em uma ordem em que Minimum
é sempre menor que Maximum
:
<Stepper Minimum="-360"
Maximum="-180" ... />
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, esse código não gerará uma exceção:
Stepper stepper = new Stepper
{
Value = 180
};
Em vez disso, a Value
propriedade é coagida ao Maximum
valor de 100.
Aqui está um trecho de código mostrado acima:
Stepper stepper = new Stepper
{
Maximum = 360,
Minimum = 180
};
Quando Minimum
é definido como 180, então Value
também é definido como 180.
Se um ValueChanged
manipulador de eventos tiver sido anexado no momento em que a Value
propriedade for coagida a algo diferente de seu valor padrão de 0, um ValueChanged
evento será acionado. Aqui está um trecho de XAML:
<Stepper ValueChanged="OnStepperValueChanged"
Maximum="360"
Minimum="180" />
Quando Minimum
é definido como 180, Value
também é definido como 180, e o ValueChanged
evento é disparado. 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 Stepper
valores foram inicializados.