Partilhar 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 em sua coleção. Um indicador de deslocamento 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 na á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. Eles 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. As etiquetas de categoria podem ser definidas para anos diferentes para ajudar os usuários a navegar para um local específico dentro de sua coleção de fotos.

Interações

Ao passar o cursor, um tooltip é revelado para mostrar 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 para uma nova posição dentro de sua coleção. À medida que arrastam, o indicador de movimento panorâmico permanece ligado ao cursor do rato e o conteúdo desloca-se para refletir a nova posição. Os usuários também podem percorrer sua coleção usando a roda do mouse. Rolar para cima ou para baixo na roda do mouse move sua posição na coleção e o indicador de movimento panorâmico correspondente para cima ou para baixo em um valor fixo.

Observação

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

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á ligeiramente elevada para facilitar a leitura para utilizadores de dispositivos táteis. Tocar e arrastar em qualquer lugar na área da barra de rolagem funcionará de forma semelhante a um clique e arraste com o mouse.
  • O rótulo da dica de ferramenta nunca é truncado, pois a sua finalidade é exibir texto explicativo. Em vez disso, o texto será quebrado se ultrapassar a largura máxima de 360px da dica de ferramenta.
  • Os rótulos de categoria são cortados 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 esta regra, a primeira etiqueta da coleção é sempre mantida, 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ótulos é acionada.

Será este o controlo correto?

Recomendamos o uso de 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 tenham apenas alguns itens ou que exijam apenas uma pequena quantidade de rolagem, recomendamos o uso de uma barra de rolagem padrão.

Recommendations

  • Adicione apenas um rótulo de categoria 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 concisa possível
  • A barra de rolagem anotada é melhor usada quando há espaço vertical suficiente. Usar a 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 dentro de uma coleção. Recomendamos o uso de cabeçalhos adesivos ou etiquetas de categoria em toda a sua coleção para complementar a barra de rolagem anotada.

Criar uma barra de rolagem anotada

Abra o aplicativo WinUI 3 Gallery e veja a AnnotatedScrollBar em ação

Ícone da Galeria WinUI 3 A aplicação WinUI 3 Gallery inclui exemplos interativos de controlos e funcionalidades WinUI. Descarrega a aplicação na Microsoft Store ou navega pelo código-fonte no GitHub.

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

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

Conectar o AnnotatedScrollBar a um contêiner de rolagem

Para usar um AnnotatedScrollBar, conecte-o a um contêiner rolável por meio da interface IScrollController . O AnnotatedScrollBar fornece uma implementação IScrollController por meio de sua propriedade ScrollController , enquanto o ScrollView a consome por meio de sua 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. Veja um exemplo mais adiante 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, como mostrado aqui. Neste exemplo, um ScrollView é usado para encapsular um ItemsRepeater e fornecer 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 / Etiquetas

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

Etiqueta de 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 do rótulo é exibido.

Os rótulos (se especificados) são sempre visíveis na barra de rolagem, a menos que colidam com outros rótulos ou ultrapassem os limites do trilho. (Consulte Comportamento do rótulo para obter mais informações.)

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

Rótulos detalhados

Um rótulo de detalhe é um elemento de dica de ferramenta que aparece quando o cursor está sobre a barra de rolagem. Para criar um rótulo de detalhes, manipule o evento DetailLabelRequested . Os argumentos do evento fornecem o ScrollOffset onde o rótulo do tooltip será mostrado. 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 do evento args.

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 Scrolling para determinar como a rolagem está sendo executada, executar uma ação quando a rolagem ocorre ou Cancelar a ação de rolagem.

Obter o código de exemplo

  • Last updated on