:::no-loc(Xamarin.Forms)::: Rolagem de CollectionView:::no-loc(Xamarin.Forms)::: CollectionView Scrolling

Baixar Exemplo Baixar o exemploDownload Sample Download the sample

CollectionView define dois ScrollTo métodos, que rolam itens para o modo de exibição.CollectionView defines two ScrollTo methods, that scroll items into view. Uma das sobrecargas rola o item no índice especificado para a exibição, enquanto o outro rola o item especificado para a exibição.One of the overloads scrolls the item at the specified index into view, while the other scrolls the specified item into view. Ambas as sobrecargas têm argumentos adicionais que podem ser especificados para indicar o grupo ao qual o item pertence, a posição exata do item após a conclusão da rolagem e se a rolagem deve ser animada.Both overloads have additional arguments that can be specified to indicate the group the item belongs to, the exact position of the item after the scroll has completed, and whether to animate the scroll.

CollectionView define um ScrollToRequested evento que é acionado quando um dos ScrollTo métodos é invocado.CollectionView defines a ScrollToRequested event that is fired when one of the ScrollTo methods is invoked. O ScrollToRequestedEventArgs objeto que acompanha o ScrollToRequested evento tem muitas propriedades, incluindo IsAnimated ,, Index Item e ScrollToPosition .The ScrollToRequestedEventArgs object that accompanies the ScrollToRequested event has many properties, including IsAnimated, Index, Item, and ScrollToPosition. Essas propriedades são definidas a partir dos argumentos especificados nas ScrollTo chamadas de método.These properties are set from the arguments specified in the ScrollTo method calls.

Além disso, CollectionView o define um Scrolled evento que é acionado para indicar que a rolagem ocorreu.In addition, CollectionView defines a Scrolled event that is fired to indicate that scrolling occurred. O ItemsViewScrolledEventArgs objeto que acompanha o Scrolled evento tem muitas propriedades.The ItemsViewScrolledEventArgs object that accompanies the Scrolled event has many properties. Para obter mais informações, consulte detectar rolagem.For more information, see Detect scrolling.

CollectionView também define uma ItemsUpdatingScrollMode propriedade que representa o comportamento de rolagem do CollectionView quando novos itens são adicionados a ele.CollectionView also 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.

Quando um usuário passa o dedo para iniciar uma rolagem, a posição final da rolagem pode ser controlada para que os itens sejam totalmente exibidos.When a user swipes to initiate a scroll, the end position of the scroll can be controlled so that items are fully displayed. Esse recurso é conhecido como encaixe, pois os itens se ajustam à posição quando a rolagem é interrompida.This feature is known as snapping, because items snap to position when scrolling stops. Para obter mais informações, consulte snap Points.For more information, see Snap points.

CollectionView també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.

Detectar rolagemDetect scrolling

CollectionView define um Scrolled evento que é acionado para indicar que a rolagem ocorreu.CollectionView defines a Scrolled event which is fired to indicate that scrolling occurred. O exemplo de XAML a seguir mostra um CollectionView que define um manipulador de eventos para o Scrolled evento:The following XAML example shows a CollectionView that sets an event handler for the Scrolled event:

<CollectionView Scrolled="OnCollectionViewScrolled">
    ...
</CollectionView>

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

CollectionView collectionView = new CollectionView();
collectionView.Scrolled += OnCollectionViewScrolled;

Neste exemplo de código, o OnCollectionViewScrolled manipulador de eventos é executado quando o evento é disparado Scrolled :In this code example, the OnCollectionViewScrolled event handler is executed when the Scrolled event fires:

void OnCollectionViewScrolled(object sender, ItemsViewScrolledEventArgs e)
{
    Debug.WriteLine("HorizontalDelta: " + e.HorizontalDelta);
    Debug.WriteLine("VerticalDelta: " + e.VerticalDelta);
    Debug.WriteLine("HorizontalOffset: " + e.HorizontalOffset);
    Debug.WriteLine("VerticalOffset: " + e.VerticalOffset);
    Debug.WriteLine("FirstVisibleItemIndex: " + e.FirstVisibleItemIndex);
    Debug.WriteLine("CenterItemIndex: " + e.CenterItemIndex);
    Debug.WriteLine("LastVisibleItemIndex: " + e.LastVisibleItemIndex);
}

Neste exemplo, o OnCollectionViewScrolled manipulador de eventos gera os valores do ItemsViewScrolledEventArgs objeto que acompanha o evento.In this example, the OnCollectionViewScrolled event handler outputs the values of the ItemsViewScrolledEventArgs object that accompanies the event.

Importante

O Scrolled evento é acionado para rolagens iniciadas pelo usuário e para rolagens programáticas.The Scrolled event is fired for user initiated scrolls, and for programmatic scrolls.

Rolar um item em um índice para a exibiçãoScroll an item at an index into view

A primeira ScrollTo sobrecarga do método rola o item no índice especificado para a exibição.The first ScrollTo method overload scrolls the item at the specified index into view. Dado um CollectionView objeto chamado collectionView , o exemplo a seguir mostra como rolar o item no índice 12 para a exibição:Given a CollectionView object named collectionView, the following example shows how to scroll the item at index 12 into view:

collectionView.ScrollTo(12);

Como alternativa, um item em dados agrupados pode ser rolado para a exibição, especificando os índices de item e de grupo.Alternatively, an item in grouped data can be scrolled into view by specifying the item and group indexes. O exemplo a seguir mostra como rolar o terceiro item no segundo grupo para a exibição:The following example shows how to scroll the third item in the second group into view:

// Items and groups are indexed from zero.
collectionView.ScrollTo(2, 1);

Observação

O ScrollToRequested evento é acionado quando o ScrollTo método é invocado.The ScrollToRequested event is fired when the ScrollTo method is invoked.

Rolar um item para a exibiçãoScroll an item into view

A sobrecarga do segundo ScrollTo método rola o item especificado para a exibição.The second ScrollTo method overload scrolls the specified item into view. Dado um CollectionView objeto chamado collectionView , o exemplo a seguir mostra como rolar o item de macaco Proboscis para a exibição:Given a CollectionView object named collectionView, the following example shows how to scroll the Proboscis Monkey item into view:

MonkeysViewModel viewModel = BindingContext as MonkeysViewModel;
Monkey monkey = viewModel.Monkeys.FirstOrDefault(m => m.Name == "Proboscis Monkey");
collectionView.ScrollTo(monkey);

Como alternativa, um item em dados agrupados pode ser rolado para a exibição, especificando o item e o grupo.Alternatively, an item in grouped data can be scrolled into view by specifying the item and the group. O exemplo a seguir mostra como rolar o item de macaco Proboscis no grupo Monkeys para a exibição:The following example shows how to scroll the Proboscis Monkey item in the Monkeys group into view:

GroupedAnimalsViewModel viewModel = BindingContext as GroupedAnimalsViewModel;
AnimalGroup group = viewModel.Animals.FirstOrDefault(a => a.Name == "Monkeys");
Animal monkey = group.FirstOrDefault(m => m.Name == "Proboscis Monkey");
collectionView.ScrollTo(monkey, group);

Observação

O ScrollToRequested evento é acionado quando o ScrollTo método é invocado.The ScrollToRequested event is fired when the ScrollTo method is invoked.

Desabilitar animação de rolagemDisable scroll animation

Uma animação de rolagem é exibida ao rolar um item para a exibição.A scrolling animation is displayed when scrolling an item into view. No entanto, essa animação pode ser desabilitada definindo o animate argumento do ScrollTo método como false :However, this animation can be disabled by setting the animate argument of the ScrollTo method to false:

collectionView.ScrollTo(monkey, animate: false);

Posição de rolagem de controleControl scroll position

Ao rolar um item para a exibição, a posição exata do item após a rolagem concluída pode ser especificada com o position argumento dos ScrollTo métodos.When scrolling an item into view, the exact position of the item after the scroll has completed can be specified with the position argument of the ScrollTo methods. Esse argumento aceita um ScrollToPosition membro de enumeração.This argument accepts a ScrollToPosition enumeration member.

MakeVisibleMakeVisible

O ScrollToPosition.MakeVisible membro indica que o item deve ser rolado até que fique visível na exibição:The ScrollToPosition.MakeVisible member indicates that the item should be scrolled until it's visible in the view:

collectionView.ScrollTo(monkey, position: ScrollToPosition.MakeVisible);

Este código de exemplo resulta na rolagem mínima necessária para rolar o item para a exibição:This example code results in the minimal scrolling required to scroll the item into view:

Captura de tela de uma lista vertical CollectionView com ScrollToPosition. MakeVisible, no iOS e no AndroidScreenshot of a CollectionView vertical list with ScrollToPosition.MakeVisible, on iOS and Android

Observação

O ScrollToPosition.MakeVisible membro será usado por padrão, se o position argumento não for especificado ao chamar o ScrollTo método.The ScrollToPosition.MakeVisible member is used by default, if the position argument is not specified when calling the ScrollTo method.

IniciarStart

O ScrollToPosition.Start membro indica que o item deve ser rolado até o início da exibição:The ScrollToPosition.Start member indicates that the item should be scrolled to the start of the view:

collectionView.ScrollTo(monkey, position: ScrollToPosition.Start);

Este código de exemplo resulta no item que está sendo rolado para o início da exibição:This example code results in the item being scrolled to the start of the view:

Captura de tela de uma lista vertical CollectionView com ScrollToPosition. Start, no iOS e no AndroidScreenshot of a CollectionView vertical list with ScrollToPosition.Start, on iOS and Android

CentroCenter

O ScrollToPosition.Center membro indica que o item deve ser rolado para o centro da exibição:The ScrollToPosition.Center member indicates that the item should be scrolled to the center of the view:

collectionView.ScrollTo(monkey, position: ScrollToPosition.Center);

Este código de exemplo resulta no item que está sendo rolado para o centro da exibição:This example code results in the item being scrolled to the center of the view:

Captura de tela de uma lista vertical CollectionView com ScrollToPosition. Center, no iOS e no AndroidScreenshot of a CollectionView vertical list with ScrollToPosition.Center, on iOS and Android

EndEnd

O ScrollToPosition.End membro indica que o item deve ser rolado para o final da exibição:The ScrollToPosition.End member indicates that the item should be scrolled to the end of the view:

collectionView.ScrollTo(monkey, position: ScrollToPosition.End);

Este código de exemplo resulta no item que está sendo rolado para o final da exibição:This example code results in the item being scrolled to the end of the view:

Captura de tela de uma lista vertical CollectionView com ScrollToPosition. end, no iOS e no AndroidScreenshot of a CollectionView vertical list with ScrollToPosition.End, on iOS and Android

Controlar a posição de rolagem quando novos itens forem adicionadosControl scroll position when new items are added

CollectionView define uma ItemsUpdatingScrollMode propriedade, que é apoiada por uma propriedade vinculável.CollectionView defines a ItemsUpdatingScrollMode property, which is backed by a bindable property. Essa propriedade Obtém ou define um ItemsUpdatingScrollMode valor de enumeração que representa o comportamento de rolagem do CollectionView quando novos itens são adicionados a ele.This property gets or sets a ItemsUpdatingScrollMode enumeration value that represents the scrolling behavior of the CollectionView when new items are added to it. A enumeração ItemsUpdatingScrollMode define os seguintes membros:The ItemsUpdatingScrollMode enumeration defines the following members:

  • KeepItemsInView mantém o primeiro item na lista exibido quando novos itens são adicionados.KeepItemsInView keeps the first item in the list displayed when new items are added.
  • KeepScrollOffset garante que a posição de rolagem atual seja mantida quando novos itens forem adicionados.KeepScrollOffset ensures that the current scroll position is maintained when new items are added.
  • KeepLastItemInView ajusta o deslocamento de rolagem para manter o último item da lista exibido quando novos itens são adicionados.KeepLastItemInView adjusts the scroll offset to keep the last item in the list displayed when new items are added.

O valor padrão da ItemsUpdatingScrollMode propriedade é KeepItemsInView .The default value of the ItemsUpdatingScrollMode property is KeepItemsInView. Portanto, quando novos itens forem adicionados a um CollectionView primeiro item da lista, permanecerão exibidos.Therefore, when new items are added to a CollectionView the first item in the list will remain displayed. Para garantir que o último item da lista seja exibido quando novos itens forem adicionados, defina a ItemsUpdatingScrollMode propriedade como KeepLastItemInView :To ensure that the last item in the list is displayed when new items are added, set the ItemsUpdatingScrollMode property to KeepLastItemInView:

<CollectionView ItemsUpdatingScrollMode="KeepLastItemInView">
    ...
</CollectionView>

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

CollectionView collectionView = new CollectionView
{
    ItemsUpdatingScrollMode = ItemsUpdatingScrollMode.KeepLastItemInView
};

Visibilidade da barra de rolagemScroll bar visibility

CollectionView define HorizontalScrollBarVisibility e VerticalScrollBarVisibility Propriedades, que são apoiadas por propriedades vinculáveis.CollectionView defines HorizontalScrollBarVisibility and VerticalScrollBarVisibility properties, which are backed by bindable properties. Essas propriedades obtêm ou definem um ScrollBarVisibility valor de enumeração que representa quando a barra de rolagem horizontal ou vertical é visível.These properties get or set a ScrollBarVisibility enumeration value that represents when the horizontal, or vertical, scroll bar is visible. A enumeração ScrollBarVisibility define os seguintes membros:The ScrollBarVisibility enumeration defines the following members:

  • Default indica o comportamento da barra de rolagem padrão para a plataforma e é o valor padrão para as HorizontalScrollBarVisibility VerticalScrollBarVisibility Propriedades e.Default indicates the default scroll bar behavior for the platform, and is the default value for the HorizontalScrollBarVisibility and VerticalScrollBarVisibility properties.
  • Always indica que as barras de rolagem estarão visíveis, mesmo quando o conteúdo couber na exibição.Always indicates that scroll bars will be visible, even when the content fits in the view.
  • Never indica que as barras de rolagem não estarão visíveis, mesmo se o conteúdo não couber na exibição.Never indicates that scroll bars will not be visible, even if the content doesn't fit in the view.

Pontos de ajusteSnap points

Quando um usuário passa o dedo para iniciar uma rolagem, a posição final da rolagem pode ser controlada para que os itens sejam totalmente exibidos.When a user swipes to initiate a scroll, the end position of the scroll can be controlled so that items are fully displayed. Esse recurso é conhecido como encaixe, pois os itens se ajustam à posição quando a rolagem é interrompida e é controlado pelas seguintes propriedades da ItemsLayout classe:This feature is known as snapping, because items snap to position when scrolling stops, and is controlled by the following properties from the ItemsLayout class:

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

Quando o ajuste ocorre, ele ocorrerá na direção que produz a menor quantidade de movimentos.When snapping occurs, it will occur in the direction that produces the least amount of motion.

Tipo de pontos de ajusteSnap points type

A SnapPointsType enumeração define os seguintes membros:The SnapPointsType enumeration defines the following members:

  • None indica que a rolagem não se ajusta aos itens.None indicates that scrolling does not snap to items.
  • Mandatory indica que o conteúdo sempre se ajusta ao ponto de ajuste mais próximo para onde a rolagem seria interrompida naturalmente, ao longo da direção de inércia.Mandatory indicates that content always snaps to the closest snap point to where scrolling would naturally stop, along the direction of inertia.
  • MandatorySingle indica o mesmo comportamento que Mandatory , mas apenas rola um item de cada vez.MandatorySingle indicates the same behavior as Mandatory, but only scrolls one item at a time.

Por padrão, a SnapPointsType propriedade é definida como SnapPointsType.None , o que garante que a rolagem não enencaixe itens, conforme mostrado nas capturas de tela a seguir:By default, the SnapPointsType property is set to SnapPointsType.None, which ensures that scrolling does not snap items, as shown in the following screenshots:

Captura de tela de uma lista vertical CollectionView sem pontos de ajuste, no iOS e no AndroidScreenshot of a CollectionView vertical list without snap points, on iOS and Android

Alinhamento dos pontos de ajusteSnap points alignment

A SnapPointsAlignment enumeração define Start Center End os membros, e.The SnapPointsAlignment enumeration defines Start, Center, and End members.

Importante

O valor da SnapPointsAlignment propriedade é respeitado somente quando a SnapPointsType propriedade é definida como Mandatory , ou MandatorySingle .The value of the SnapPointsAlignment property is only respected when the SnapPointsType property is set to Mandatory, or MandatorySingle.

IniciarStart

O SnapPointsAlignment.Start membro indica que os pontos de ajuste estão alinhados com a borda à esquerda dos itens.The SnapPointsAlignment.Start member indicates that snap points are aligned with the leading edge of items.

Por padrão, a SnapPointsAlignment propriedade é definida como SnapPointsAlignment.Start .By default, the SnapPointsAlignment property is set to SnapPointsAlignment.Start. No entanto, para fins de integridade, o exemplo XAML a seguir mostra como definir esse membro de enumeração:However, for completeness, the following XAML example shows how to set this enumeration member:

<CollectionView ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemsLayout>
        <LinearItemsLayout Orientation="Vertical"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="Start" />
    </CollectionView.ItemsLayout>
    ...
</CollectionView>

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

CollectionView collectionView = new CollectionView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Vertical)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.Start
    },
    // ...
};

Quando um usuário passa o dedo para iniciar uma rolagem, o item superior será alinhado com a parte superior da exibição:When a user swipes to initiate a scroll, the top item will be aligned with the top of the view:

Captura de tela de uma lista vertical de CollectionView com pontos de partida de início, no iOS e no AndroidScreenshot of a CollectionView vertical list with start snap points, on iOS and Android

CentroCenter

O SnapPointsAlignment.Center membro indica que os pontos de ajuste estão alinhados ao centro dos itens.The SnapPointsAlignment.Center member indicates that snap points are aligned with the center of items. O exemplo de XAML a seguir mostra como definir esse membro de enumeração:The following XAML example shows how to set this enumeration member:

<CollectionView ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemsLayout>
        <LinearItemsLayout Orientation="Vertical"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="Center" />
    </CollectionView.ItemsLayout>
    ...
</CollectionView>

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

CollectionView collectionView = new CollectionView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Vertical)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.Center
    },
    // ...
};

Quando um usuário passa o dedo para iniciar uma rolagem, o item superior será alinhado ao centro na parte superior da exibição:When a user swipes to initiate a scroll, the top item will be center aligned at the top of the view:

Captura de tela de uma lista vertical CollectionView com pontos de alinhamento do centro, no iOS e no AndroidScreenshot of a CollectionView vertical list with center snap points, on iOS and Android

EndEnd

O SnapPointsAlignment.End membro indica que os pontos de ajuste estão alinhados com a borda à direita dos itens.The SnapPointsAlignment.End member indicates that snap points are aligned with the trailing edge of items. O exemplo de XAML a seguir mostra como definir esse membro de enumeração:The following XAML example shows how to set this enumeration member:

<CollectionView ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemsLayout>
        <LinearItemsLayout Orientation="Vertical"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="End" />
    </CollectionView.ItemsLayout>
    ...
</CollectionView>

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

CollectionView collectionView = new CollectionView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Vertical)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.End
    },
    // ...
};

Quando um usuário passa o dedo para iniciar uma rolagem, o item inferior será alinhado com a parte inferior da exibição:When a user swipes to initiate a scroll, the bottom item will be aligned with the bottom of the view:

Captura de tela de uma lista vertical CollectionView com pontos de ajuste finais, no iOS e no AndroidScreenshot of a CollectionView vertical list with end snap points, on iOS and Android