Control de barra de desplazamiento anotada

Una barra de desplazamiento anotada ayuda a los usuarios a navegar fácilmente por una gran colección de elementos. Reemplaza la barra de desplazamiento predeterminada y se puede usar junto con cualquier contenedor desplazable. Esta barra de desplazamiento vertical permite a los usuarios desplazarse hacia arriba y hacia abajo por los elementos de una colección. Los usuarios pueden ver etiquetas de categoría a lo largo del área de la barra de desplazamiento para proporcionar una referencia visual de dónde están dentro de su colección. Un indicador de movimiento panorámico (línea de color de énfasis) indica la posición actual del usuario en la colección. Cuando un usuario pasa el ratón por encima de la barra de desplazamiento, se muestra un mensaje emergente. Esta información sobre herramientas contiene una etiqueta para proporcionar más información al usuario sobre su posición actual en la colección. Las flechas de desplazamiento se encuentran en la parte superior e inferior del área de la barra de desplazamiento. Se pueden usar para mover la posición actual por un pequeño incremento.

La barra de desplazamiento anotada se puede usar junto con un control ItemsView para volver a crear una experiencia de galería de fotos. Las etiquetas de categoría se pueden establecer en diferentes años para ayudar a los usuarios a navegar a una ubicación específica dentro de su colección de fotos.

Interacciones

Al mantener el puntero sobre una ubicación, se revela un tooltip que muestra una vista previa de esa ubicación. A continuación, los usuarios pueden hacer clic para ir a esa ubicación específica. Los usuarios también pueden hacer clic y arrastrar en cualquier lugar del área de la barra de desplazamiento para navegar a una nueva posición dentro de su colección. A medida que arrastran, el indicador de movimiento panorámico permanece conectado al cursor del mouse y el contenido se desplaza para reflejar la nueva posición. Los usuarios también pueden desplazarse por su colección mediante la rueda del mouse. Desplazarse hacia arriba o hacia abajo en la rueda del ratón mueve su posición en la colección y el indicador de desplazamiento panorámico correspondiente hacia arriba o hacia abajo por una cantidad fija.

Comportamiento de la etiqueta

• Para obtener experiencias optimizadas para la entrada táctil, los usuarios pueden mantener presionado sobre el área de la barra de desplazamiento para ver el tooltip. La información sobre herramientas estará ligeramente más elevada para facilitar su lectura a los usuarios de dispositivos táctiles. Pulsar y arrastrar en cualquier lugar del área de la barra de desplazamiento funcionará de forma similar a un clic y arrastrar con el mouse.
• La etiqueta de información sobre herramientas nunca se trunca, ya que su propósito es mostrar texto explicativo. En su lugar, el texto se ajusta cuando supera el ancho máximo del tooltip de 360px.
• Las etiquetas de categoría se recortan si el texto es mayor que el ancho del área de la barra de desplazamiento.
• Cuando hay una colisión entre dos etiquetas de categoría (por ejemplo, cuando el tamaño de la ventana disminuye y dos etiquetas se superponen entre sí), se quita la etiqueta superior. Como excepción a esta regla, la primera etiqueta de la colección siempre se mantiene, ya que ayuda a indicar el intervalo de la colección a los usuarios. Las etiquetas de categoría siempre deben tener un mínimo de 4px (2px por encima, 2px por debajo) entre sí; de lo contrario, se desencadena una colisión de etiquetas.

¿Es este el control adecuado?

Se recomienda usar una barra de desplazamiento anotada, en lugar de una barra de desplazamiento predeterminada, cuando se trabaja con una gran colección de elementos o cuando se espera una gran cantidad de desplazamiento. La barra de desplazamiento anotada proporcionará a los usuarios una forma fácil de ubicarse en su colección y de recorrerla.

En el caso de las colecciones que solo tienen algunos elementos o que solo requieren una pequeña cantidad de desplazamiento, se recomienda usar una barra de desplazamiento predeterminada.

Recommendations

• Solo agregue una etiqueta de categoría si proporciona información útil a los usuarios
• Mantenga las cadenas utilizadas para las etiquetas de categoría y el cuadro de información lo más concisas posible.
• La barra de desplazamiento anotada se usa mejor cuando hay suficiente espacio vertical. El uso de la barra de desplazamiento anotada en un espacio vertical confinado reducirá el número de etiquetas visibles.
• No use la barra de desplazamiento anotada como único medio para que los usuarios se ubiquen dentro de una colección. Se recomienda usar encabezados permanentes o etiquetas de categoría en toda la colección para complementar la barra de desplazamiento anotada.

Creación de una barra de desplazamiento anotada

La aplicación Galería de WinUI 3 incluye ejemplos interactivos de características y controles winUI. Obtenga la aplicación del Microsoft Store o examine el código fuente en GitHub.

Para usar annotatedScrollBar, debe completar varios pasos:

• Conecte el AnnotatedScrollBar a un contenedor de desplazamiento.
• Agregue etiquetas a la barra de desplazamiento.
• Agregue etiquetas de detalles (información sobre herramientas).

Conecta AnnotatedScrollBar con un contenedor de desplazamiento

Para usar AnnotatedScrollBar, conéctelo a un contenedor desplazable a través de la interfaz IScrollController. AnnotatedScrollBar proporciona una implementación de IScrollController a través de su propiedad ScrollController, mientras que ScrollView la consume a través de su propiedad ScrollPresenter (en concreto, ScrollPresenter.VerticalScrollController).

Aquí, la propiedad VerticalScrollController de un ItemsView está vinculada al ScrollController de una AnnotatedScrollBar. (La propiedad ItemsView.VerticalScrollPresenter se transmite al valor de ScrollPresenter.VerticalScrollController de la ScrollView interna de ItemsView).

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

También puede conectarlos en código, como se muestra aquí. En este ejemplo, se usa una ScrollView para encapsular un ItemsRepeater y proporcionarle funciones de desplazamiento. AnnotatedScrollBar reemplaza la barra de desplazamiento predeterminada de 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;
}

Etiquetas

AnnotatedScrollBar puede mostrar dos tipos de etiquetas, ambos opcionales.

Etiquetas de categoría

Puede agregar etiquetas rellenando la colección Etiquetas. Cada etiqueta se representa mediante la clase AnnotatedScrollBarLabel y requiere dos fragmentos de información:

• Contenido: el contenido que se muestra en la barra de desplazamiento.
• ScrollOffset: valor de desplazamiento en el que se muestra el contenido de la etiqueta.

Las etiquetas (si se especifican) siempre están visibles en la barra de desplazamiento, a menos que entren en conflicto con otras etiquetas o se extiendan más allá de los límites del raíl. (Consulte Comportamiento de etiquetas para más información).

El cálculo del valor de desplazamiento de la etiqueta depende de los detalles de la aplicación y sus datos. Para obtener un ejemplo de cómo se puede calcular el desplazamiento, consulte el ejemplo de galería de WinUI 3 en GitHub.

Etiquetas detalladas

Una etiqueta de detalle es un elemento tipo tooltip que se muestra cuando el cursor está sobre la barra de desplazamiento. Para crear una etiqueta de detalles, controle el evento DetailLabelRequested. Los argumentos de evento proporcionan el ScrollOffset donde se mostrará la etiqueta de información sobre herramientas. Use este valor para determinar la etiqueta correcta que se va a mostrar para esa posición y establecer la etiqueta como la propiedad Content de los argumentos del evento.

Desplazamiento

El usuario puede desplazarse por AnnotatedScrollBar haciendo clic en los botones de flecha de la parte superior e inferior de la barra de desplazamiento. Puede establecer la propiedad SmallChange para especificar la cantidad por la que los botones de flecha desplazan el contenido.

Puede controlar el evento Scrolling para determinar cómo se realiza el desplazamiento, realizar una acción al desplazarse o cancelar la acción de desplazamiento.

Obtención del código de ejemplo

• Ejemplo de la galería de WinUI 3 : consulta todos los controles XAML en un formato interactivo.

Temas relacionados

• Clase ScrollView