Exibição de itens

Use uma exibição de itens para exibir uma coleção de itens de dados, como fotos em um álbum ou itens em um catálogo de produtos.

A exibição de itens é semelhante aos controles de exibição de lista e de exibição de grade e você pode usá-la na maioria dos casos em que você usaria esses controles. Uma vantagem do modo de exibição de itens é a capacidade de alternar o layout em tempo real, preservando a seleção do item.

O controle de exibição de itens é criado usando os componentes ItemsRepeater, ScrollView, ItemContainere ItemCollectionTransitionProvider, portanto, oferece a capacidade exclusiva de conectar implementações personalizadas de Layout ou ItemCollectionTransitionProvider. O controle ScrollView interno do modo de exibição de item permite rolagem e zoom dos itens. Ele também oferece recursos indisponíveis no controle ScrollViewer usados pela exibição de lista e modo de exibição de grade, como a capacidade de controlar a animação durante rolagem programática.

Assim como os controles de exibição de lista e exibição de grade, a exibição de itens pode usar a interface do usuário e a virtualização de dados; manipular o teclado, o mouse, a caneta e a entrada por toque; e tem suporte de acessibilidade interno.

Esse é o controle correto?

Use uma exibição de itens para:

• Exiba uma coleção em que todos os itens devem ter o mesmo comportamento visual e de interação.
• Exiba uma coleção de conteúdo com a capacidade de alternar entre a lista, a grade e os layouts personalizados.
• Acomodar uma série de casos de uso, incluindo os seguintes tipos comuns:
  • Interface do usuário do tipo vitrine (ou seja, pesquisando aplicativos, músicas, produtos etc.)
  • Bibliotecas de fotos interativas
  • Lista de contatos

Criar uma exibição de itens

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub

Um ItemsView pode mostrar uma coleção de itens de qualquer tipo. Para preencher o modo de exibição, defina a propriedade ItemsSource como uma fonte de dados.

Definir a origem dos itens

Normalmente, você usa uma exibição de itens para exibir dados de uma fonte, como um banco de dados ou a Internet. Para preencher uma exibição de itens de uma fonte de dados, defina sua propriedade ItemsSource como uma coleção de itens de dados.

Definir ItemsSource no código

Aqui, ItemsSource é definido em código diretamente como uma instância de uma coleção.

 // Data source.
 List<String> itemsList = new List<string>();
 itemsList.Add("Item 1");
 itemsList.Add("Item 2");

 // Create a new ItemsView and set the data source.
 ItemsView itemsView1 = new ItemsView();
 itemsView1.ItemsSource = itemsList;

 // Add the ItemsView to a parent container in the visual tree.
 rootGrid.Children.Add(itemsView1);

Associar ItemsSource em XAML

Você também pode associar a propriedade ItemsSource a uma coleção em XAML. Para obter mais informações, consulte Associação de dados com XAML.

Aqui, o ItemsSource está associado a uma coleção de objetos de dados personalizados (do tipo Photo).

<ItemsView ItemsSource="{x:Bind Photos}">

</ItemsView>

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();
        Photos = new ObservableCollection<Photo>();
        PopulatePhotos();
    }

    public ObservableCollection<Photo> Photos
    {
        get; private set;
    }


    private void PopulatePhotos()
    {
        // Populate the Photos collection. 
    }
}

public class Photo
{
    public BitmapImage PhotoBitmapImage { get; set; }
    public string Title { get; set; }
    public int Likes { get; set; }
}

Especificar a aparência dos itens

Por padrão, um item de dados é exibido na exibição de itens como a representação de cadeia de caracteres do objeto de dados ao qual ele está associado. Você geralmente quer mostrar uma apresentação mais sofisticada de seus dados. Para especificar exatamente como os itens na exibição de itens são exibidos, crie um DataTemplate. O XAML no DataTemplate define o layout e a aparência dos controles usados para exibir cada item. Os controles no layout podem ser associados a propriedades de um objeto de dados ou ter conteúdo estático definido embutido. O DataTemplate é atribuído à propriedade ItemTemplate do controle ItemsView.

Neste exemplo, o DataTemplate é definido no Page.Resources ResourceDictionary. Ele inclui um controle Image para mostrar a imagem e uma sobreposição que contém o título da imagem e o número de curtidas recebidos.

 <Page.Resources>
     <DataTemplate x:Key="PhotoItemTemplate" x:DataType="local:Photo">
         <ItemContainer AutomationProperties.Name="{x:Bind Title}">
             <Grid>
                 <Image Source="{x:Bind PhotoBitmapImage, Mode=OneWay}" 
                        Stretch="UniformToFill" MinWidth="70"
                        HorizontalAlignment="Center" VerticalAlignment="Center"/>
                 <StackPanel Orientation="Vertical" Height="40" Opacity=".75"
                             VerticalAlignment="Bottom" Padding="5,1,5,1" 
                             Background="{ThemeResource SystemControlBackgroundBaseMediumBrush}">
                     <TextBlock Text="{x:Bind Title}" 
                                Foreground="{ThemeResource SystemControlForegroundAltHighBrush}"/>
                     <StackPanel Orientation="Horizontal">
                         <TextBlock Text="{x:Bind Likes}"
                                    Style="{ThemeResource CaptionTextBlockStyle}"
                                    Foreground="{ThemeResource SystemControlForegroundAltHighBrush}"/>
                         <TextBlock Text=" Likes"
                                    Style="{ThemeResource CaptionTextBlockStyle}"
                                    Foreground="{ThemeResource SystemControlForegroundAltHighBrush}"/>
                     </StackPanel>
                 </StackPanel>
             </Grid>
         </ItemContainer>
     </DataTemplate>
 </Page.Resources>

 <Grid x:Name="rootGrid">
     <ItemsView ItemsSource="{x:Bind Photos}" Width="480" Height="400" 
                ItemTemplate="{StaticResource PhotoItemTemplate}">
     </ItemsView>
 </Grid>

Veja a aparência do layout do item definido pelo modelo de dados.

Alterar o layout dos itens

Quando você adiciona itens a um controle ItemsView, ele encapsula automaticamente cada item em um ItemContainer e, em seguida, define todos os contêineres de itens. A forma como esses contêineres de itens são dispostos depende da propriedade Layout do controle.

Você pode modificar o layout dos itens ajustando as propriedades no layout atual ou pode substituir completamente o layout atual por um layout diferente. Você pode usar um dos layouts descritos a seguir ou derivar um layout personalizado da classe Layout.

StackLayout

Por padrão, ItemsView usa um StackLayout, que produz uma lista vertical, mostrada aqui com configurações de propriedade padrão e um modelo de imagem simples.

Esse XAML define o espaçamento entre itens no StackLayout como 5px.

<ItemsView ItemsSource="{x:Bind Photos}" Width="480" Height="400" 
           ItemTemplate="{StaticResource PhotoItemTemplate}">
    <ItemsView.Layout>
        <StackLayout Spacing="5"/>
    </ItemsView.Layout>
</ItemsView>

O StackLayout fornece propriedades para controlar:

• se o layout é vertical ou horizontal (Orientação)
• o espaçamento de itens (Espaçamento)

Você pode usar o layout em combinação com o ItemTemplate para dar à sua coleção uma variedade de aparências para atender às suas necessidades. Por exemplo, o exemplo da Galeria da WinUI altera o ItemTemplate usado com o StackLayout para ter esta aparência.

LinedFlowLayout

O LinedFlowLayout posiciona os elementos sequencialmente da esquerda para a direita e, em seguida, de cima para baixo, em um layout de disposição. Use esse layout para exibir uma coleção de itens em que os itens têm uma altura fixa, mas uma largura variável. Recomendamos isso para coleções baseadas em imagem. Esse layout também tem animações internas que são reproduzidas quando a coleção tem itens adicionados ou removidos e quando a exibição é redimensionada.

Aqui está uma exibição de itens que mostra uma coleção de fotos em um layout de fluxo forrado.

<ItemsView Width="500" Height="400" HorizontalAlignment="Left"
           ItemTemplate="{StaticResource LinedFlowLayoutItemTemplate}">
    <ItemsView.Layout>
        <LinedFlowLayout ItemsStretch="Fill" 
                         LineHeight="160" 
                         LineSpacing="5"
                         MinItemSpacing="5"/>
    </ItemsView.Layout>
</ItemsView>

LinedFlowLayout fornece propriedades para controlar:

• o tamanho e o espaçamento de itens (LineHeight, LineSpacing, MinItemSpacing)
• a disposição dos itens (ItemsJustification, ItemsStretch)

UniformGridLayout

O UniformGridLayout posiciona os elementos sequencialmente da esquerda para a direita ou de cima para baixo (dependendo da Orientação) em um layout de disposição. Cada item tem o mesmo tamanho.

Aqui está uma exibição de itens que mostra uma coleção de fotos em um layout de grade uniforme.

<ItemsView ItemsSource="{x:Bind Photos}" Width="480" Height="400"
           ItemTemplate="{StaticResource PhotoItemTemplate}">
    <ItemsView.Layout>
        <UniformGridLayout MaximumRowsOrColumns="3" 
                           MinRowSpacing="5" 
                           MinColumnSpacing="5"/>
    </ItemsView.Layout>
</ItemsView>

UniformGridLayout fornece propriedades para controlar:

• se o layout é baseado em linha ou coluna (Orientação)
• o número de linhas ou colunas (MaximumRowsOrColumns)
• o tamanho e o espaçamento de itens (MinItemHeight, MinItemWidth, MinColumnSpacing, MinRowSpacing)
• a disposição dos itens (ItemsJustification, ItemsStretch)

Seleção e interação de itens

Você pode escolher entre várias maneiras de permitir que os usuários interajam com uma exibição de itens. Por padrão, os usuários podem selecionar um único item. Você pode alterar a propriedade SelectionMode para habilitar a multisseleção ou desabilitar a seleção. Você pode definir a propriedade IsItemInvokedEnabled para que os usuários cliquem em um item para invocar uma ação em vez de selecionar o item.

Esta tabela mostra as maneiras pelas quais um usuário pode interagir com um modo de exibição de itens e como você pode responder à interação.

Você pode definir essas propriedades em XAML ou em código, conforme mostrado aqui:

<ItemsView x:Name="myItemsView" SelectionMode="None" IsItemInvokedEnabled="True"/>

myItemsView.SelectionMode = ItemsViewSelectionMode.None;
myItemsView.IsItemInvokedEnabled = true;

Somente leitura

Você pode definir a propriedade SelectionMode como ItemsViewSelectionMode.None para desabilitar a seleção de item. Isso coloca o controle no modo somente leitura, para que ele seja usado para exibir dados, mas não para interagir com ele. Ou seja, a seleção de item está desabilitada, mas o controle em si não está.

Seleção única

Esta tabela descreve as interações de teclado, mouse e toque quando SelectionMode é definido como Single.

Quando SelectionMode estiver definido como Single, você poderá obter o item de dados selecionado na propriedade SelectedItem. Se nenhum item estiver selecionado, SelectedItem será null.

Se você tentar definir um item que não está na coleção de itens como SelectedItem, a operação será ignorada e SelectedItem será null.

O indicador de seleção padrão para seleção de Single tem esta aparência.

Seleção múltipla

Esta tabela descreve as interações de teclado, mouse e toque quando SelectionMode é definido como Multiple.

O indicador de seleção padrão para seleção de Multiple tem esta aparência.

Seleção estendida

Esta tabela descreve as interações de teclado, mouse e toque quando SelectionMode é definido como Extended.

Quando SelectionMode é definido como Multiple ou Extended, você pode obter os itens de dados selecionados na propriedade SelectedItems.

As propriedades SelectedItem e SelectedItems são sincronizadas. Por exemplo, se você definir SelectedItem como null, SelectedItems estará vazio. No modo de seleção múltipla, SelectedItem contém o item que foi selecionado primeiro.

O indicador de seleção padrão para seleção de Extended é o mesmo da seleção de Single e tem esta aparência.

Gerenciar a seleção de itens programaticamente

Às vezes, talvez seja necessário manipular a seleção de item ItemsView programaticamente. Por exemplo, você pode exibir um botão Selecionar tudo para permitir que os usuários selecionem todos os itens em uma lista. Nesse caso, geralmente não é muito eficiente adicionar e remover itens da coleção SelectedItems um a um. É mais eficiente usar os métodos Select, SelectAll, Deselect e InvertSelection para modificar a seleção do que usar a propriedade SelectedItems.

Obter o código de exemplo

• Exemplo de Galeria da WinUI: veja todos os controles XAML em um formato interativo.

Artigos relacionados

• Diretrizes para listas
• Classe ItemsView
• StackLayout
• UniformGridLayout
• LinedFlowLayout