Compartilhar via

Controle de barra de rolagem anotada

Uma barra de rolagem anotada ajuda os usuários a navegar facilmente por uma grande coleção de itens. Ele substitui a barra de rolagem padrão e pode ser usado em conjunto com qualquer contêiner rolável. Essa barra de rolagem vertical permite que os usuários rolem para cima e para baixo pelos itens de uma coleção. Os usuários podem ver rótulos de categoria ao longo da área da barra de rolagem para fornecer uma referência visual de onde eles estão na coleção. Um indicador panorâmico (linha com cor de destaque) indica a posição atual do usuário na coleção. Uma dica de ferramenta é revelada quando um usuário passa o mouse sobre a área da barra de rolagem. Esta dica de ferramenta contém um rótulo para fornecer mais informações ao usuário sobre sua posição atual na coleção. As setas de rolagem estão localizadas na parte superior e inferior da área da barra de rolagem. Esses elementos podem ser usados para mover a posição atual por um pequeno incremento

Uma captura de tela que mostra uma barra de rolagem anotada no aplicativo Fotos.

A barra de rolagem anotada pode ser usada em conjunto com um controle ItemsView para recriar uma experiência de galeria de fotos. Os rótulos de categoria podem ser definidos para anos diferentes para ajudar os usuários a navegar para um local específico em sua coleção de fotos.

Interações

Ao passar o cursor, uma dica de ferramenta é revelada para exibir uma visualização desse local. Os usuários podem clicar para navegar até esse local específico. Os usuários também podem clicar e arrastar para qualquer lugar na área da barra de rolagem para navegar até uma nova posição em sua coleção. À medida que eles arrastam, o indicador de movimento panorâmico permanece conectado ao cursor do mouse e o conteúdo rola para refletir a nova posição. Os usuários também podem rolar pela coleção usando o botão de rolagem do mouse. Rolagem para cima ou para baixo na roda de rolagem do mouse move sua posição na coleção e o indicador de rolagem correspondente para cima ou para baixo em um valor fixo.

Observação

Ao contrário de um controle Barra de Rolagem, você não pode clicar e arrastar o indicador. O polegar é um elemento não interativo que serve apenas para visualizar a posição atual do viewport. O controle de posição tem uma altura fixa que não é representativa da altura da porta de visualização.

Comportamento do rótulo

  • Para experiências otimizadas para entrada por toque, os usuários podem tocar e segurar na área da barra de rolagem para ver a dica de ferramenta. A dica de ferramenta será levemente elevada para facilitar a leitura dos usuários de toque. Tocar e arrastar em qualquer lugar na área da barra de rolagem funcionará de forma semelhante a clicar e arrastar com o mouse.
  • O rótulo da dica de ferramenta nunca é truncado, pois sua finalidade é exibir texto explicativo. Em vez disso, o texto será encapsulado se ultrapassar a largura máxima da dica de ferramenta de 360px.
  • Os rótulos de categoria serão recortados se o texto for maior do que a largura da área da barra de rolagem.
  • Quando há uma colisão entre dois rótulos de categoria (por exemplo, quando o tamanho da janela diminui e dois rótulos se sobrepõem), o rótulo superior é removido. Como exceção a essa regra, o primeiro rótulo da coleção é sempre mantido, pois ajuda a indicar o alcance da coleção aos usuários. Os rótulos de categoria devem sempre ter um mínimo de 4px (2px acima, 2px abaixo) no meio, caso contrário, uma colisão de rótulo é acionada.

Esse é o controle correto?

Recomendamos usar uma barra de rolagem anotada, em vez de uma barra de rolagem padrão, ao lidar com uma grande coleção de itens ou quando uma grande quantidade de rolagem é esperada. A barra de rolagem anotada fornecerá uma maneira fácil para os usuários se localizarem em sua coleção e percorrê-la.

Para coleções que têm apenas alguns itens ou que exigem apenas uma pequena quantidade de rolagem, recomendamos o uso de uma barra de rolagem padrão.

Recommendations

  • Adicione um rótulo de categoria somente se ele fornecer informações úteis aos usuários
  • Mantenha as cadeias de caracteres usadas para os rótulos de categoria e a dica de ferramenta o mais concisas possível
  • A barra de rolagem anotada é usada da melhor forma quando há espaço vertical suficiente. O uso da barra de rolagem anotada em um espaço vertical confinado reduzirá o número de rótulos visíveis
  • Não use a barra de rolagem anotada como a única maneira de os usuários se localizarem em uma coleção. Recomendamos o uso de cabeçalhos adesivos ou rótulos de categoria em toda a coleção para complementar a barra de rolagem anotada.

Criar uma barra de rolagem anotada

Abra o aplicativo Da Galeria do WinUI 3 e veja o AnnotatedScrollBar em ação

Ícone da Galeria do WinUI 3 O aplicativo Da Galeria do WinUI 3 inclui exemplos interativos de controles e recursos do WinUI. Obtenha o aplicativo na Microsoft Store ou navegue pelo código-fonte em GitHub.

Para usar uma AnnotatedScrollBar, você precisa concluir várias etapas:

  • Conecte a AnnotatedScrollBar a um contêiner de rolagem.
  • Adicione rótulos à barra de rolagem.
  • Adicione rótulos de detalhes (dicas de ferramentas).

Conectar a AnnotatedScrollBar a um contêiner de rolagem

Para usar um AnnotatedScrollBar, conecte-o a um contêiner rolável por meio da interface IScrollController. A AnnotatedScrollBar fornece uma implementação IScrollController por meio de sua propriedade ScrollController, enquanto o ScrollView o consome por meio da propriedade ScrollPresenter (especificamente, ScrollPresenter.VerticalScrollController).

Observação

O controle ScrollView tem suporte interno para consumir a interface IScrollController. Para outros contêineres de rolagem, como ScrollViewer, você deve escrever um adaptador para IScrollController. Consulte um exemplo posteriormente neste artigo.

Aqui, a propriedade VerticalScrollController de um ItemsView está vinculada ao ScrollController de um AnnotatedScrollBar. (A propriedade ItemsView.VerticalScrollPresenter é passada para o valor ScrollPresenter.VerticalScrollController do ScrollView interno do ItemsView.)

<Grid ColumnDefinitions="*,Auto">
    <ItemsView VerticalScrollController="{x:Bind annotatedScrollBar.ScrollController}"/>
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"/>
</Grid>

Você também pode conectá-los em código, conforme mostrado aqui. Neste exemplo, um ScrollView é usado para encapsular um ItemsRepeater e oferecer funcionalidade de rolagem para ele. O AnnotatedScrollBar substitui a barra de rolagem padrão do ScrollView.

<Grid ColumnDefinitions="*, Auto">
    <ScrollView x:Name="scrollView"
                Background="LightGray" 
                MaxWidth="800" MaxHeight="500"
                VerticalScrollBarVisibility="Hidden">
        <ItemsRepeater x:Name="itemsRepeater"
                ItemsSource="{x:Bind ColorCollection}"
                Margin="2"
                SizeChanged="ItemsRepeater_SizeChanged">
            <ItemsRepeater.Layout>
                <UniformGridLayout/>
            </ItemsRepeater.Layout>
            <ItemsRepeater.ItemTemplate>
                <DataTemplate x:DataType="media:SolidColorBrush">
                    <Grid Background="{x:Bind}" Width="112" Height="82" 
                          CornerRadius="4" Margin="4"/>
                </DataTemplate>
            </ItemsRepeater.ItemTemplate>
        </ItemsRepeater>
    </ScrollView>
                
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"
        Margin="4,0,48,0" MaxHeight="500" HorizontalAlignment="Right"
        DetailLabelRequested="AnnotatedScrollBar_DetailLabelRequested"/>
</Grid>

private void AnnotatedScrollBarPage_Loaded(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
    scrollView.ScrollPresenter.VerticalScrollController = annotatedScrollBar.ScrollController;
}

Rótulos

O AnnotatedScrollBar pode exibir dois tipos de rótulos, ambos opcionais.

Rótulos da categoria

Você adiciona rótulos preenchendo a coleção Labels. Cada Label é representado pela classe AnnotatedScrollBarLabel e requer duas informações:

  • Conteúdo: o conteúdo exibido na barra de rolagem.
  • ScrollOffset: o valor de deslocamento no qual o conteúdo da etiqueta é exibido.

Os rótulos (se especificados) estão sempre visíveis na barra de rolagem, a menos que colidam com outros rótulos ou se estendam além dos limites do trilho. (Veja Comportamento do rótulo para obter mais informações.)

O cálculo do valor de deslocamento do rótulo depende dos detalhes do seu aplicativo e de seus dados. Para obter um exemplo de como o deslocamento pode ser calculado, consulte o exemplo da Galeria WinUI 3 em GitHub.

Rótulos de detalhe

Um rótulo de detalhe é um elemento de dica de ferramenta que é mostrado quando o cursor está sobre a barra de rolagem. Para criar um rótulo de detalhes, manipule o evento DetailLabelRequested. Os argumentos de evento fornecem o ScrollOffset onde o rótulo da dica de ferramenta será exibido. Use esse valor para determinar o rótulo correto a ser exibido para essa posição e defina o rótulo como a propriedade Content dos argumentos de evento.

Rolagem

O usuário pode rolar a AnnotatedScrollBar clicando nos botões de seta na parte superior e inferior da barra de rolagem. Você pode definir a propriedade SmallChange para especificar a quantidade pela qual os botões de seta rolam o conteúdo.

Você pode manipular o evento Rolagem para determinar como a rolagem está sendo executada, executar uma ação quando a rolagem ocorrer ou Cancelar a ação de rolagem.

Obter o código de exemplo

  • Last updated on