:::no-loc(Xamarin.Forms)::: Dados CollectionView:::no-loc(Xamarin.Forms)::: CollectionView Data

Baixar Exemplo Baixar o exemploDownload Sample Download the sample

CollectionView inclui as seguintes propriedades que definem os dados a serem exibidos e sua aparência:CollectionView includes the following properties that define the data to be displayed, and its appearance:

  • ItemsSource, do tipo IEnumerable , especifica a coleção de itens a serem exibidos e tem um valor padrão de null .ItemsSource, of type IEnumerable, specifies the collection of items to be displayed, and has a default value of null.
  • ItemTemplate, do tipo DataTemplate , especifica o modelo a ser aplicado a cada item na coleção de itens a ser exibida.ItemTemplate, of type DataTemplate, specifies the template to apply to each item in the collection of items to be displayed.

Essas propriedades são apoiadas por BindableProperty objetos, o que significa que as propriedades podem ser destinos de associações de dados.These properties are backed by BindableProperty objects, which means that the properties can be targets of data bindings.

Observação

CollectionView define uma ItemsUpdatingScrollMode propriedade que representa o comportamento de rolagem do CollectionView quando novos itens são adicionados a ele.CollectionView defines a ItemsUpdatingScrollMode property that represents the scrolling behavior of the CollectionView when new items are added to it. Para obter mais informações sobre essa propriedade, consulte controlar posição de rolagem quando novos itens forem adicionados.For more information about this property, see Control scroll position when new items are added.

CollectionView dá suporte à virtualização de dados incremental à medida que o usuário rola.CollectionView supports incremental data virtualization as the user scrolls. Para obter mais informações, consulte carregar dados incrementalmente.For more information, see Load data incrementally.

Preencher um CollectionView com dadosPopulate a CollectionView with data

Um CollectionView é populado com dados definindo sua ItemsSource propriedade para qualquer coleção que implementa IEnumerable .A CollectionView is populated with data by setting its ItemsSource property to any collection that implements IEnumerable. Por padrão, CollectionView o exibe itens em uma lista vertical.By default, CollectionView displays items in a vertical list.

Importante

Se o CollectionView for necessário para atualizar à medida que os itens forem adicionados, removidos ou alterados na coleção subjacente, a coleção subjacente deverá ser uma IEnumerable coleção que enviará notificações de alteração de propriedade, como ObservableCollection .If the CollectionView is required to refresh as items are added, removed, or changed in the underlying collection, the underlying collection should be an IEnumerable collection that sends property change notifications, such as ObservableCollection.

CollectionView pode ser preenchido com dados usando a vinculação de dados para associar sua ItemsSource Propriedade a uma IEnumerable coleção.CollectionView can be populated with data by using data binding to bind its ItemsSource property to an IEnumerable collection. Em XAML, isso é obtido com a Binding extensão de marcação:In XAML, this is achieved with the Binding markup extension:

<CollectionView ItemsSource="{Binding Monkeys}" />

Este é o código C# equivalente:The equivalent C# code is:

CollectionView collectionView = new CollectionView();
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");

Neste exemplo, os ItemsSource dados de propriedade são associados à Monkeys Propriedade do ViewModel conectado.In this example, the ItemsSource property data binds to the Monkeys property of the connected viewmodel.

Observação

Associações compiladas podem ser habilitadas para melhorar o desempenho de vinculação de dados em :::no-loc(Xamarin.Forms)::: aplicativos.Compiled bindings can be enabled to improve data binding performance in :::no-loc(Xamarin.Forms)::: applications. Para saber mais, confira Associações compiladas.For more information, see Compiled Bindings.

Para obter informações sobre como alterar o CollectionView layout, consulte :::no-loc(Xamarin.Forms)::: layout CollectionView.For information on how to change the CollectionView layout, see :::no-loc(Xamarin.Forms)::: CollectionView Layout. Para obter informações sobre como definir a aparência de cada item no CollectionView , consulte definir a aparência do item.For information on how to define the appearance of each item in the CollectionView, see Define item appearance. Para obter mais informações sobre a vinculação de dados, consulte :::no-loc(Xamarin.Forms)::: vinculação de dados.For more information about data binding, see :::no-loc(Xamarin.Forms)::: Data Binding.

Aviso

CollectionView gerará uma exceção se sua ItemsSource for atualizada fora do thread da interface do usuário.CollectionView will throw an exception if its ItemsSource is updated off the UI thread.

Definir a aparência do itemDefine item appearance

A aparência de cada item no CollectionView pode ser definida definindo a CollectionView.ItemTemplate propriedade como a DataTemplate :The appearance of each item in the CollectionView can be defined by setting the CollectionView.ItemTemplate property to a DataTemplate:

<CollectionView ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <Grid Padding="10">
                <Grid.RowDefinitions>
                    <RowDefinition Height="Auto" />
                    <RowDefinition Height="Auto" />
                </Grid.RowDefinitions>
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto" />
                    <ColumnDefinition Width="Auto" />
                </Grid.ColumnDefinitions>
                <Image Grid.RowSpan="2"
                       Source="{Binding ImageUrl}"
                       Aspect="AspectFill"
                       HeightRequest="60"
                       WidthRequest="60" />
                <Label Grid.Column="1"
                       Text="{Binding Name}"
                       FontAttributes="Bold" />
                <Label Grid.Row="1"
                       Grid.Column="1"
                       Text="{Binding Location}"
                       FontAttributes="Italic"
                       VerticalOptions="End" />
            </Grid>
        </DataTemplate>
    </CollectionView.ItemTemplate>
    ...
</CollectionView>

Este é o código C# equivalente:The equivalent C# code is:

CollectionView collectionView = new CollectionView();
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");

collectionView.ItemTemplate = new DataTemplate(() =>
{
    Grid grid = new Grid { Padding = 10 };
    grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Auto });
    grid.RowDefinitions.Add(new RowDefinition { Height = GridLength.Auto });
    grid.ColumnDefinitions.Add(new ColumnDefinition { Width = GridLength.Auto });
    grid.ColumnDefinitions.Add(new ColumnDefinition { Width = GridLength.Auto });

    Image image = new Image { Aspect = Aspect.AspectFill, HeightRequest = 60, WidthRequest = 60 };
    image.SetBinding(Image.SourceProperty, "ImageUrl");

    Label nameLabel = new Label { FontAttributes = FontAttributes.Bold };
    nameLabel.SetBinding(Label.TextProperty, "Name");

    Label locationLabel = new Label { FontAttributes = FontAttributes.Italic, VerticalOptions = LayoutOptions.End };
    locationLabel.SetBinding(Label.TextProperty, "Location");

    Grid.SetRowSpan(image, 2);

    grid.Children.Add(image);
    grid.Children.Add(nameLabel, 1, 0);
    grid.Children.Add(locationLabel, 1, 1);

    return grid;
});

Os elementos especificados no DataTemplate definem a aparência de cada item na lista.The elements specified in the DataTemplate define the appearance of each item in the list. No exemplo, o layout dentro do DataTemplate é gerenciado por um Grid .In the example, layout within the DataTemplate is managed by a Grid. O Grid contém um Image objeto e dois Label objetos, todos associados a propriedades da Monkey classe:The Grid contains an Image object, and two Label objects, that all bind to properties of the Monkey class:

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 na lista:The following screenshots show the result of templating each item in the list:

Captura de tela de CollectionView em que cada item é modelado, no iOS e no AndroidScreenshot of CollectionView where each item is templated, on iOS and Android

Para obter mais informações sobre modelos de dados, consulte :::no-loc(Xamarin.Forms)::: modelos de dados.For more information about data templates, see :::no-loc(Xamarin.Forms)::: Data Templates.

Escolher a aparência do item em tempo de execuçãoChoose item appearance at runtime

A aparência de cada item no CollectionView pode ser escolhida em tempo de execução, com base no valor do item, definindo a CollectionView.ItemTemplate propriedade como um DataTemplateSelector objeto:The appearance of each item in the CollectionView can be chosen at runtime, based on the item value, by setting the CollectionView.ItemTemplate property to a DataTemplateSelector object:

<ContentPage ...
             xmlns:controls="clr-namespace:CollectionViewDemos.Controls">
    <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>

    <CollectionView ItemsSource="{Binding Monkeys}"
                    ItemTemplate="{StaticResource MonkeySelector}" />
</ContentPage>

Este é o código C# equivalente:The equivalent C# code is:

CollectionView collectionView = new CollectionView
{
    ItemTemplate = new MonkeyDataTemplateSelector { ... }
};
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");

A ItemTemplate propriedade é definida como um MonkeyDataTemplateSelector objeto.The ItemTemplate property is set to a MonkeyDataTemplateSelector object. O exemplo a seguir mostra a MonkeyDataTemplateSelector classe:The following example shows the MonkeyDataTemplateSelector class:

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 MonkeyDataTemplateSelector classe define AmericanMonkey e OtherMonkey DataTemplate Propriedades que são definidas para modelos de dados diferentes.The MonkeyDataTemplateSelector class defines AmericanMonkey and OtherMonkey DataTemplate properties that are set to different data templates. A OnSelectTemplate substituição retorna o AmericanMonkey modelo, que exibe o nome do macaco e o local em azul-petróleo, quando o nome do macaco contiver "America".The OnSelectTemplate override returns the AmericanMonkey template, which displays the monkey name and location in teal, when the monkey name contains "America". Quando o nome do macaco não contém "America", a OnSelectTemplate substituição retorna o OtherMonkey modelo, que exibe o nome do macaco e o local em prata:When the monkey name doesn't contain "America", the OnSelectTemplate override returns the OtherMonkey template, which displays the monkey name and location in silver:

Captura de tela da seleção de modelo de item de tempo de execução CollectionView em iOS e AndroidScreenshot of CollectionView runtime item template selection, on iOS and Android

Para obter mais informações sobre seletores de modelo de dados, consulte criar um :::no-loc(Xamarin.Forms)::: DataTemplateSelector.For more information about data template selectors, see Create a :::no-loc(Xamarin.Forms)::: DataTemplateSelector.

Importante

Ao usar CollectionView , nunca defina o elemento raiz de seus DataTemplate objetos como um ViewCell .When using CollectionView, never set the root element of your DataTemplate objects to a ViewCell. Isso resultará em uma exceção sendo gerada porque CollectionView não tem nenhum conceito de células.This will result in an exception being thrown because CollectionView has no concept of cells.

Menus de contextoContext menus

CollectionView dá suporte a menus de contexto para itens de dados por meio do SwipeView , que revela o menu de contexto com um gesto de passar o dedo.CollectionView supports context menus for items of data through the SwipeView, which reveals the context menu with a swipe gesture. O SwipeView é um controle de contêiner que encapsula em um item de conteúdo e fornece itens de menu de contexto para esse item de conteúdo.The SwipeView is a container control that wraps around an item of content, and provides context menu items for that item of content. Portanto, os menus de contexto são implementados para um CollectionView criando um SwipeView que define o conteúdo que o SwipeView encapsulado e os itens do menu de contexto que são revelados pelo gesto de passar o dedo.Therefore, context menus are implemented for a CollectionView by creating a SwipeView that defines the content that the SwipeView wraps around, and the context menu items that are revealed by the swipe gesture. Isso é feito definindo o SwipeView como a exibição raiz no DataTemplate que define a aparência de cada item de dados no CollectionView :This is achieved by setting the SwipeView as the root view in the DataTemplate that defines the appearance of each item of data in the CollectionView:

<CollectionView x:Name="collectionView"
                ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <SwipeView>
                <SwipeView.LeftItems>
                    <SwipeItems>
                        <SwipeItem Text="Favorite"
                                   IconImageSource="favorite.png"
                                   BackgroundColor="LightGreen"
                                   Command="{Binding Source={x:Reference collectionView}, Path=BindingContext.FavoriteCommand}"
                                   CommandParameter="{Binding}" />
                        <SwipeItem Text="Delete"
                                   IconImageSource="delete.png"
                                   BackgroundColor="LightPink"
                                   Command="{Binding Source={x:Reference collectionView}, Path=BindingContext.DeleteCommand}"
                                   CommandParameter="{Binding}" />
                    </SwipeItems>
                </SwipeView.LeftItems>
                <Grid BackgroundColor="White"
                      Padding="10">
                    <!-- Define item appearance -->
                </Grid>
            </SwipeView>
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

Este é o código C# equivalente:The equivalent C# code is:

CollectionView collectionView = new CollectionView();
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Monkeys");

collectionView.ItemTemplate = new DataTemplate(() =>
{
    // Define item appearance
    Grid grid = new Grid { Padding = 10, BackgroundColor = Color.White };
    // ...

    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: collectionView));
    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: collectionView));
    deleteSwipeItem.SetBinding(MenuItem.CommandParameterProperty, ".");

    swipeView.LeftItems = new SwipeItems { favoriteSwipeItem, deleteSwipeItem };
    swipeView.Content = grid;    
    return swipeView;
});

Neste exemplo, o SwipeView conteúdo é um Grid que define a aparência de cada item no CollectionView .In this example, the SwipeView content is a Grid that defines the appearance of each item in the CollectionView. Os itens do dedo são usados para executar ações no SwipeView conteúdo e são revelados quando o controle é transdedodo do lado esquerdo:The swipe items are used to perform actions on the SwipeView content, and are revealed when the control is swiped from the left side:

Captura de tela de itens de menu de contexto CollectionView, em iOS e AndroidScreenshot of CollectionView context menu items, on iOS and Android

SwipeView dá suporte a quatro direções de toque diferentes, com a direção do dedo sendo definida pela SwipeItems coleção direcional à SwipeItems qual os objetos são adicionados.SwipeView supports four different swipe directions, with the swipe direction being defined by the directional SwipeItems collection the SwipeItems objects are added to. Por padrão, um item de dedo é executado quando ele é tocado pelo usuário.By default, a swipe item is executed when it's tapped by the user. Além disso, quando um item de dedo for executado, os itens do dedo serão ocultados e o SwipeView conteúdo será exibido novamente.In addition, once a swipe item has been executed the swipe items are hidden and the SwipeView content is re-displayed. No entanto, esses comportamentos podem ser alterados.However, these behaviors can be changed.

Para obter mais informações sobre o SwipeView controle, consulte :::no-loc(Xamarin.Forms)::: SwipeView.For more information about the SwipeView control, see :::no-loc(Xamarin.Forms)::: SwipeView.

Puxar para atualizarPull to refresh

CollectionView dá suporte à funcionalidade de pull para atualizar por meio do RefreshView , que permite que os dados sejam exibidos para serem atualizados ao puxar a lista de itens.CollectionView supports pull to refresh functionality through the RefreshView, which enables the data being displayed to be refreshed by pulling down on the list of items. O RefreshView é um controle de contêiner que fornece a funcionalidade de pull para atualizar para seu filho, desde que o filho ofereça suporte a conteúdo rolável.The RefreshView is a container control that provides pull to refresh functionality to its child, provided that the child supports scrollable content. Portanto, o pull para a atualização é implementado para um definindo CollectionView -o como o filho de um RefreshView :Therefore, pull to refresh is implemented for a CollectionView by setting it as the child of a RefreshView:

<RefreshView IsRefreshing="{Binding IsRefreshing}"
             Command="{Binding RefreshCommand}">
    <CollectionView ItemsSource="{Binding Animals}">
        ...
    </CollectionView>
</RefreshView>

Este é o código C# equivalente:The equivalent C# code is:

RefreshView refreshView = new RefreshView();
ICommand refreshCommand = new Command(() =>
{
    // IsRefreshing is true
    // Refresh data here
    refreshView.IsRefreshing = false;
});
refreshView.Command = refreshCommand;

CollectionView collectionView = new CollectionView();
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Animals");
refreshView.Content = collectionView;
// ...

Quando o usuário inicia uma atualização, o ICommand definido pela Command propriedade é executado, o que deve atualizar os itens que estão sendo exibidos.When the user initiates a refresh, the ICommand defined by the Command property is executed, which should refresh the items being displayed. Uma visualização de atualização é mostrada enquanto a atualização ocorre, que consiste em um círculo de progresso animado:A refresh visualization is shown while the refresh occurs, which consists of an animated progress circle:

Captura de tela de pull-to-Refresh CollectionView, no iOS e no AndroidScreenshot of CollectionView pull-to-refresh, on iOS and Android

O valor da RefreshView.IsRefreshing propriedade indica o estado atual do RefreshView .The value of the RefreshView.IsRefreshing property indicates the current state of the RefreshView. Quando uma atualização for disparada pelo usuário, essa propriedade passará automaticamente para o true .When a refresh is triggered by the user, this property will automatically transition to true. Quando a atualização for concluída, você deverá redefinir a propriedade para false .Once the refresh completes, you should reset the property to false.

Para obter mais informações sobre o RefreshView , consulte :::no-loc(Xamarin.Forms)::: RefreshView.For more information about RefreshView, see :::no-loc(Xamarin.Forms)::: RefreshView.

Carregar dados de forma incrementalLoad data incrementally

CollectionView dá suporte à virtualização de dados incremental à medida que o usuário rola.CollectionView supports incremental data virtualization as the user scrolls. Isso permite cenários como o carregamento assíncrono de uma página de dados de um serviço Web, à medida que o usuário rola.This enables scenarios such as asynchronously loading a page of data from a web service, as the user scrolls. Além disso, o ponto no qual mais dados são carregados é configurável para que os usuários não vejam o espaço em branco ou sejam interrompidos da rolagem.In addition, the point at which more data is loaded is configurable so that users don't see blank space, or are stopped from scrolling.

CollectionView define as propriedades a seguir para controlar o carregamento incremental de dados:CollectionView defines the following properties to control incremental loading of data:

  • RemainingItemsThreshold, do tipo int , o limite de itens ainda não visíveis na lista na qual o RemainingItemsThresholdReached evento será acionado.RemainingItemsThreshold, of type int, the threshold of items not yet visible in the list at which the RemainingItemsThresholdReached event will be fired.
  • RemainingItemsThresholdReachedCommand, do tipo ICommand , que é executado quando o RemainingItemsThreshold é atingido.RemainingItemsThresholdReachedCommand, of type ICommand, which is executed when the RemainingItemsThreshold is reached.
  • RemainingItemsThresholdReachedCommandParameter, do tipo object, que é o parâmetro passado para RemainingItemsThresholdReachedCommand.RemainingItemsThresholdReachedCommandParameter, of type object, which is the parameter that's passed to the RemainingItemsThresholdReachedCommand.

CollectionView também define um RemainingItemsThresholdReached evento que é acionado quando o CollectionView é rolado muito suficiente para que RemainingItemsThreshold os itens não tenham sido exibidos.CollectionView also defines a RemainingItemsThresholdReached event that is fired when the CollectionView is scrolled far enough that RemainingItemsThreshold items have not been displayed. Esse evento pode ser tratado para carregar mais itens.This event can be handled to load more items. Além disso, quando o RemainingItemsThresholdReached evento é acionado, o RemainingItemsThresholdReachedCommand é executado, permitindo que o carregamento de dados incremental ocorra em um ViewModel.In addition, when the RemainingItemsThresholdReached event is fired, the RemainingItemsThresholdReachedCommand is executed, enabling incremental data loading to take place in a viewmodel.

O valor padrão da RemainingItemsThreshold propriedade é-1, que indica que o RemainingItemsThresholdReached evento nunca será acionado.The default value of the RemainingItemsThreshold property is -1, which indicates that the RemainingItemsThresholdReached event will never be fired. Quando o valor da propriedade for 0, o RemainingItemsThresholdReached evento será acionado quando o item final no ItemsSource for exibido.When the property value is 0, the RemainingItemsThresholdReached event will be fired when the final item in the ItemsSource is displayed. Para valores maiores que 0, o RemainingItemsThresholdReached evento será acionado quando o ItemsSource contiver esse número de itens ainda não rolados.For values greater than 0, the RemainingItemsThresholdReached event will be fired when the ItemsSource contains that number of items not yet scrolled to.

Observação

CollectionView valida a RemainingItemsThreshold propriedade para que seu valor seja sempre maior ou igual a-1.CollectionView validates the RemainingItemsThreshold property so that its value is always greater than or equal to -1.

O exemplo de XAML a seguir mostra um CollectionView que carrega dados de forma incremental:The following XAML example shows a CollectionView that loads data incrementally:

<CollectionView ItemsSource="{Binding Animals}"
                RemainingItemsThreshold="5"
                RemainingItemsThresholdReached="OnCollectionViewRemainingItemsThresholdReached">
    ...
</CollectionView>

Este é o código C# equivalente:The equivalent C# code is:

CollectionView collectionView = new CollectionView
{
    RemainingItemsThreshold = 5
};
collectionView.RemainingItemsThresholdReached += OnCollectionViewRemainingItemsThresholdReached;
collectionView.SetBinding(ItemsView.ItemsSourceProperty, "Animals");

Neste exemplo de código, o RemainingItemsThresholdReached evento é acionado quando há 5 itens ainda não rolados para e, em resposta, executa o OnCollectionViewRemainingItemsThresholdReached manipulador de eventos:In this code example, the RemainingItemsThresholdReached event fires when there are 5 items not yet scrolled to, and in response executes the OnCollectionViewRemainingItemsThresholdReached event handler:

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 ligando o RemainingItemsThresholdReachedCommand a uma ICommand implementação no ViewModel.Data can also be loaded incrementally by binding the RemainingItemsThresholdReachedCommand to an ICommand implementation in the viewmodel.