Visão geral do ScrollViewer

Artigo
12/17/2024

O conteúdo dentro de uma interface de usuário geralmente é maior do que a área de exibição da tela de um computador. O controle ScrollViewer fornece uma maneira conveniente de habilitar a rolagem de conteúdo em aplicativos do Windows Presentation Foundation (WPF). Este tópico apresenta o elemento ScrollViewer e fornece vários exemplos de uso.

O controle ScrollViewer

Há dois elementos predefinidos que permitem a rolagem em aplicativos WPF: ScrollBar e ScrollViewer. O controle ScrollViewer encapsula elementos ScrollBar horizontais e verticais e um contêiner de conteúdo (como um elemento Panel) para exibir outros elementos visíveis em uma área rolável. Você deve criar um objeto personalizado para usar o elemento ScrollBar para rolagem de conteúdo. No entanto, você pode usar o elemento ScrollViewer por si só, pois é um controle composto que encapsula ScrollBar funcionalidade.

O controle ScrollViewer responde aos comandos do mouse e do teclado e define vários métodos com os quais rolar o conteúdo por incrementos predeterminados. Você pode usar o evento ScrollChanged para detetar uma alteração em um estado ScrollViewer.

Um ScrollViewer só pode ter um filho, normalmente um elemento Panel que pode hospedar uma coleção de elementos Children. A propriedade Content define o filho único do ScrollViewer.

Rolagem física versus lógica

A rolagem física é usada para rolar o conteúdo por um incremento físico predeterminado, normalmente por um valor declarado em pixels. A rolagem lógica é usada para rolar até o próximo item na árvore lógica. A rolagem física é o comportamento de rolagem padrão para a maioria dos elementos Panel. WPF suporta ambos os tipos de rolagem.

A Interface IScrollInfo

A interface IScrollInfo representa a região de rolagem principal dentro de um controle ScrollViewer ou derivado. A interface define propriedades e métodos de rolagem que podem ser implementados por elementos Panel que exigem rolagem por unidade lógica, em vez de por um incremento físico. Converter uma instância de IScrollInfo para um Panel derivado e depois, com os seus métodos de deslocamento, fornece uma forma útil de deslocar para a próxima unidade lógica numa coleção filha, em vez de por incremento de píxeis. Por padrão, o controle ScrollViewer suporta rolagem por unidades físicas.

StackPanel e VirtualizingStackPanel implementam IScrollInfo e suportam nativamente a rolagem lógica. Para controles de layout que suportam nativamente a rolagem lógica, você ainda pode obter a rolagem física encapsulando o elemento host Panel em um ScrollViewer e definindo a propriedade CanContentScroll como false.

O exemplo de código a seguir demonstra como converter uma instância de IScrollInfo para um StackPanel e usar métodos de rolagem de conteúdo (LineUp e LineDown) definidos pela interface.

private void spLineUp(object sender, RoutedEventArgs e)
{
    ((IScrollInfo)sp1).LineUp();
}
private void spLineDown(object sender, RoutedEventArgs e)
{
    ((IScrollInfo)sp1).LineDown();
}

Private Sub spLineUp(ByVal sender As Object, ByVal args As RoutedEventArgs)

    CType(sp1, IScrollInfo).LineUp()
End Sub
Private Sub spLineDown(ByVal sender As Object, ByVal args As RoutedEventArgs)

    CType(sp1, IScrollInfo).LineDown()
End Sub

Definindo e usando um elemento ScrollViewer

O exemplo a seguir cria um ScrollViewer em uma janela que contém algum texto e um retângulo. ScrollBar elementos aparecem apenas quando são necessários. Quando você redimensiona a janela, os elementos ScrollBar aparecem e desaparecem, devido aos valores atualizados das propriedades ComputedHorizontalScrollBarVisibility e ComputedVerticalScrollBarVisibility.


// Create the application's main window
mainWindow = gcnew System::Windows::Window();
mainWindow->Title = "ScrollViewer Sample";

// Define a ScrollViewer
myScrollViewer = gcnew ScrollViewer();
myScrollViewer->HorizontalScrollBarVisibility = ScrollBarVisibility::Auto;

// Add Layout control
myStackPanel = gcnew StackPanel();
myStackPanel->HorizontalAlignment = HorizontalAlignment::Left;
myStackPanel->VerticalAlignment = VerticalAlignment::Top;

TextBlock^ myTextBlock = gcnew TextBlock();
myTextBlock->TextWrapping = TextWrapping::Wrap;
myTextBlock->Margin = System::Windows::Thickness(0, 0, 0, 20);
myTextBlock->Text = "Scrolling is enabled when it is necessary. Resize the Window, making it larger and smaller.";

Rectangle^ myRectangle = gcnew Rectangle();
myRectangle->Fill = Brushes::Red;
myRectangle->Width = 500;
myRectangle->Height = 500;

// Add child elements to the parent StackPanel
myStackPanel->Children->Add(myTextBlock);
myStackPanel->Children->Add(myRectangle);

// Add the StackPanel as the lone child of the ScrollViewer
myScrollViewer->Content = myStackPanel;

// Add the ScrollViewer as the Content of the parent Window object
mainWindow->Content = myScrollViewer;
mainWindow->Show();


// Create the application's main window
mainWindow = new Window ();
mainWindow.Title = "ScrollViewer Sample";

// Define a ScrollViewer
myScrollViewer = new ScrollViewer();
myScrollViewer.HorizontalScrollBarVisibility = ScrollBarVisibility.Auto;

// Add Layout control
myStackPanel = new StackPanel();
myStackPanel.HorizontalAlignment = HorizontalAlignment.Left;
myStackPanel.VerticalAlignment = VerticalAlignment.Top;

TextBlock myTextBlock = new TextBlock();
myTextBlock.TextWrapping = TextWrapping.Wrap;
myTextBlock.Margin = new Thickness(0, 0, 0, 20);
myTextBlock.Text = "Scrolling is enabled when it is necessary. Resize the Window, making it larger and smaller.";

Rectangle myRectangle = new Rectangle();
myRectangle.Fill = Brushes.Red;
myRectangle.Width = 500;
myRectangle.Height = 500;

// Add child elements to the parent StackPanel
myStackPanel.Children.Add(myTextBlock);
myStackPanel.Children.Add(myRectangle);

// Add the StackPanel as the lone child of the ScrollViewer
myScrollViewer.Content = myStackPanel;

// Add the ScrollViewer as the Content of the parent Window object
mainWindow.Content = myScrollViewer;
mainWindow.Show ();


'Define a ScrollViewer.
Dim myScrollViewer As New ScrollViewer
myScrollViewer.HorizontalScrollBarVisibility = ScrollBarVisibility.Auto

'Add Layout control.
Dim myStackPanel As New StackPanel
myStackPanel.HorizontalAlignment = System.Windows.HorizontalAlignment.Left
myStackPanel.VerticalAlignment = System.Windows.VerticalAlignment.Top

Dim myTextBlock As New TextBlock
myTextBlock.TextWrapping = TextWrapping.Wrap
myTextBlock.Margin = New Thickness(0, 0, 0, 20)
myTextBlock.Text = "Scrolling is enabled when it is necessary. Resize the Window, making it larger and smaller."

Dim myRectangle As New Rectangle
myRectangle.Fill = Brushes.Red
myRectangle.Width = 500
myRectangle.Height = 500

'Add child elements to the parent StackPanel.
myStackPanel.Children.Add(myTextBlock)
myStackPanel.Children.Add(myRectangle)

'Add the StackPanel as the lone child of the ScrollViewer
myScrollViewer.Content = myStackPanel

'Add the ScrollViewer as the Content of the parent Window object
Me.Content = myScrollViewer

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      WindowTitle="ScrollViewer Sample">
  <ScrollViewer HorizontalScrollBarVisibility="Auto">
    <StackPanel VerticalAlignment="Top" HorizontalAlignment="Left">
      <TextBlock TextWrapping="Wrap" Margin="0,0,0,20">Scrolling is enabled when it is necessary. 
      Resize the window, making it larger and smaller.</TextBlock>
      <Rectangle Fill="Red" Width="500" Height="500"></Rectangle>
    </StackPanel>
  </ScrollViewer>
</Page>

Estilizando um ScrollViewer

Como todos os controles no Windows Presentation Foundation, o ScrollViewer pode ser estilizado para alterar o comportamento de renderização padrão do controle. Para obter informações adicionais sobre a formatação dos controlos, consulte Styling and Templating.

Paginando documentos

Para o conteúdo do documento, uma alternativa à rolagem é escolher um contêiner de documento que ofereça suporte à paginação. FlowDocument é para documentos projetados para serem hospedados em um controle de visualização, como FlowDocumentPageViewer, que suporta a paginação de conteúdo em várias páginas, evitando a necessidade de rolagem. DocumentViewer fornece uma solução para visualizar conteúdos de FixedDocument, utilizando a rolagem tradicional para exibir conteúdo além dos limites da área de visualização.

Para obter informações adicionais sobre formatos de documentos e opções de apresentação, consulte documentos no WPF.

Partilhar via