Xamarin.Forms CarrosselVer Dados
CarouselView
Inclui as seguintes propriedades que definem os dados a serem exibidos e sua aparência:
ItemsSource
, do tipoIEnumerable
, especifica a coleção de itens a serem exibidos e tem um valor padrão denull
.ItemTemplate
, do tipoDataTemplate
, especifica o modelo a ser aplicado a cada item na coleção de itens a serem exibidos.
Essas propriedades são apoiadas por BindableProperty
objetos, o que significa que as propriedades podem ser destinos de associações de dados.
Observação
CarouselView
Define uma ItemsUpdatingScrollMode
propriedade que representa o comportamento de rolagem do CarouselView
quando novos itens são adicionados a ela. Para obter mais informações sobre essa propriedade, consulte Controlar a posição de rolagem quando novos itens são adicionados.
CarouselView
Oferece suporte à virtualização de dados incrementais à medida que o usuário rola. Para obter mais informações, consulte Carregar dados incrementalmente.
Preencher um CarouselView com dados
A CarouselView
é preenchido com dados definindo sua ItemsSource
propriedade para qualquer coleção que implementa IEnumerable
o . Por padrão, CarouselView
exibe itens horizontalmente.
Importante
Se for necessário atualizar à medida que os CarouselView
itens são adicionados, removidos ou alterados na coleção subjacente, a coleção subjacente deve ser uma IEnumerable
coleção que envia notificações de alteração de propriedade, como ObservableCollection
.
CarouselView
pode ser preenchido com dados usando a vinculação de dados para vincular sua ItemsSource
propriedade a uma IEnumerable
coleção. Em XAML, isso é obtido com a Binding
extensão de marcação:
<CarouselView ItemsSource="{Binding Monkeys}" />
Este é o código C# equivalente:
CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
Neste exemplo, os ItemsSource
dados da propriedade se vinculam à Monkeys
propriedade do modelo de exibição conectado.
Observação
As associações compiladas podem ser habilitadas para melhorar o desempenho da vinculação de dados em Xamarin.Forms aplicativos. Para obter mais informações, confira Associações compiladas do Xamarin.Forms.
Para obter informações sobre como alterar a CarouselView
orientação, consulte Xamarin.Forms CarouselView Layout. Para obter informações sobre como definir a aparência de cada item no , consulte Definir a aparência do CarouselView
item. Para obter mais informações sobre vinculação de dados, consulte Xamarin.Forms Vinculação de dados.
Definir a aparência do item
A aparência de cada item no CarouselView
pode ser definida definindo a CarouselView.ItemTemplate
propriedade como um DataTemplate
:
<CarouselView ItemsSource="{Binding Monkeys}">
<CarouselView.ItemTemplate>
<DataTemplate>
<StackLayout>
<Frame HasShadow="True"
BorderColor="DarkGray"
CornerRadius="5"
Margin="20"
HeightRequest="300"
HorizontalOptions="Center"
VerticalOptions="CenterAndExpand">
<StackLayout>
<Label Text="{Binding Name}"
FontAttributes="Bold"
FontSize="Large"
HorizontalOptions="Center"
VerticalOptions="Center" />
<Image Source="{Binding ImageUrl}"
Aspect="AspectFill"
HeightRequest="150"
WidthRequest="150"
HorizontalOptions="Center" />
<Label Text="{Binding Location}"
HorizontalOptions="Center" />
<Label Text="{Binding Details}"
FontAttributes="Italic"
HorizontalOptions="Center"
MaxLines="5"
LineBreakMode="TailTruncation" />
</StackLayout>
</Frame>
</StackLayout>
</DataTemplate>
</CarouselView.ItemTemplate>
</CarouselView>
Este é o código C# equivalente:
CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
carouselView.ItemTemplate = new DataTemplate(() =>
{
Label nameLabel = new Label { ... };
nameLabel.SetBinding(Label.TextProperty, "Name");
Image image = new Image { ... };
image.SetBinding(Image.SourceProperty, "ImageUrl");
Label locationLabel = new Label { ... };
locationLabel.SetBinding(Label.TextProperty, "Location");
Label detailsLabel = new Label { ... };
detailsLabel.SetBinding(Label.TextProperty, "Details");
StackLayout stackLayout = new StackLayout
{
Children = { nameLabel, image, locationLabel, detailsLabel }
};
Frame frame = new Frame { ... };
StackLayout rootStackLayout = new StackLayout
{
Children = { frame }
};
return rootStackLayout;
});
Os elementos especificados no DataTemplate
definem a aparência de cada item no CarouselView
. No exemplo, o layout dentro do DataTemplate
é gerenciado por um StackLayout
, e os dados são exibidos com um Image
objeto e três Label
objetos, que se vinculam às propriedades da Monkey
classe:
public class Monkey
{
public string Name { get; set; }
public string Location { get; set; }
public string Details { get; set; }
public string ImageUrl { get; set; }
}
As capturas de tela a seguir mostram o resultado da modelagem de cada item:
Para obter mais informações sobre modelos de dados, consulte Xamarin.Forms Modelos de dados.
Escolher a aparência do item em tempo de execução
A aparência de cada item no pode ser escolhida em CarouselView
tempo de execução, com base no valor do item, definindo a CarouselView.ItemTemplate
propriedade como um DataTemplateSelector
objeto:
<ContentPage ...
xmlns:controls="clr-namespace:CarouselViewDemos.Controls"
x:Class="CarouselViewDemos.Views.HorizontalLayoutDataTemplateSelectorPage">
<ContentPage.Resources>
<DataTemplate x:Key="AmericanMonkeyTemplate">
...
</DataTemplate>
<DataTemplate x:Key="OtherMonkeyTemplate">
...
</DataTemplate>
<controls:MonkeyDataTemplateSelector x:Key="MonkeySelector"
AmericanMonkey="{StaticResource AmericanMonkeyTemplate}"
OtherMonkey="{StaticResource OtherMonkeyTemplate}" />
</ContentPage.Resources>
<CarouselView ItemsSource="{Binding Monkeys}"
ItemTemplate="{StaticResource MonkeySelector}" />
</ContentPage>
Este é o código C# equivalente:
CarouselView carouselView = new CarouselView
{
ItemTemplate = new MonkeyDataTemplateSelector { ... }
};
carouselView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
A ItemTemplate
propriedade é definida como um MonkeyDataTemplateSelector
objeto. O exemplo a seguir mostra a classe MonkeyDataTemplateSelector
:
public class MonkeyDataTemplateSelector : DataTemplateSelector
{
public DataTemplate AmericanMonkey { get; set; }
public DataTemplate OtherMonkey { get; set; }
protected override DataTemplate OnSelectTemplate(object item, BindableObject container)
{
return ((Monkey)item).Location.Contains("America") ? AmericanMonkey : OtherMonkey;
}
}
A classe MonkeyDataTemplateSelector
define as propriedades AmericanMonkey
e OtherMonkey
do DataTemplate
como modelos de dados diferentes. A OnSelectTemplate
substituição retorna o AmericanMonkey
modelo quando o nome do macaco contém "América". Quando o nome do macaco não contém "América", a OnSelectTemplate
substituição retorna o OtherMonkey
modelo, que exibe seus dados esmaecidos:
Para obter mais informações sobre seletores de modelo de dados, consulte Criar um Xamarin.Forms DataTemplateSelector.
Importante
Ao usar CarouselView
o , nunca defina o elemento raiz de seus DataTemplate
objetos como um ViewCell
arquivo . Isso resultará em uma exceção sendo lançada porque CarouselView
não tem conceito de células.
exibir indicadores
Os indicadores, que representam o número de itens e a posição atual em um CarouselView
, podem ser exibidos ao lado do CarouselView
. Isso pode ser realizado com o IndicatorView
controle:
<StackLayout>
<CarouselView ItemsSource="{Binding Monkeys}"
IndicatorView="indicatorView">
<CarouselView.ItemTemplate>
<!-- DataTemplate that defines item appearance -->
</CarouselView.ItemTemplate>
</CarouselView>
<IndicatorView x:Name="indicatorView"
IndicatorColor="LightGray"
SelectedIndicatorColor="DarkGray"
HorizontalOptions="Center" />
</StackLayout>
Neste exemplo, o IndicatorView
é renderizado abaixo do CarouselView
, com um indicador para cada item no CarouselView
. O IndicatorView
é preenchido com dados definindo a CarouselView.IndicatorView
propriedade para o IndicatorView
objeto. Cada indicador é um círculo cinza claro, enquanto o indicador que representa o item atual no CarouselView
é cinza escuro:
Importante
A definição da CarouselView.IndicatorView
propriedade resulta na vinculação da IndicatorView.Position
propriedade à CarouselView.Position
propriedade e na vinculação da IndicatorView.ItemsSource
propriedade à CarouselView.ItemsSource
propriedade.
Para obter mais informações sobre indicadores, consulte Xamarin.Forms IndicatorView.
Menus de contexto
CarouselView
Oferece suporte a menus de contexto para itens de dados por meio do , que revela o menu de contexto com um gesto de passar o SwipeView
dedo. O SwipeView
é um controle de contêiner que envolve um item de conteúdo e fornece itens de menu de contexto para esse item de conteúdo. Portanto, os menus de contexto são implementados para um CarouselView
criando um SwipeView
que define o conteúdo que envolve SwipeView
e os itens de menu de contexto que são revelados pelo gesto de passar o dedo. Isso é obtido adicionando um SwipeView
ao que define a DataTemplate
aparência de cada item de dados no CarouselView
:
<CarouselView x:Name="carouselView"
ItemsSource="{Binding Monkeys}">
<CarouselView.ItemTemplate>
<DataTemplate>
<StackLayout>
<Frame HasShadow="True"
BorderColor="DarkGray"
CornerRadius="5"
Margin="20"
HeightRequest="300"
HorizontalOptions="Center"
VerticalOptions="CenterAndExpand">
<SwipeView>
<SwipeView.TopItems>
<SwipeItems>
<SwipeItem Text="Favorite"
IconImageSource="favorite.png"
BackgroundColor="LightGreen"
Command="{Binding Source={x:Reference carouselView}, Path=BindingContext.FavoriteCommand}"
CommandParameter="{Binding}" />
</SwipeItems>
</SwipeView.TopItems>
<SwipeView.BottomItems>
<SwipeItems>
<SwipeItem Text="Delete"
IconImageSource="delete.png"
BackgroundColor="LightPink"
Command="{Binding Source={x:Reference carouselView}, Path=BindingContext.DeleteCommand}"
CommandParameter="{Binding}" />
</SwipeItems>
</SwipeView.BottomItems>
<StackLayout>
<!-- Define item appearance -->
</StackLayout>
</SwipeView>
</Frame>
</StackLayout>
</DataTemplate>
</CarouselView.ItemTemplate>
</CarouselView>
Este é o código C# equivalente:
CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");
carouselView.ItemTemplate = new DataTemplate(() =>
{
StackLayout stackLayout = new StackLayout();
Frame frame = new Frame { ... };
SwipeView swipeView = new SwipeView();
SwipeItem favoriteSwipeItem = new SwipeItem
{
Text = "Favorite",
IconImageSource = "favorite.png",
BackgroundColor = Color.LightGreen
};
favoriteSwipeItem.SetBinding(MenuItem.CommandProperty, new Binding("BindingContext.FavoriteCommand", source: carouselView));
favoriteSwipeItem.SetBinding(MenuItem.CommandParameterProperty, ".");
SwipeItem deleteSwipeItem = new SwipeItem
{
Text = "Delete",
IconImageSource = "delete.png",
BackgroundColor = Color.LightPink
};
deleteSwipeItem.SetBinding(MenuItem.CommandProperty, new Binding("BindingContext.DeleteCommand", source: carouselView));
deleteSwipeItem.SetBinding(MenuItem.CommandParameterProperty, ".");
swipeView.TopItems = new SwipeItems { favoriteSwipeItem };
swipeView.BottomItems = new SwipeItems { deleteSwipeItem };
StackLayout swipeViewStackLayout = new StackLayout { ... };
swipeView.Content = swipeViewStackLayout;
frame.Content = swipeView;
stackLayout.Children.Add(frame);
return stackLayout;
});
Neste exemplo, o SwipeView
conteúdo é um StackLayout
que define a aparência de cada item que é cercado por um Frame
no CarouselView
. Os itens de passar o SwipeView
dedo são usados para executar ações no conteúdo e são revelados quando o controle é passado de cima para baixo:
SwipeView
Oferece suporte a quatro direções de deslizamento diferentes, com a direção do gesto de passar o dedo sendo definida pela coleção direcional SwipeItems
à qual os SwipeItems
objetos são adicionados. Por padrão, um item de passar o dedo é executado quando é tocado pelo usuário. Além disso, depois que um item de passar o dedo é executado, os itens de passar o dedo ficam ocultos e o SwipeView
conteúdo é exibido novamente. No entanto, esses comportamentos podem ser alterados.
Para obter mais informações sobre o SwipeView
controle, consulte Xamarin.Forms SwipeView.
Deslizar para atualizar
CarouselView
Oferece suporte à funcionalidade pull to refresh por meio do RefreshView
, que permite que os dados exibidos sejam atualizados puxando os itens para baixo. O RefreshView
é um controle de contêiner que fornece funcionalidade pull para atualizar seu filho, desde que o filho ofereça suporte a conteúdo rolável. Portanto, pull to refresh é implementado para um CarouselView
definindo-o como o filho de um RefreshView
:
<RefreshView IsRefreshing="{Binding IsRefreshing}"
Command="{Binding RefreshCommand}">
<CarouselView ItemsSource="{Binding Animals}">
...
</CarouselView>
</RefreshView>
Este é o código C# equivalente:
RefreshView refreshView = new RefreshView();
ICommand refreshCommand = new Command(() =>
{
// IsRefreshing is true
// Refresh data here
refreshView.IsRefreshing = false;
});
refreshView.Command = refreshCommand;
CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, "Animals");
refreshView.Content = carouselView;
// ...
Quando o usuário inicia uma atualização, o ICommand
definido pela propriedade é executado, o Command
que deve atualizar os itens que estão sendo exibidos. Uma visualização de atualização é mostrada enquanto a atualização ocorre, que consiste em um círculo de progresso animado:
O valor da RefreshView.IsRefreshing
propriedade indica o estado atual do RefreshView
. Quando uma atualização é acionada pelo usuário, essa propriedade será automaticamente transferida para true
. Quando a atualização for concluída, você deverá redefinir a propriedade para false
.
Para obter mais informações sobre RefreshView
o , consulte Xamarin.Forms RefreshView.
Carregar dados incrementalmente
CarouselView
Oferece suporte à virtualização de dados incrementais à medida que o usuário rola. Isso permite cenários como carregar de forma assíncrona uma página de dados de um serviço Web, à medida que o usuário rola. Além disso, o ponto em que mais dados são carregados é configurável para que os usuários não vejam espaço em branco ou sejam impedidos de rolar.
CarouselView
define as seguintes propriedades para controlar o carregamento incremental de dados:
RemainingItemsThreshold
, do tipoint
, o limite de itens ainda não visíveis na lista na qual oRemainingItemsThresholdReached
evento será disparado.RemainingItemsThresholdReachedCommand
, do tipoICommand
, que é executado quando oRemainingItemsThreshold
é atingido.RemainingItemsThresholdReachedCommandParameter
, do tipoobject
, que é o parâmetro passado paraRemainingItemsThresholdReachedCommand
.
CarouselView
também define um RemainingItemsThresholdReached
evento que é acionado quando o é rolado longe o suficiente para que RemainingItemsThreshold
os CarouselView
itens não tenham sido exibidos. Esse evento pode ser manipulado para carregar mais itens. Além disso, quando o RemainingItemsThresholdReached
evento é acionado, o é executado, permitindo que o RemainingItemsThresholdReachedCommand
carregamento incremental de dados ocorra em um viewmodel.
O valor padrão da RemainingItemsThreshold
propriedade é -1, que indica que o RemainingItemsThresholdReached
evento nunca será acionado. Quando o valor da propriedade for 0, o RemainingItemsThresholdReached
evento será acionado quando o item final no ItemsSource
for exibido. Para valores maiores que 0, o RemainingItemsThresholdReached
evento será acionado quando o ItemsSource
contém esse número de itens ainda não rolados.
Observação
CarouselView
valida a RemainingItemsThreshold
propriedade para que seu valor seja sempre maior ou igual a -1.
O exemplo XAML a seguir mostra um CarouselView
que carrega dados incrementalmente:
<CarouselView ItemsSource="{Binding Animals}"
RemainingItemsThreshold="2"
RemainingItemsThresholdReached="OnCarouselViewRemainingItemsThresholdReached"
RemainingItemsThresholdReachedCommand="{Binding LoadMoreDataCommand}">
...
</CarouselView>
Este é o código C# equivalente:
CarouselView carouselView = new CarouselView
{
RemainingItemsThreshold = 2
};
carouselView.RemainingItemsThresholdReached += OnCollectionViewRemainingItemsThresholdReached;
carouselView.SetBinding(ItemsView.ItemsSourceProperty, "Animals");
Neste exemplo de código, o RemainingItemsThresholdReached
evento é acionado quando há 2 itens ainda não rolados e, em resposta, executa o OnCollectionViewRemainingItemsThresholdReached
manipulador de eventos:
void OnCollectionViewRemainingItemsThresholdReached(object sender, EventArgs e)
{
// Retrieve more data here and add it to the CollectionView's ItemsSource collection.
}
Observação
Os dados também podem ser carregados incrementalmente vinculando o RemainingItemsThresholdReachedCommand
a uma ICommand
implementação no viewmodel.