Xamarin.Forms Scrollview

Baixar exemplo Baixar o exemplo

Xamarin.Forms ScrollView

ScrollView é um layout capaz de rolar seu conteúdo. A ScrollView classe deriva da Layout classe e, por padrão, rola seu conteúdo verticalmente. Um ScrollView só pode ter um único filho, embora isso possa ser outros layouts.

Aviso

ScrollView os objetos não devem ser aninhados. Além disso, ScrollView os objetos não devem ser aninhados com outros controles que fornecem rolagem, como CollectionView, ListViewe WebView.

ScrollView define as propriedades a seguir:

Essas propriedades são apoiadas por BindableProperty objetos, com exceção da propriedade , o Content que significa que elas podem ser destinos de associações de dados e estilizadas.

A Content propriedade é da ContentPropertyScrollView classe e, portanto, não precisa ser definida explicitamente a partir de XAML.

Dica

Para obter o melhor desempenho de layout possível, siga as diretrizes em Otimizar o desempenho do layout.

ScrollView como um layout raiz

Um ScrollView só pode ter um único filho, que pode ser outros layouts. Portanto, é comum que um ScrollView seja o layout raiz em uma página. Para rolar seu conteúdo filho, ScrollView calcula a diferença entre a altura de seu conteúdo e sua própria altura. Essa diferença é a quantidade que o ScrollView pode rolar seu conteúdo.

Um StackLayout geralmente será o filho de um ScrollView. Nesse cenário, o ScrollView faz com que o StackLayout seja tão alto quanto a soma das alturas de seus filhos. Em seguida, o ScrollView pode determinar a quantidade que seu conteúdo pode ser rolado. Para obter mais informações sobre o StackLayout, consulte Xamarin.Forms StackLayout.

Cuidado

Em um vertical ScrollView, evite definir a VerticalOptions propriedade como Start, Centerou End. Fazer isso diz ao ScrollView para ser tão alto quanto precisa ser, o que pode ser zero. Embora Xamarin.Forms proteja contra essa eventualidade, é melhor evitar código que sugira algo que você não deseja que aconteça.

O exemplo XAML a seguir tem um ScrollView como layout raiz em uma página:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:ScrollViewDemos"
             x:Class="ScrollViewDemos.Views.ColorListPage"
             Title="ScrollView demo">
    <ScrollView>
        <StackLayout BindableLayout.ItemsSource="{x:Static local:NamedColor.All}">
            <BindableLayout.ItemTemplate>
                <DataTemplate>
                    <StackLayout Orientation="Horizontal">
                        <BoxView Color="{Binding Color}"
                                 HeightRequest="32"
                                 WidthRequest="32"
                                 VerticalOptions="Center" />
                        <Label Text="{Binding FriendlyName}"
                               FontSize="24"
                               VerticalOptions="Center" />
                    </StackLayout>
                </DataTemplate>
            </BindableLayout.ItemTemplate>
        </StackLayout>
    </ScrollView>
</ContentPage>

Neste exemplo, o tem seu ScrollView conteúdo definido como um StackLayout que usa um layout associável para exibir os Color campos definidos por Xamarin.Forms. Por padrão, um ScrollView rola verticalmente, o que revela mais conteúdo:

Captura de tela de um layout de ScrollView raiz Layout

Este é o código C# equivalente:

public class ColorListPageCode : ContentPage
{
    public ColorListPageCode()
    {
        DataTemplate dataTemplate = new DataTemplate(() =>
        {
            BoxView boxView = new BoxView
            {
                HeightRequest = 32,
                WidthRequest = 32,
                VerticalOptions = LayoutOptions.Center
            };
            boxView.SetBinding(BoxView.ColorProperty, "Color");

            Label label = new Label
            {
                FontSize = 24,
                VerticalOptions = LayoutOptions.Center
            };
            label.SetBinding(Label.TextProperty, "FriendlyName");

            StackLayout horizontalStackLayout = new StackLayout
            {
                Orientation = StackOrientation.Horizontal,
                Children = { boxView, label }
            };
            return horizontalStackLayout;
        });

        StackLayout stackLayout = new StackLayout();
        BindableLayout.SetItemsSource(stackLayout, NamedColor.All);
        BindableLayout.SetItemTemplate(stackLayout, dataTemplate);

        ScrollView scrollView = new ScrollView { Content = stackLayout };

        Title = "ScrollView demo";
        Content = scrollView;
    }
}

Para obter mais informações sobre layouts associáveis, consulte Layouts associáveis em Xamarin.Forms.

ScrollView como um layout filho

Um ScrollView pode ser um layout filho para um layout pai diferente.

Um ScrollView geralmente será o filho de um StackLayout. Um ScrollView requer uma altura específica para calcular a diferença entre a altura de seu conteúdo e sua própria altura, com a diferença sendo a quantidade que o ScrollView pode rolar seu conteúdo. Quando um ScrollView é filho de um StackLayout, ele não recebe uma altura específica. O StackLayout deseja que o seja o ScrollView mais curto possível, que é a altura do ScrollView conteúdo ou zero. Para lidar com esse cenário, a VerticalOptions propriedade do ScrollView deve ser definida como FillAndExpand. Isso fará com que o StackLayout dê todo o ScrollView espaço extra não exigido pelos outros filhos e o ScrollView terá uma altura específica.

O exemplo XAML a seguir tem um ScrollView layout como filho para um StackLayout:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ScrollViewDemos.Views.BlackCatPage"
             Title="ScrollView as a child layout demo">
    <StackLayout Margin="20">
        <Label Text="THE BLACK CAT by Edgar Allan Poe"
               FontSize="Medium"
               FontAttributes="Bold"
               HorizontalOptions="Center" />
        <ScrollView VerticalOptions="FillAndExpand">
            <StackLayout>
                <Label Text="FOR the most wild, yet most homely narrative which I am about to pen, I neither expect nor solicit belief. Mad indeed would I be to expect it, in a case where my very senses reject their own evidence. Yet, mad am I not -- and very surely do I not dream. But to-morrow I die, and to-day I would unburthen my soul. My immediate purpose is to place before the world, plainly, succinctly, and without comment, a series of mere household events. In their consequences, these events have terrified -- have tortured -- have destroyed me. Yet I will not attempt to expound them. To me, they have presented little but Horror -- to many they will seem less terrible than barroques. Hereafter, perhaps, some intellect may be found which will reduce my phantasm to the common-place -- some intellect more calm, more logical, and far less excitable than my own, which will perceive, in the circumstances I detail with awe, nothing more than an ordinary succession of very natural causes and effects." />
                <!-- More Label objects go here -->
            </StackLayout>
        </ScrollView>
    </StackLayout>
</ContentPage>

Neste exemplo, há dois StackLayout objetos. O primeiro StackLayout é o objeto de layout raiz, que tem um Label objeto e um ScrollView como seus filhos. O ScrollView tem um StackLayout como seu conteúdo, com o StackLayout que contém vários Label objetos. Essa disposição garante que o primeiro Label esteja sempre na tela, enquanto o texto exibido pelos outros Label objetos pode ser rolado:

Captura de tela de um layout de ScrollView filho

Este é o código C# equivalente:

public class BlackCatPageCS : ContentPage
{
    public BlackCatPageCS()
    {
        Label titleLabel = new Label
        {
            Text = "THE BLACK CAT by Edgar Allan Poe",
            // More properties set here to define the Label appearance
        };

        ScrollView scrollView = new ScrollView
        {
            VerticalOptions = LayoutOptions.FillAndExpand,
            Content = new StackLayout
            {
                Children =
                {
                    new Label
                    {
                        Text = "FOR the most wild, yet most homely narrative which I am about to pen, I neither expect nor solicit belief. Mad indeed would I be to expect it, in a case where my very senses reject their own evidence. Yet, mad am I not -- and very surely do I not dream. But to-morrow I die, and to-day I would unburthen my soul. My immediate purpose is to place before the world, plainly, succinctly, and without comment, a series of mere household events. In their consequences, these events have terrified -- have tortured -- have destroyed me. Yet I will not attempt to expound them. To me, they have presented little but Horror -- to many they will seem less terrible than barroques. Hereafter, perhaps, some intellect may be found which will reduce my phantasm to the common-place -- some intellect more calm, more logical, and far less excitable than my own, which will perceive, in the circumstances I detail with awe, nothing more than an ordinary succession of very natural causes and effects.",
                    },
                    // More Label objects go here
                }
            }
        };

        Title = "ScrollView as a child layout demo";
        Content = new StackLayout
        {
            Margin = new Thickness(20),
            Children = { titleLabel, scrollView }
        };
    }
}

Orientation

ScrollView tem uma Orientation propriedade , que representa a direção de rolagem do ScrollView. Essa propriedade é do tipo ScrollOrientation, que define os seguintes membros:

  • Vertical indica que o ScrollView rolará verticalmente. Esse membro é o valor padrão da Orientation propriedade .
  • Horizontal indica que o ScrollView rolará horizontalmente.
  • Both indica que o ScrollView rolará horizontal e verticalmente.
  • Neither indica que o ScrollView não rolará.

Dica

A rolagem pode ser desabilitada definindo a Orientation propriedade como Neither.

Detectar rolagem

ScrollView define um Scrolled evento que é disparado para indicar que a rolagem ocorreu. O ScrolledEventArgs objeto que acompanha o Scrolled evento tem ScrollX propriedades e ScrollY , ambos do tipo double.

Importante

As ScrolledEventArgs.ScrollX propriedades e ScrolledEventArgs.ScrollY podem ter valores negativos, devido ao efeito de recuperação que ocorre ao rolar de volta para o início de um ScrollView.

O exemplo XAML a seguir mostra um ScrollView que define um manipulador de eventos para o Scrolled evento:

<ScrollView Scrolled="OnScrollViewScrolled">
		...
</ScrollView>

Este é o código C# equivalente:

ScrollView scrollView = new ScrollView();
scrollView.Scrolled += OnScrollViewScrolled;

Neste exemplo, o OnScrollViewScrolled manipulador de eventos é executado quando o Scrolled evento é acionado:

void OnScrollViewScrolled(object sender, ScrolledEventArgs e)
{
    Console.WriteLine($"ScrollX: {e.ScrollX}, ScrollY: {e.ScrollY}");
}

Neste exemplo, o OnScrollViewScrolled manipulador de eventos gera os valores do ScrolledEventArgs objeto que acompanha o evento.

Observação

O Scrolled evento é acionado para rolagens iniciadas pelo usuário e para rolagens programáticas.

Rolar programaticamente

ScrollView define dois ScrollToAsync métodos, que rolam de forma assíncrona o ScrollView. Uma das sobrecargas rola para uma posição especificada no ScrollView, enquanto a outra rola um elemento especificado para a exibição. Ambas as sobrecargas têm um argumento adicional que pode ser usado para indicar se deseja animar a rolagem.

Importante

Os ScrollToAsync métodos não resultarão na rolagem quando a ScrollView.Orientation propriedade for definida Neithercomo .

Rolar uma posição para a exibição

Uma posição dentro de um ScrollView pode ser rolada para com o ScrollToAsync método que aceita doublex e y argumentos. Dado um objeto vertical ScrollView chamado scrollView, o exemplo a seguir mostra como rolar até 150 unidades independentes de dispositivo da parte superior do ScrollView:

await scrollView.ScrollToAsync(0, 150, true);

O terceiro argumento para o ScrollToAsync é o animated argumento , que determina se uma animação de rolagem é exibida ao rolar programaticamente um ScrollView.

Rolar um elemento para a exibição

Um elemento dentro de um ScrollView pode ser rolado para exibição com o ScrollToAsync método que aceita Element e ScrollToPosition argumentos. Dado um vertical ScrollView chamado scrollView, e um Label chamado label, o exemplo a seguir mostra como rolar um elemento para a exibição:

await scrollView.ScrollToAsync(label, ScrollToPosition.End, true);

O terceiro argumento para o ScrollToAsync é o animated argumento , que determina se uma animação de rolagem é exibida ao rolar programaticamente um ScrollView.

Ao rolar um elemento para a exibição, a posição exata do elemento após a conclusão da rolagem pode ser definida com o segundo argumento, position, do ScrollToAsync método . Esse argumento aceita um ScrollToPosition membro de enumeração:

  • MakeVisible indica que o elemento deve ser rolado até ficar visível no ScrollView.
  • Start indica que o elemento deve ser rolado até o início do ScrollView.
  • Center indica que o elemento deve ser rolado para o centro do ScrollView.
  • End indica que o elemento deve ser rolado até o final do ScrollView.

Visibilidade da barra de rolagem

ScrollViewdefine e VerticalScrollBarVisibility propriedades, que são apoiadas por propriedades associáveisHorizontalScrollBarVisibility. Essas propriedades obtêm ou definem um ScrollBarVisibility valor de enumeração que representa se a barra de rolagem horizontal ou vertical está visível. A enumeração ScrollBarVisibility define os seguintes membros:

  • Default indica o comportamento da barra de rolagem padrão para a plataforma e é o valor padrão das HorizontalScrollBarVisibility propriedades e VerticalScrollBarVisibility .
  • Always indica que as barras de rolagem ficarão visíveis, mesmo quando o conteúdo se ajustar à exibição.
  • Never indica que as barras de rolagem não estarão visíveis, mesmo que o conteúdo não se encaixe no modo de exibição.