Controles do visualizador de rolagem

Quando houver mais conteúdo da interface do usuário para mostrar do que você pode caber em uma área, use um controle de visualizador de rolagem.

Os visualizadores de rolagem permitem que o conteúdo se estenda além dos limites da janela de visualização (área visível). Os usuários alcançam esse conteúdo manipulando a superfície do visualizador de rolagem por meio de toque, roda do mouse, teclado ou gamepad, ou usando o cursor do mouse ou da caneta para interagir com a barra de rolagem do visualizador.

Consoante a situação, a barra de rolagem do controlo de scroll utiliza duas visualizações diferentes, mostradas na ilustração a seguir: o indicador de varrimento (à esquerda) e o cursor tradicional da barra de rolagem (à direita).

Rolagem, deslocamento e zoom

Utilize um controlo de scroll para permitir a rolagem, panorâmica e zoom do seu conteúdo.

• Rolagem: mover o conteúdo vertical ou horizontalmente arrastando o polegar da barra de rolagem ou usando a roda de rolagem em um mouse.
• Movimento panorâmico: mover conteúdo vertical ou horizontalmente usando toque ou caneta.
  • Para saber mais sobre rolagem e movimento panorâmico, veja Diretrizes para movimento panorâmico.
• Zoom: aumenta ou diminui opticamente a escala do conteúdo.
  • Para saber mais sobre zoom, veja Zoom ótico e redimensionamento.

A barra de rolagem está consciente do método de entrada do usuário e usa-o para determinar qual visualização exibir.

• Quando a região é rolada sem manipular a barra de rolagem diretamente, por exemplo, por toque, o indicador de deslocamento aparece, exibindo a posição de rolagem atual.
• Quando o cursor do mouse ou da caneta se move sobre o indicador de panorâmica, ele se transforma na barra de rolagem tradicional. Arrastar o polegar da barra de rolagem manipula a região de rolagem.

Viewport e extensão

Um visualizador de rolagem é composto por duas regiões principais que são importantes para entender sua funcionalidade. A área que abrange todo o conteúdo rolável, incluindo o oculto e o visível, é conhecida como extensão. A área visível do controlo onde o conteúdo é mostrado é o viewport.

Várias APIs estão disponíveis que permitem obter a altura e a largura dessas regiões, bem como a altura e a largura navegáveis, que é a diferença entre o tamanho da extensão total e o tamanho da área de visualização.

Recommendations

• Sempre que possível, projete para rolagem vertical em vez de horizontal.
• Utilize o deslocamento em um eixo para regiões de conteúdo que se estendem além de um limite de visualização (vertical ou horizontal). Use o movimento panorâmico de dois eixos para regiões de conteúdo que se estendem além dos limites da janela de visualização (vertical e horizontal).
• Utilize a funcionalidade de deslocamento incorporada na exibição de itens, exibição de lista, exibição de grelha, caixa de combinação, caixa de listagem, caixa de entrada de texto e nos controlos de hub. Com esses controles, se houver muitos itens para mostrar todos de uma vez, o usuário poderá rolar horizontal ou verticalmente sobre a lista de itens.
• Se você quiser que o usuário faça movimento panorâmico em ambas as direções em torno de uma área maior e, possivelmente, aplique zoom também, por exemplo, se quiser permitir que o usuário faça movimento panorâmico e zoom sobre uma imagem em tamanho real (em vez de uma imagem dimensionada para caber na tela), coloque a imagem dentro de um visualizador de rolagem.
• Se o usuário percorrer uma longa passagem de texto, configure o visualizador de rolagem para rolar apenas verticalmente.
• Use um visualizador de rolagem para conter apenas um objeto. Observe que um objeto pode ser um painel de layout, por sua vez contendo qualquer número de objetos próprios.
• Se você precisar manipular eventos de ponteiro para um UIElement em um modo de exibição rolável (como um ScrollViewer ou ListView), deverá desabilitar explicitamente o suporte para eventos de manipulação no elemento no modo de exibição chamando UIElement.CancelDirectManipulation. Para reativar eventos de manipulação no modo de exibição, chame UIElement.TryStartDirectManipulation.

Criar um visualizador de rolagem

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

Um controle de visualizador de rolagem pode ser usado para tornar o conteúdo rolável encapsulando explicitamente o conteúdo no visualizador de rolagem ou colocando um visualizador de rolagem no modelo de controle de um controle de conteúdo.

Visualizador de rolagem em um modelo de controle

É típico que um controle de visualizador de rolagem exista como uma parte composta de outros controles. Uma parte do visualizador de rolagem exibirá uma janela de visualização junto com barras de rolagem somente quando o espaço de layout do controle de host estiver sendo restringido menor do que o tamanho do conteúdo expandido.

ItemsView inclui um ScrollView controle em seu modelo. Você pode acessar a ScrollView através da propriedade ItemsView.ScrollView.

ListView e GridView templates sempre incluem um ScrollViewer. TextBox e RichEditBox também incluem um ScrollViewer em seus modelos. Para influenciar alguns dos comportamentos e propriedades da parte integrada ScrollViewer, ScrollViewer define várias propriedades anexadas XAML que podem ser definidas em estilos e usadas em ligações de modelo. Para saber mais sobre propriedades anexadas, veja Visão geral das propriedades anexadas.

Definir conteúdo rolável

O conteúdo dentro de um visualizador de rolagem torna-se rolável quando é maior do que a janela de visualização do visualizador de rolagem

Este exemplo define a Rectangle como o conteúdo do ScrollView controle. O usuário vê apenas uma parte de 500x400 desse retângulo e pode rolar para ver o resto dele.

<ScrollView Width="500" Height="400">
    <Rectangle Width="1000" Height="800">
        <Rectangle.Fill>
            <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
                <GradientStop Color="Yellow" Offset="0.0" />
                <GradientStop Color="Red" Offset="0.25" />
                <GradientStop Color="Blue" Offset="0.75" />
                <GradientStop Color="LimeGreen" Offset="1.0" />
            </LinearGradientBrush>
        </Rectangle.Fill>
    </Rectangle>
</ScrollView>

<ScrollViewer Width="500" Height="400" HorizontalScrollBarVisibility="Auto">
    <Rectangle Width="1000" Height="800">
        <Rectangle.Fill>
            <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
                <GradientStop Color="Yellow" Offset="0.0" />
                <GradientStop Color="Red" Offset="0.25" />
                <GradientStop Color="Blue" Offset="0.75" />
                <GradientStop Color="LimeGreen" Offset="1.0" />
            </LinearGradientBrush>
        </Rectangle.Fill>
    </Rectangle>
</ScrollViewer>

Esquema

No exemplo anterior, o tamanho do retângulo é explicitamente definido como maior do que o visualizador de rolagem. Nos casos em que o conteúdo do visualizador de rolagem pode crescer naturalmente, como em uma lista ou bloco de texto, você pode configurar o visualizador de rolagem para permitir que seu conteúdo (a extensão) se expanda verticalmente, horizontalmente, ambos ou nenhum.

Por exemplo, esse bloco de texto crescerá horizontalmente até que seu contêiner pai o restrinja, depois quebrará o texto e crescerá verticalmente.

<TextBlock Text="{x:Bind someText}" TextWrapping="WrapWholeWords"/>

Quando o bloco de texto é embalado em um navegador de scroll, o navegador de scroll restringe o seu crescimento horizontal e vertical.

Visibilidade da barra de rolagem

Os controles ScrollViewer e ScrollView usam meios ligeiramente diferentes para configurar a rolagem horizontal e vertical do conteúdo.

• No controle ScrollViewer , as propriedades VerticalScrollBarVisibility e HorizontalScrollBarVisibility controlam a visibilidade das barras de rolagem e se a rolagem em uma direção específica é permitida. Quando uma propriedade é definida como Disabled, o conteúdo não pode ser rolado nessa direção pela interação do usuário.
  • Os padrões são: VerticalScrollBarVisibility="Auto", HorizontalScrollBarVisibility="Disabled"
• No controle ScrollView , as propriedades VerticalScrollBarVisibility e HorizontalScrollBarVisibility controlam apenas a visibilidade das barras de rolagem.
  • Os padrões são: VerticalScrollBarVisibility="Auto", HorizontalScrollBarVisibility="Auto"

Esta tabela descreve as opções de visibilidade para essas propriedades.

(ScrollViewer usa o enum ScrollBarVisibility ; ScrollView usa o enum ScrollingScrollBarVisibility .)

Orientação

O controle ScrollView tem uma propriedade ContentOrientation que permite controlar o layout do conteúdo. Essa propriedade determina como o conteúdo pode crescer quando não está explicitamente restrito. Se Height e Width são explicitamente definidos no conteúdo, ContentOrientation não tem efeito.

Esta tabela mostra as ContentOrientation opções para ScrollView e as configurações equivalentes para ScrollViewer.

Disposição vertical

Por padrão, o layout de conteúdo (orientação) de um visualizador de rolagem é vertical.

Neste exemplo, um ItemsRepeater é usado como componente do Content. O UniformGridLayout para o ItemsRepeater posiciona os itens horizontalmente em uma linha até que fique sem espaço (500px neste exemplo) e, em seguida, posiciona o próximo item na próxima linha. O ItemsRepeater pode ser mais alto do que os 400px que o usuário pode ver, mas o usuário pode rolar o conteúdo verticalmente.

<ScrollView Width="500" Height="400">
    <ItemsRepeater ItemsSource="{x:Bind Albums}"
                   ItemTemplate="{StaticResource MyTemplate}">
        <ItemsRepeater.Layout>
            <UniformGridLayout RowSpacing="8" ColumnSpacing="8"/>
        </ItemsRepeater.Layout>
    </ItemsRepeater>
</ScrollView>

<ScrollViewer Width="500" Height="400">
    <ItemsRepeater ItemsSource="{x:Bind Albums}"
                   ItemTemplate="{StaticResource MyTemplate}">
        <ItemsRepeater.Layout>
            <UniformGridLayout RowSpacing="8" ColumnSpacing="8"/>
        </ItemsRepeater.Layout>
    </ItemsRepeater>
</ScrollViewer>

Disposição horizontal

Neste exemplo, o conteúdo é um StackPanel que está organizando os seus itens de forma horizontal. A configuração do visualizador de rolagem é alterada para suportar a rolagem horizontal e desabilitar a rolagem vertical.

<ScrollView Width="500" Height="400" ContentOrientation="Horizontal">
    <StackPanel Orientation="Horizontal">
        <Button Width="200" Content="Button 1"/>
        <Button Width="200" Content="Button 2"/>
        <Button Width="200" Content="Button 3"/>
        <Button Width="200" Content="Button 4"/>
        <Button Width="200" Content="Button 5"/>
    </StackPanel>
</ScrollView>

<ScrollViewer Width="500" Height="400"
    HorizontalScrollBarVisibility="Auto" VerticalScrollBarVisibility="Disabled">
    <StackPanel Orientation="Horizontal">
        <Button Width="200" Content="Button 1"/>
        <Button Width="200" Content="Button 2"/>
        <Button Width="200" Content="Button 3"/>
        <Button Width="200" Content="Button 4"/>
        <Button Width="200" Content="Button 5"/>
    </StackPanel>
</ScrollViewer>

Rolagem programática

As propriedades de deslocamento do visualizador de rolagem são somente leitura, mas os métodos são fornecidos para permitir que você role programaticamente.

<Button Content="Scroll to top" Click="ScrollTopButton_Click"/>
<Button Content="Scroll to bottom" Click="ScrollBottomButton_Click"/>
<ScrollView x:Name="scrollView" Width="500" Height="400">
    <StackPanel>
        <Button Width="200" Content="Button 1"/>
        <Button Width="200" Content="Button 2"/>
        <Button Width="200" Content="Button 3"/>
        <Button Width="200" Content="Button 4"/>
        <Button Width="200" Content="Button 5"/>
    </StackPanel>
</ScrollView>

private void ScrollTopButton_Click(object sender, RoutedEventArgs e)
{
    scrollView.ScrollTo(
        horizontalOffset: scrollView.HorizontalOffset,
        verticalOffset: 0);
}

private void ScrollBottomButton_Click(object sender, RoutedEventArgs e)
{
    scrollView.ScrollTo(
        horizontalOffset: scrollView.HorizontalOffset,
        verticalOffset: scrollView.ScrollableHeight);
}

<Button Content="Scroll to top" Click="ScrollTopButton_Click"/>
<Button Content="Scroll to bottom" Click="ScrollBottomButton_Click"/>
<ScrollView Width="500" Height="400">
    <StackPanel>
        <Button Width="200" Content="Button 1"/>
        <Button Width="200" Content="Button 2"/>
        <Button Width="200" Content="Button 3"/>
        <Button Width="200" Content="Button 4"/>
        <Button Width="200" Content="Button 5"/>
    </StackPanel>
</ScrollView>

private void ScrollTopButton_Click(object sender, RoutedEventArgs e)
{
    scrollViewer.ChangeView(
        horizontalOffset: null,
        verticalOffset: 0,
        zoomFactor: null);
}

private void ScrollBottomButton_Click(object sender, RoutedEventArgs e)
{
    scrollViewer.ChangeView(
        horizontalOffset: null,
        verticalOffset: scrollViewer.ScrollableHeight,
        zoomFactor: null);
}

Zoom

Você pode usar um visualizador de rolagem para permitir que um usuário aumente e diminua opticamente o zoom do conteúdo. As interações de zoom ótico são realizadas através dos gestos de pinçar e esticar (mover os dedos para mais longe aumenta o zoom e aproximá-los diminui o zoom) ou pressionando a tecla Ctrl enquanto rola a roda de rolagem do mouse. Para saber mais sobre zoom, veja Zoom ótico e redimensionamento.

Para habilitar o zoom por interação do usuário, defina a ZoomMode propriedade como Enabled (é Disabled por padrão). As alterações na ZoomMode propriedade entram em vigor imediatamente e podem afetar uma interação contínua do usuário.

Este exemplo mostra uma Imagem encapsulada em um visualizador de rolagem configurado para permitir zoom.

<ScrollView Width="500" Height="400"
            ContentOrientation="Both"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.jpg"/>
</ScrollView>

<ScrollViewer Width="500" Height="400" 
              HorizontalScrollBarVisibility="Auto"
              ZoomMode="Enabled">
    <Image Source="Assets/rainier.jpg"/>
</ScrollViewer>

<ScrollView Width="500" Height="400"
            ContentOrientation="None"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.jpg"/>
</ScrollView>

 <ScrollViewer x:Name="scrollControl" Width="500" Height="400"
               HorizontalScrollBarVisibility="Auto" 
               VerticalScrollBarVisibility="Auto" 
               ZoomMode="Enabled">
     <Viewbox MaxWidth="{x:Bind scrollControl.ViewportWidth, Mode=OneWay}"  
              MaxHeight="{x:Bind scrollControl.ViewportHeight, Mode=OneWay}">
         <Image Source="Assets/rainier.jpg"/>
     </Viewbox>
 </ScrollViewer>

Fator de zoom

Use as propriedades MinZoomFactor e MaxZoomFactor para controlar quanto o utilizador pode ampliar o conteúdo. Essas propriedades são eficazes para interações do usuário e zoom programático.

• Os padrões são: MinZoomFactor="0.1", MaxZoomFactor="10.0"

<ScrollView Width="500" Height="400"
            ContentOrientation="Both"
            ZoomMode="Enabled" 
            MinZoomFactor="1.0" MaxZoomFactor="8.0">
    <Image Source="Assets/rainier.png"/>
</ScrollView>

<ScrollViewer Width="500" Height="400"
              HorizontalScrollBarVisibility="Auto"
              ZoomMode="Enabled"
              MinZoomFactor="1.0" MaxZoomFactor="8.0">
    <Image Source="Assets/rainier.png"/>
</ScrollViewer>

Zoom programático

A propriedade ZoomFactor é de leitura exclusiva, mas existem métodos que permitem aplicar zoom programaticamente. Um uso típico para isso é ligar o scroll viewer a um slider que controla o nível de zoom ou a um botão para redefinir o zoom. (Consulte ScrollViewer no aplicativo WinUI 3 Gallery para ver um exemplo de um controle deslizante de zoom.)

<Slider Header="Zoom" IsEnabled="True"
        Maximum="{x:Bind scrollControl.MaxZoomFactor, Mode=OneWay}"
        Minimum="{x:Bind scrollControl.MinZoomFactor, Mode=OneWay}"
        StepFrequency="0.1"
        ValueChanged="ZoomSlider_ValueChanged" />
<ScrollView Width="500" Height="400"
            ContentOrientation="None"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.png"/>
</ScrollView>

private void ZoomSlider_ValueChanged(object sender, RangeBaseValueChangedEventArgs e)
{
    if (scrollControl != null)
    {
        scrollControl.ZoomTo(
            zoomFactor: (float)e.NewValue,
            centerPoint: null)
    }
}

<Slider Header="Zoom" IsEnabled="True"
        Maximum="{x:Bind scrollControl.MaxZoomFactor, Mode=OneWay}"
        Minimum="{x:Bind scrollControl.MinZoomFactor, Mode=OneWay}"
        StepFrequency="0.1"
        ValueChanged="ZoomSlider_ValueChanged" />

<ScrollViewer x:Name="scrollControl" Width="500" Height="400"
              HorizontalScrollBarVisibility="Auto"
              ZoomMode="Enabled">
    <Image Source="Assets/rainier.png"/>
</ScrollViewer>

private void ZoomSlider_ValueChanged(object sender, RangeBaseValueChangedEventArgs e)
{
    if (scrollControl != null)
    {
        scrollViewer.ChangeView(
            horizontalOffset: null,
            verticalOffset: null,
            zoomFactor: (float)e.NewValue));
    }
}

UWP e WinUI 2

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .

Recomendamos usar a WinUI 2 mais recente para obter os estilos e modelos mais atuais para todos os controles. WinUI 2.2 ou posterior inclui um novo modelo para este controle que usa cantos arredondados. Consulte Raio de cantopara obter mais informações.

Tópicos relacionados

• classe ScrollViewer