Xamarin.Forms ScrollView

ScrollView est une disposition capable de faire défiler son contenu. La ScrollView classe dérive de la Layout classe, et par défaut fait défiler son contenu verticalement. Un ScrollView ne peut avoir qu’un seul enfant, même s’il peut s’agir d’autres dispositions.

Avertissement

Les objets ScrollView ne doivent pas être imbriqués. En outre, les objets ScrollView ne doivent pas être imbriqués avec d’autres contrôles qui fournissent le défilement, tels que CollectionView, ListView et WebView.

ScrollView définit les propriétés suivantes :

• Content, de type View, représente le contenu à afficher dans le ScrollView.
• ContentSize, de type Size, représente la taille du contenu. Il s’agit d’une propriété en lecture seule.
• HorizontalScrollBarVisibility, de type ScrollBarVisibility, représente le moment où la barre de défilement horizontale est visible.
• Orientation, de type ScrollOrientation, représente la direction de défilement du ScrollView. La valeur par défaut de cette propriété est Vertical.
• ScrollX, de type double, indique la position de défilement X actuelle. La valeur par défaut de cette propriété en lecture seule est 0.
• ScrollY, de type double, indique la position de défilement Y actuelle. La valeur par défaut de cette propriété en lecture seule est 0.
• VerticalScrollBarVisibility, de type ScrollBarVisibility, représente le moment où la barre de défilement verticale est visible.

Ces propriétés s’appuient sur des objets BindableProperty à l’exception de la propriété Content, ce qui signifie qu’elles peuvent être des cibles de liaisons de données et être mises en forme.

La propriété Content est la ContentProperty de la classe ScrollView. Elle n’a par conséquent pas besoin d’être explicitement définie à partir de XAML.

Conseil

Pour obtenir les meilleures performances de disposition possibles, suivez les instructions pour optimiser les performances de disposition.

ScrollView en tant que disposition racine

Un ScrollView ne peut avoir qu’un seul enfant. Il peut s’agir d’autres dispositions. Il est donc courant qu’un ScrollView soit la disposition racine d’une page. Pour faire défiler son contenu enfant, ScrollView calcule la différence entre la hauteur de son contenu et sa propre hauteur. Cette différence correspond à la quantité de contenu que le ScrollView peut faire défiler.

Une StackLayout sera souvent l’enfant d’un ScrollView. Dans ce scénario, le ScrollView amène la StackLayout à être aussi grande que la somme des hauteurs de ses enfants. Ensuite, le ScrollView peut déterminer la quantité que son contenu peut faire défiler. Pour plus d’informations sur stackLayout StackLayoutXamarin.Forms .

Attention

Dans un ScrollView verticale, évitez de définir la propriété VerticalOptions sur Start, Center ou End. Cette opération indique au ScrollView d’être uniquement aussi haut que nécessaire, ce qui peut être zéro. Bien que vous Xamarin.Forms soyez protégé contre cette éventualité, il est préférable d’éviter le code qui suggère quelque chose que vous ne voulez pas faire.

L’exemple de XAML suivant a un ScrollView comme disposition racine sur une page :

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:ScrollViewDemos"
             x:Class="ScrollViewDemos.Views.ColorListPage"
             Title="ScrollView demo">
    <ScrollView>
        <StackLayout BindableLayout.ItemsSource="{x:Static local:NamedColor.All}">
            <BindableLayout.ItemTemplate>
                <DataTemplate>
                    <StackLayout Orientation="Horizontal">
                        <BoxView Color="{Binding Color}"
                                 HeightRequest="32"
                                 WidthRequest="32"
                                 VerticalOptions="Center" />
                        <Label Text="{Binding FriendlyName}"
                               FontSize="24"
                               VerticalOptions="Center" />
                    </StackLayout>
                </DataTemplate>
            </BindableLayout.ItemTemplate>
        </StackLayout>
    </ScrollView>
</ContentPage>

Dans cet exemple, son ScrollView contenu est défini sur une StackLayout disposition pouvant être liée pour afficher les Color champs définis par Xamarin.Forms. Par défaut, un ScrollView fait défiler verticalement, ce qui révèle plus de contenu :

Le code C# équivalent est :

public class ColorListPageCode : ContentPage
{
    public ColorListPageCode()
    {
        DataTemplate dataTemplate = new DataTemplate(() =>
        {
            BoxView boxView = new BoxView
            {
                HeightRequest = 32,
                WidthRequest = 32,
                VerticalOptions = LayoutOptions.Center
            };
            boxView.SetBinding(BoxView.ColorProperty, "Color");

            Label label = new Label
            {
                FontSize = 24,
                VerticalOptions = LayoutOptions.Center
            };
            label.SetBinding(Label.TextProperty, "FriendlyName");

            StackLayout horizontalStackLayout = new StackLayout
            {
                Orientation = StackOrientation.Horizontal,
                Children = { boxView, label }
            };
            return horizontalStackLayout;
        });

        StackLayout stackLayout = new StackLayout();
        BindableLayout.SetItemsSource(stackLayout, NamedColor.All);
        BindableLayout.SetItemTemplate(stackLayout, dataTemplate);

        ScrollView scrollView = new ScrollView { Content = stackLayout };

        Title = "ScrollView demo";
        Content = scrollView;
    }
}

Pour plus d’informations sur les dispositions pouvant être liées, consultez Dispositions pouvant être liées dans Xamarin.Forms.

ScrollView en tant que disposition enfant

Un ScrollView peut être une disposition enfant dans une autre disposition parente.

Un ScrollView sera souvent l’enfant d’une StackLayout. Un ScrollView nécessite une hauteur spécifique pour calculer la différence entre la hauteur de son contenu et sa propre hauteur, la différence étant la quantité de contenu que le ScrollView peut faire défiler. Quand un ScrollView est l’enfant d’une StackLayout, il ne reçoit pas de hauteur spécifique. La StackLayout veut que le ScrollView soit aussi court que possible, ce qui correspond à la hauteur du contenu du ScrollView ou zéro. Pour gérer ce scénario, la VerticalOptions propriété de la propriété ScrollView doit être définie sur FillAndExpand. Cela entraînera la StackLayout à donner au ScrollView tout l’espace supplémentaire non requis par les autres enfants et le ScrollView aura alors une hauteur spécifique.

L’exemple de XAML suivant a un ScrollView comme disposition enfant dans une StackLayout :

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ScrollViewDemos.Views.BlackCatPage"
             Title="ScrollView as a child layout demo">
    <StackLayout Margin="20">
        <Label Text="THE BLACK CAT by Edgar Allan Poe"
               FontSize="Medium"
               FontAttributes="Bold"
               HorizontalOptions="Center" />
        <ScrollView VerticalOptions="FillAndExpand">
            <StackLayout>
                <Label Text="FOR the most wild, yet most homely narrative which I am about to pen, I neither expect nor solicit belief. Mad indeed would I be to expect it, in a case where my very senses reject their own evidence. Yet, mad am I not -- and very surely do I not dream. But to-morrow I die, and to-day I would unburthen my soul. My immediate purpose is to place before the world, plainly, succinctly, and without comment, a series of mere household events. In their consequences, these events have terrified -- have tortured -- have destroyed me. Yet I will not attempt to expound them. To me, they have presented little but Horror -- to many they will seem less terrible than barroques. Hereafter, perhaps, some intellect may be found which will reduce my phantasm to the common-place -- some intellect more calm, more logical, and far less excitable than my own, which will perceive, in the circumstances I detail with awe, nothing more than an ordinary succession of very natural causes and effects." />
                <!-- More Label objects go here -->
            </StackLayout>
        </ScrollView>
    </StackLayout>
</ContentPage>

Dans cet exemple, il existe deux StackLayout objets. Le premier StackLayout est l’objet de disposition racine, qui a un Label objet et un ScrollView en tant qu’enfant. Le ScrollView a un StackLayout en tant que contenu, avec la StackLayout contenant plusieurs objets Label. Cette disposition veille à ce que la première Label soit toujours à l’écran, alors qu’il est possible de faire défiler le texte affiché par les autres objets Label :

Le code C# équivalent est :

public class BlackCatPageCS : ContentPage
{
    public BlackCatPageCS()
    {
        Label titleLabel = new Label
        {
            Text = "THE BLACK CAT by Edgar Allan Poe",
            // More properties set here to define the Label appearance
        };

        ScrollView scrollView = new ScrollView
        {
            VerticalOptions = LayoutOptions.FillAndExpand,
            Content = new StackLayout
            {
                Children =
                {
                    new Label
                    {
                        Text = "FOR the most wild, yet most homely narrative which I am about to pen, I neither expect nor solicit belief. Mad indeed would I be to expect it, in a case where my very senses reject their own evidence. Yet, mad am I not -- and very surely do I not dream. But to-morrow I die, and to-day I would unburthen my soul. My immediate purpose is to place before the world, plainly, succinctly, and without comment, a series of mere household events. In their consequences, these events have terrified -- have tortured -- have destroyed me. Yet I will not attempt to expound them. To me, they have presented little but Horror -- to many they will seem less terrible than barroques. Hereafter, perhaps, some intellect may be found which will reduce my phantasm to the common-place -- some intellect more calm, more logical, and far less excitable than my own, which will perceive, in the circumstances I detail with awe, nothing more than an ordinary succession of very natural causes and effects.",
                    },
                    // More Label objects go here
                }
            }
        };

        Title = "ScrollView as a child layout demo";
        Content = new StackLayout
        {
            Margin = new Thickness(20),
            Children = { titleLabel, scrollView }
        };
    }
}

Orientation

ScrollView a une propriété d’Orientation qui représente la direction de défilement du ScrollView. Cette propriété est de type ScrollOrientation, ce qui définit les membres suivants :

• Vertical indique que le ScrollView effectue un défilement vertical. Ce membre est la valeur par défaut de la propriété Orientation.
• Horizontal indique que le ScrollView effectue un défilement horizontal.
• Both indique que le ScrollView effectue un défilement horizontal et vertical.
• Neither indique que le ScrollView n’effectue aucun défilement.

Conseil

Vous pouvez désactiver le défilement en définissant la propriété Orientation sur Neither.

Détecter le défilement

ScrollView définit un Scrolled événement déclenché pour indiquer que le défilement s’est produit. L’objet ScrolledEventArgs qui accompagne l’événement Scrolled a les propriétés ScrollX et ScrollY, toutes deux de type double.

Important

Les propriétés ScrolledEventArgs.ScrollX et ScrolledEventArgs.ScrollY peuvent avoir des valeurs négatives, en raison de l’effet de rebond qui se produit lors du défilement jusqu’au début d’un ScrollView.

L’exemple de XAML suivant montre un ScrollView qui définit un gestionnaire d’événements Scrolled pour l’événement :

<ScrollView Scrolled="OnScrollViewScrolled">
		...
</ScrollView>

Le code C# équivalent est :

ScrollView scrollView = new ScrollView();
scrollView.Scrolled += OnScrollViewScrolled;

Dans cet exemple, le gestionnaire d’événements OnScrollViewScrolled est exécuté lorsque l’événement Scrolled se déclenche :

void OnScrollViewScrolled(object sender, ScrolledEventArgs e)
{
    Console.WriteLine($"ScrollX: {e.ScrollX}, ScrollY: {e.ScrollY}");
}

Dans cet exemple, le gestionnaire d’événements OnScrollViewScrolled génère les valeurs de l’objet ScrolledEventArgs qui accompagne l’événement.

Remarque

L’événement Scrolled se déclenche pour les défilements initiés par l’utilisateur et les défilements programmatiques.

Faire défiler par programmation

ScrollView définit deux méthodes ScrollToAsync qui font défiler de manière asynchrone le ScrollView. L’une des surcharges fait défiler jusqu’à une position spécifiée dans le ScrollView, tandis que l’autre fait défiler un élément spécifié dans l’affichage. Les deux surcharges ont un argument supplémentaire que vous pouvez utiliser pour indiquer s’il faut animer le défilement.

Important

Les méthodes ScrollToAsync n’entraînent pas le défilement lorsque la propriété ScrollView.Orientation est définie sur Neither.

Faire défiler une position dans un affichage

Une position au sein d’un ScrollView peut faire l’objet d’un défilement avec la méthode ScrollToAsync qui accepte les arguments double x et y. Avec un objet vertical ScrollView nommé scrollView, l’exemple suivant montre comment faire défiler jusqu’à 150 unités indépendantes de l’appareil en haut du ScrollView :

await scrollView.ScrollToAsync(0, 150, true);

Le troisième argument de ScrollToAsync est l’argument animated qui détermine si une animation de défilement est affichée lors du défilement par programmation d’un ScrollView.

Faire défiler un élément dans un affichage

Un élément au sein d’un ScrollView peut faire l’objet d’un défilement avec la méthode ScrollToAsync qui accepte les arguments Element et ScrollToPosition. Avec un ScrollView vertical nommé scrollView et une Label nommée label, l’exemple suivant montre comment faire défiler un élément dans un affichage :

await scrollView.ScrollToAsync(label, ScrollToPosition.End, true);

Le troisième argument de ScrollToAsync est l’argument animated qui détermine si une animation de défilement est affichée lors du défilement par programmation d’un ScrollView.

Lors du défilement d’un élément dans un affichage, la position exacte de l’élément une fois le défilement terminé peut être définie avec le deuxième argument, position, de la méthode ScrollToAsync. Cet argument accepte un membre d’énumération ScrollToPosition :

• MakeVisible indique que l’élément doit faire l’objet d’un défilement jusqu’à ce qu’il soit visible dans le ScrollView.
• Start indique que l’élément doit faire l’objet d’un défilement jusqu’au début du ScrollView.
• Center indique que l’élément doit faire l’objet d’un défilement jusqu’au milieu du ScrollView.
• End indique que l’élément doit faire l’objet d’un défilement jusqu’à la fin du ScrollView.

Visibilité de la barre de défilement

ScrollView définit les propriétés HorizontalScrollBarVisibility et VerticalScrollBarVisibility qui s’appuient sur des propriétés pouvant être liées. Ces propriétés obtiennent ou définissent une valeur d’énumération ScrollBarVisibility qui indique si la barre de défilement horizontale ou verticale est visible. L’énumération ScrollBarVisibility définit les membres suivants :

• Defaultindique le comportement de la barre de défilement par défaut pour la plateforme et constitue la valeur par défaut des propriétés HorizontalScrollBarVisibility et VerticalScrollBarVisibility.
• Always indique que la barre de défilement est visible même si le contenu correspond à l’affichage.
• Never indique que la barre de défilement n’est pas visible même si le contenu ne correspond pas à l’affichage.

Liens connexes

• Xamarin.Forms StackLayout
• Dispositions pouvant être liées dans Xamarin.Forms