Dados CollectionView do Xamarin. FormsXamarin.Forms CollectionView Data

Baixar Exemplo Baixar o exemploDownload Sample Download the sample

CollectionViewdefine as seguintes propriedades que definem os dados a serem exibidos e sua aparência:CollectionView defines 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. nullItemsSource, 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

CollectionViewdefine uma ItemsUpdatingScrollMode propriedade que representa o comportamento CollectionView de rolagem do 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.

CollectionViewtambém pode carregar dados de forma incremental à medida que o usuário rola.CollectionView can also load data incrementally 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 ItemsSource sua propriedade para qualquer coleção que IEnumerableimplementa.A CollectionView is populated with data by setting its ItemsSource property to any collection that implements IEnumerable. Os itens podem ser adicionados em XAML inicializando ItemsSource a propriedade de uma matriz de cadeias de caracteres:Items can be added in XAML by initializing the ItemsSource property from an array of strings:

<CollectionView>
  <CollectionView.ItemsSource>
    <x:Array Type="{x:Type x:String}">
      <x:String>Baboon</x:String>
      <x:String>Capuchin Monkey</x:String>
      <x:String>Blue Monkey</x:String>
      <x:String>Squirrel Monkey</x:String>
      <x:String>Golden Lion Tamarin</x:String>
      <x:String>Howler Monkey</x:String>
      <x:String>Japanese Macaque</x:String>
    </x:Array>
  </CollectionView.ItemsSource>
</CollectionView>

Observação

Observe que o elemento x:Array requer um atributo Type que indica o tipo dos itens na matriz.Note that the x:Array element requires a Type attribute indicating the type of the items in the array.

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

CollectionView collectionView = new CollectionView();
collectionView.ItemsSource = new string[]
{
    "Baboon",
    "Capuchin Monkey",
    "Blue Monkey",
    "Squirrel Monkey",
    "Golden Lion Tamarin",
    "Howler Monkey",
    "Japanese Macaque"
};

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 IEnumerable uma coleção que enviará notificações de ObservableCollectionalteração de propriedade, como.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.

Por padrão, CollectionView o exibe itens em uma lista vertical, conforme mostrado nas capturas de tela a seguir:By default, CollectionView displays items in a vertical list, as shown in the following screenshots:

[ Captura de tela de CollectionView contendo itens de texto, em itens de texto do IOS e Android ] (populate-data-images/text-large.png#lightbox "Itens de texto em um CollectionView")Screenshot of CollectionView containing text items, on iOS and Android

Para obter informações sobre como alterar o CollectionView layout, consulte especificar um layout.For information on how to change the CollectionView layout, see Specify a 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.

Associação de dadosData binding

CollectionViewpode ser preenchido com dados usando a vinculação de dados para associar ItemsSource sua propriedade a IEnumerable uma 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}" />

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 aplicativos Xamarin. Forms.Compiled bindings can be enabled to improve data binding performance in Xamarin.Forms applications. Para saber mais, confira Associações compiladas.For more information, see Compiled Bindings.

Para obter mais informações sobre associação de dados, confira Associação de Dados do Xamarin.Forms.For more information about data binding, see Xamarin.Forms Data Binding.

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 DataTemplatea: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>

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 Monkey , todos associados a propriedades da 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, em itens de modelo Ios e Android ] (populate-data-images/datatemplate-large.png#lightbox "Itens de modelo em um CollectionView")Screenshot of CollectionView where each item is templated, on iOS and Android

Para obter mais informações sobre modelos de dados, confira Modelos de dados do Xamarin.Forms.For more information about data templates, see 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 DataTemplateSelector um 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>

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 MonkeyDataTemplateSelector a 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 PropriedadesquesãodefinidasparamodelosDataTemplate 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", OnSelectTemplate a substituição retorna OtherMonkey o 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, na do IOS e Android] (populate-data-images/datatemplateselector-large.png#lightbox "Seleção de modelo de item de tempo de execução em um CollectionView")Screenshot of CollectionView runtime item template selection, on iOS and Android

Para obter mais informações sobre seletores de modelo de dados, consulte criar um Xamarin. Forms DataTemplateSelector.For more information about data template selectors, see Create a 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.

Carregar dados de forma incrementalLoad data incrementally

CollectionViewdá suporte ao carregamento de dados incrementalmente conforme os usuários rolam os itens.CollectionView supports loading data incrementally as users scroll through items. 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.

CollectionViewdefine 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.

CollectionViewtambém define um RemainingItemsThresholdReached evento que é acionado quando CollectionView o é rolado muito suficiente RemainingItemsThreshold para que 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, RemainingItemsThresholdReachedCommand o é 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, RemainingItemsThresholdReached o evento será acionado quando o item final ItemsSource no 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

CollectionViewvalida 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 CollectionView mostra um 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>

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 OnCollectionViewRemainingItemsThresholdReached o 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.