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). Para acceder a dicho contenido, los usuario manipulan la superficie del visor de desplazamiento mediante entrada táctil, la rueda del mouse, el teclado o un controlador para juegos, o bien mediante el uso del cursor del ratón o del lápiz óptico para interactuar con la barra de desplazamiento del visor de desplazamiento.

En función de la situación, la barra de desplazamiento del visor de desplazamiento usa dos visualizaciones diferentes, que se muestran en la siguiente ilustración: el indicador de movimiento panorámico (izquierda) y la barra de desplazamiento con el control tradicional (derecha).

Desplazamiento, movimiento panorámico 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 vertical u horizontalmente mediante la entrada táctil o manuscrita.
  • Para obtener más información sobre el desplazamiento y el movimiento panorámico, consulte Directrices para el movimiento panorámico.
• Zoom: aumento o disminución ópticos de 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.

Ventanilla y extensión

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 visible del control donde se muestra el contenido es la ventanilla.

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.

Recomendaciones

• Siempre que sea posible, diseñe para el desplazamiento vertical en lugar del horizontal.
• Utilice el desplazamiento lateral en un eje para las regiones de contenido que se extienden más allá de los límites de una ventana gráfica (vertical u horizontal). Utilice el desplazamiento lateral 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).
• Use la funcionalidad de desplazamiento integrada 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 de navegación centralizada. 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.

UWP y WinUI 2

Existen API para este control en el espacio de nombres Windows.UI.Xaml.Controls.

Se recomienda usar la versión más reciente de WinUI 2 para obtener los estilos, las plantillas y las características más actuales de todos los controles. WinUI 2.2 o de versiones posteriores incluye una nueva plantilla para este control que usa esquinas redondeadas. Para obtener más información, consulta Radio de redondeo.

Crear un visor de desplazamiento

La aplicación WinUI 3 Gallery incluye ejemplos interactivos de la mayoría de los controles, características y funcionalidades de WinUI 3. Obtenga la aplicación de Microsoft Store u obtenga el código fuente en GitHub.

Un control de visor de desplazamiento se puede usar para hacer que el contenido sea desplazable mediante el ajuste explícito del contenido en el visor de desplazamiento o la colocación 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 ScrollView en su plantilla. Puede acceder a ScrollView mediante la propiedad ItemsView.ScrollView.

Las plantillas ListView y GridView siempre incluyen un ScrollViewer. TextBox y RichEditBox también incluyen un ScrollViewer en sus plantillas. Para influir en algunos de los comportamientos y de las propiedades de la parte integrada ScrollViewer, ScrollViewer 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 de un visor de desplazamiento se vuelve desplazable cuando es mayor que la ventanilla del visor de desplazamiento

En este ejemplo se establece un Rectangle como el contenido del control ScrollView. 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>

Layout

En el ejemplo anterior, el tamaño del rectángulo se establece explícitamente para que sea más grande que el 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 aumentará horizontalmente hasta que su contenedor primario lo restrinja y, a continuación, ajuste el texto y lo extienda verticalmente.

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

Cuando el bloque de texto se ajusta en un visor de desplazamiento, el visor de desplazamiento restringe 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 Disabled, la interacción del usuario no puede desplazar el contenido en esa dirección.
  • Los valores predeterminados son: VerticalScrollBarVisibility="Auto", HorizontalScrollBarVisibility="Disabled"
• En el control ScrollView, las propiedades VerticalScrollBarVisibility y HorizontalScrollBarVisibility controlan solo la visibilidad de las barras de desplazamiento.
  • Los valores predeterminados son: VerticalScrollBarVisibility="Auto", HorizontalScrollBarVisibility="Auto"

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 Height y Width se establecen explícitamente en el contenido, ContentOrientation no tiene ningún efecto.

En esta tabla se muestran las opciones ContentOrientation 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 Content 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 StackPanel que está estableciendo 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 mediante programación.

<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);
}

Acercar

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 reducir y estirar (separar los dedos sirve para hace zoom y juntarlos, para deshacerlo) o presionando la tecla Ctrl mientras se desplaza la rueda del mouse. 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 ZoomMode en Enabled (es Disabled de forma predeterminada). Los cambios en la propiedad ZoomMode 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 MinZoomFactor y MaxZoomFactor 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: MinZoomFactor="0.1", MaxZoomFactor="10.0"

<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 ZoomFactor 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 un control deslizante que controla la cantidad de zoom o a un botón para restablecer el nivel de zoom. (Consulte ScrollViewer en la aplicación WinUI 3 Gallery para ver un control deslizante de zoom de ejemplo).

<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));
    }
}

Obtener el código de ejemplo

• Muestra de la Galería WinUI: vea todos los controles XAML en un formato interactivo.

Temas relacionados

• Clase ScrollViewer