Controles del visor de desplazamiento

Cuando la interfaz de usuario tenga más contenido que el que se puede mostrar en un área, use un control del visor de desplazamiento.

Los visores de desplazamiento permiten que el contenido se extienda más allá de los límites de la ventanilla (área visible). Los usuarios acceden a este contenido manipulando la superficie del visor de desplazamiento a través de la pantalla táctil, el ratón, el teclado o un gamepad, o utilizando el cursor del ratón o el lápiz para interactuar con la barra de desplazamiento del visor de desplazamiento.

En función de la situación, la barra de desplazamiento del visualizador de desplazamiento utiliza dos visualizaciones diferentes, que se muestran en la siguiente ilustración: el indicador de desplazamiento (izquierda) y el deslizador de la barra de desplazamiento tradicional (derecha).

Desplazamiento, panorámica y zoom

Use un control del visor de desplazamiento para permitir el desplazamiento, el movimiento panorámico y el zoom del contenido.

• Desplazamiento: mover el contenido vertical u horizontalmente arrastrando la barra de desplazamiento con el control o usando la rueda de desplazamiento de un mouse.
• Movimiento panorámico: mover contenido de manera vertical o horizontal mediante entrada táctil o de lápiz.
  • Para obtener más información sobre el desplazamiento y el movimiento panorámico, consulte Directrices para el movimiento panorámico.
• Hacer zoom: Aumentando o disminuyendo ópticamente la escala del contenido.
  • Para obtener más información sobre el zoom, consulte Zoom óptico y cambio de tamaño.

La barra de desplazamiento es consciente del método de entrada del usuario y lo usa para determinar la visualización que se va a usar.

• Cuando la región se desplaza sin manipular directamente la barra de desplazamiento, por ejemplo de manera táctil, aparece el indicador de movimiento panorámico y muestra la posición de desplazamiento actual.
• Cuando se mueve el cursor del ratón o del lápiz sobre el indicador de movimiento panorámico, se transforma en la barra de desplazamiento tradicional. Al arrastrar la barra de desplazamiento, la región de desplazamiento se manipula con el pulgar.

Animación que muestra la transformación de la barra de desplazamiento del indicador de movimiento panorámico estrecho al pulgar tradicional cuando el cursor se mueve sobre él.

Área visible y alcance

Un visor de desplazamiento se compone de dos regiones principales que son importantes para comprender su funcionalidad. El área que incluye todo el contenido desplazable, tanto oculto como visible, es la extensión. El área de visualización del control donde se muestra el contenido es el viewport.

Bloque de texto que se extiende más allá de la ventanilla o área visible del control.

Hay varias API disponibles que permiten obtener el alto y el ancho de estas regiones, así como el alto y el ancho desplazables, que son la diferencia entre el tamaño de extensión y el tamaño de la ventanilla.

Recommendations

• Siempre que sea posible, diseñe para el desplazamiento vertical en lugar del horizontal.
• Utilice el desplazamiento en un solo eje para las regiones de contenido que se extienden más allá de los límites de un área de visualización (vertical u horizontal). Utilice el desplazamiento en dos ejes para las regiones de contenido que se extienden más allá de ambos límites de la ventana gráfica (vertical y horizontal).
• Utilice la funcionalidad integrada de desplazamiento en la vista de elementos, la vista de lista, la vista de cuadrícula, el cuadro combinado, el cuadro de lista, el cuadro de entrada de texto y los controles hub. Con estos controles, si hay demasiados elementos que mostrar al mismo tiempo, el usuario puede desplazarse horizontal o verticalmente por la lista de elementos.
• Si quiere que el usuario pueda generar una vista panorámica en ambas direcciones sobre un área mayor y, posiblemente, también aplicar zoom. Por ejemplo, si quiere permitir que el usuario pueda generar una vista panorámica y aplicar zoom sobre una imagen a tamaño completo (en lugar de una imagen con tamaño ajustado a la pantalla) y, a continuación, colocar la imagen dentro de un visor de desplazamiento.
• Si el usuario va a desplazarse a lo largo un fragmento de texto largo, configure el visor de desplazamiento para que se desplace solamente de manera vertical.
• Use un visor de desplazamiento para contener un solo objeto. Tenga en cuenta que ese objeto puede ser un panel de diseño que contenga a su vez cualquier número de objetos.
• Si necesita controlar los eventos de puntero para una clase UIElement en una vista desplazable (como ScrollViewer o ListView), debe deshabilitar explícitamente la compatibilidad con los eventos de manipulación en el elemento de la vista mediante una llamada a UIElement.CancelDirectmanipulation(). Para volver a habilitar los eventos de manipulación en la vista, llame a UIElement.TryStartDirectManipulation.

Crear un visualizador de desplazamiento

Icono de la galería de WinUI 3

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.

Un control de visor de desplazamiento se puede usar para hacer que el contenido sea desplazable al envolver explícitamente el contenido en el visor de desplazamiento, o colocando un visor de desplazamiento en la plantilla de control de un control de contenido.

Visor de desplazamiento en una plantilla de control

Es habitual que exista un control del visor de desplazamiento como parte de otros controles. Un elemento del visor de desplazamiento mostrará una ventanilla junto con las barras de desplazamiento solo cuando el espacio de diseño del control de host tenga una limitación menor que el tamaño del contenido expandido.

ItemsView incluye un control en su plantilla. Puede acceder a a través de la propiedad ItemsView.ScrollView.

Las plantillas ListView y GridView siempre incluyen un . TextBox y RichEditBox también incluyen un en sus plantillas. Para influir en algunos de los comportamientos y de las propiedades de la parte integrada , define una serie de propiedades adjuntas XAML que se pueden establecer en estilos y usar en enlaces de plantilla. Para obtener más información sobre las propiedades adjuntas, consulte Introducción a las propiedades adjuntas.

Establecer contenido desplazable

El contenido dentro de un visualizador de desplazamiento se vuelve desplazable cuando es más grande que el área de visualización del visualizador de desplazamiento.

En este ejemplo se establece un como el contenido del control . El usuario solo ve una parte de 500x400 de ese rectángulo y puede desplazarse para ver el resto.

<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>

Diseño

En el ejemplo anterior, se establece que el tamaño del rectángulo sea explícitamente mayor que el del visor de desplazamiento. En los casos en los que el contenido del visor de desplazamiento puede crecer de forma natural, como en una lista o un bloque de texto, puede configurar el visor de desplazamiento para permitir que su contenido (la extensión) se expanda verticalmente, horizontalmente, de ambas maneras o de ninguna.

Por ejemplo, este bloque de texto se expandirá horizontalmente hasta que su contenedor primario lo restrinja, luego el texto se ajustará y crecerá verticalmente.

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

Cuando el bloque de texto se envuelve en un visor de desplazamiento, el visor de desplazamiento limita su crecimiento horizontal y vertical.

Visibilidad de la barra de desplazamiento

Los controles ScrollViewer y ScrollView usan medios ligeramente diferentes para configurar el desplazamiento horizontal y vertical del contenido.

• En el control ScrollViewer, las propiedades VerticalScrollBarVisibility y HorizontalScrollBarVisibility controlan la visibilidad de las barras de desplazamiento y si se permite el desplazamiento en una dirección determinada. Cuando una propiedad se establece en , la interacción del usuario no puede desplazar el contenido en esa dirección.
  • Los valores predeterminados son: ,
• En el control ScrollView, las propiedades VerticalScrollBarVisibility y HorizontalScrollBarVisibility controlan solo la visibilidad de las barras de desplazamiento.
  • Los valores predeterminados son: ,

En esta tabla se describen las opciones de visibilidad de estas propiedades.

(ScrollViewer usa la enumeración ScrollBarVisibility; ScrollView usa la enumeración ScrollingScrollBarVisibility).

Orientación

El control ScrollView tiene una propiedad ContentOrientation que permite controlar el diseño del contenido. Esta propiedad determina cómo puede crecer el contenido cuando no está restringido explícitamente. Si y se establecen explícitamente en el contenido, no tiene ningún efecto.

En esta tabla se muestran las opciones para ScrollView y la configuración equivalente para ScrollViewer.

Diseño vertical

De forma predeterminada, el diseño de contenido (orientación) de un visor de desplazamiento es vertical.

En este ejemplo, se usa un ItemsRepeater como de ScrollView. UniformGridLayout para ItemsRepeater coloca los elementos horizontalmente en una fila hasta que se queda sin espacio (500px en este ejemplo) y después coloca el siguiente elemento en la fila siguiente. ItemsRepeater puede ser más alto que los 400px que puede ver el usuario, pero el usuario puede desplazar el contenido 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>

Diseño horizontal

En este ejemplo, el contenido es un que dispone sus elementos horizontalmente. La configuración del visor de desplazamiento se cambia para admitir el desplazamiento horizontal y deshabilitar el desplazamiento 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>

Desplazamiento mediante programación

Las propiedades de desplazamiento del visor de desplazamiento son de solo lectura, pero se proporcionan métodos para permitirle desplazarse programáticamente.

<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

Puede usar un visor de desplazamiento para permitir al usuario acercar y alejar ópticamente el contenido. Las interacciones de zoom óptico se realizan a través de los gestos de pellizcar y estirar (separar los dedos sirve para hacer zoom y juntarlos para alejar el zoom) o presionando la tecla Ctrl mientras se mueve la rueda del ratón. Para obtener más información sobre el zoom, consulte Zoom óptico y cambio de tamaño.

Para habilitar el zoom por interacción del usuario, establezca la propiedad en (es de forma predeterminada). Los cambios en la propiedad surten efecto inmediatamente y pueden afectar a una interacción en curso del usuario.

En este ejemplo se muestra una imagen encapsulada en un visor de desplazamiento configurado para permitir el 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>

Factor de zoom

Use las propiedades y para controlar la medida en que el usuario puede acercar el contenido. Estas propiedades son eficaces para las interacciones del usuario y el zoom mediante programación.

• Los valores predeterminados son: ,

<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 mediante programación

La propiedad es de solo lectura, pero se proporcionan métodos para permitirle aplicar zoom mediante programación. Un uso típico de esto es conectar el visor de desplazamiento a una barra deslizante que controla la cantidad de zoom, o a un botón para restablecer el nivel de zoom. (Consulte el control ScrollViewer en la aplicación Gallery de WinUI 3 para ver un ejemplo de un control 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));
    }
}

Temas relacionados

• Clase ScrollViewer