Share via

Kontrol penampil gulir

  • Artikel

Ketika ada lebih banyak konten UI untuk ditampilkan daripada yang dapat Anda paskan di area, gunakan kontrol penampil gulir.

Penampil gulir memungkinkan konten meluas di luar batas viewport (area yang terlihat). Pengguna mencapai konten ini dengan memanipulasi permukaan penampil gulir melalui sentuhan, mousewheel, keyboard, atau gamepad, atau dengan menggunakan kursor mouse atau pena untuk berinteraksi dengan bilah gulir penampil gulir.

Bergantung pada situasinya, bilah gulir penampil gulir menggunakan dua visualisasi berbeda, yang ditunjukkan dalam ilustrasi berikut: indikator panning (kiri) dan ibu jari bilah gulir tradisional (kanan).

A screenshot that illustrates a panning scrollbar, a 2 pixel wide vertical line at the right edge of the content.

A screenshot that illustrates the standard scrollbar, a 6 pixel wide vertical line with an up arrow button at the top, and a down arrow at the bottom.

Penting

WinUI 3 memiliki dua kontrol penampil gulir berbeda yang tersedia: ScrollViewer dan ScrollView. Setiap kali kita berbicara secara generik tentang kontrol penampil gulir, informasi tersebut berlaku untuk kedua kontrol.

Menggulir, menggeser, dan memperbesar tampilan

Gunakan kontrol penampil gulir untuk mengizinkan pengguliran, pengalihan, dan perbesar tampilan konten Anda.

  • Menggulir: Memindahkan konten secara vertikal atau horizontal dengan menyeret jempol bilah gulir atau menggunakan roda gulir pada mouse.
  • Panning: Memindahkan konten secara vertikal atau horizontal menggunakan input sentuhan atau pena.
  • Pembesaran: Meningkatkan atau mengurangi skala konten secara optik.

Bilah gulir sadar akan metode input pengguna dan menggunakannya untuk menentukan visualisasi mana yang akan ditampilkan.

  • Saat wilayah digulir tanpa memanipulasi bilah gulir secara langsung, misalnya, dengan sentuhan, indikator panning muncul, menampilkan posisi gulir saat ini.
  • Ketika kursor mouse atau pena bergerak di atas indikator panning, kursor akan berubah menjadi bilah gulir tradisional. Menyeret jempol bilah gulir memanipulasi wilayah gulir.

An animation that shows the scroll bar transform from the narrow panning indicator to the traditional thumb when the cursor moves over it.

Catatan

Ketika bilah gulir terlihat, itu dilapisi sebagai 16px di atas konten di dalam ScrollViewer Anda. Untuk memastikan desain UX yang baik, Anda ingin memastikan bahwa tidak ada konten interaktif yang dikaburkan oleh overlay ini. Selain itu jika Anda lebih suka tidak memiliki tumpang tindih UX, biarkan 16px padding di tepi viewport untuk memungkinkan bilah gulir.

Lihatlaporan dan luas

Penampil gulir terdiri dari dua wilayah utama yang penting untuk memahami fungsionalitasnya. Area yang mencakup semua konten yang dapat digulir, baik tersembunyi maupun terlihat, adalah sejauh mana. Area kontrol yang terlihat di mana konten ditampilkan adalah viewport.

A block of text that extends beyond the viewport, or visible area of the control.

Berbagai API tersedia yang memungkinkan Anda mendapatkan tinggi dan lebar wilayah ini, serta tinggi dan lebar yang dapat digulir, yang merupakan perbedaan antara ukuran luas dan ukuran viewport.

Rekomendasi

  • Jika memungkinkan, desain untuk pengguliran vertikal daripada horizontal.
  • Gunakan panning satu sumbu untuk wilayah konten yang melampaui satu batas viewport (vertikal atau horizontal). Gunakan panning dua sumbu untuk wilayah konten yang melampaui batas viewport (vertikal dan horizontal).
  • Gunakan fungsionalitas gulir bawaan dalam tampilan item, tampilan daftar, tampilan kisi, kotak kombo, kotak daftar, kotak input teks, dan kontrol hub. Dengan kontrol tersebut, jika ada terlalu banyak item untuk ditampilkan sekaligus, pengguna dapat menggulir secara horizontal atau vertikal di atas daftar item.
  • Jika Anda ingin pengguna menggeser ke kedua arah di sekitar area yang lebih besar, dan mungkin juga untuk memperbesar tampilan, misalnya, jika Anda ingin mengizinkan pengguna untuk menggeser dan memperbesar gambar berukuran penuh (bukan ukuran gambar agar sesuai dengan layar) lalu letakkan gambar di dalam penampil gulir.
  • Jika pengguna akan menggulir bagian teks yang panjang, konfigurasikan penampil gulir untuk menggulir secara vertikal saja.
  • Gunakan penampil gulir untuk berisi satu objek saja. Perhatikan bahwa satu objek dapat menjadi panel tata letak, pada gilirannya berisi sejumlah objek sendiri.
  • Jika Anda perlu menangani peristiwa penunjuk untuk UIElement dalam tampilan yang dapat digulir (seperti ScrollViewer atau ListView), Anda harus secara eksplisit menonaktifkan dukungan untuk peristiwa manipulasi pada elemen dalam tampilan dengan memanggil UIElement.CancelDirectManipulation. Untuk mengaktifkan kembali peristiwa manipulasi dalam tampilan, panggil UIElement.TryStartDirectManipulation.

UWP dan WinUI 2

Catatan

Kontrol ScrollView hanya tersedia di WinUI 3. Untuk UWP dan WinUI 2, gunakan ScrollViewer kontrol .

Penting

Informasi dan contoh dalam artikel ini dioptimalkan untuk aplikasi yang menggunakan SDK Aplikasi Windows dan WinUI 3, tetapi umumnya berlaku untuk aplikasi UWP yang menggunakan WinUI 2. Lihat referensi API UWP untuk informasi dan contoh spesifik platform.

Bagian ini berisi informasi yang Anda butuhkan untuk menggunakan kontrol di aplikasi UWP atau WinUI 2.

API untuk kontrol ini ada di namespace Windows.UI.Xaml.Controls .

Sebaiknya gunakan WinUI 2 terbaru untuk mendapatkan gaya dan templat terbaru untuk semua kontrol. WinUI 2.2 atau yang lebih baru menyertakan templat baru untuk kontrol ini yang menggunakan sudut bulat. Untuk informasi selengkapnya, lihat radius sudut.

Membuat penampil gulir

Buka aplikasi Galeri WinUI 3 dan lihat tindakan ScrollView. Buka aplikasi Galeri WinUI 3 dan lihat ScrollViewer beraksi.

Aplikasi Galeri WinUI 3 mencakup contoh interaktif dari sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub

Kontrol penampil gulir dapat digunakan untuk membuat konten dapat digulir dengan secara eksplisit membungkus konten di penampil gulir, atau dengan menempatkan penampil gulir di templat kontrol kontrol konten.

Gulir penampil dalam templat kontrol

Biasanya kontrol penampil gulir ada sebagai bagian komposit dari kontrol lain. Bagian penampil gulir akan menampilkan viewport bersama dengan bilah gulir hanya ketika ruang tata letak kontrol host dibatasi lebih kecil dari ukuran konten yang diperluas.

ItemsView menyertakan ScrollView kontrol dalam templatnya. Anda dapat mengakses ScrollView properti ItemsView.ScrollView.

Templat ListView dan GridView selalu menyertakan ScrollViewer. TextBox dan RichEditBox juga menyertakan ScrollViewer dalam templat mereka. Untuk memengaruhi beberapa perilaku dan properti bagian bawaan ScrollViewer , ScrollViewer menentukan sejumlah properti terlampir XAML yang dapat diatur dalam gaya dan digunakan dalam pengikatan templat. Untuk informasi selengkapnya tentang properti terlampir, lihat Gambaran umum properti terlampir.

Mengatur konten yang dapat digulir

Konten di dalam penampil gulir menjadi dapat digulir saat lebih besar dari viewport penampil gulir

Contoh ini menetapkan Rectangle sebagai konten ScrollView kontrol. Pengguna hanya melihat bagian 500x400 dari persegi panjang tersebut dan dapat menggulir untuk melihat sisanya.

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

Tata letak

Dalam contoh sebelumnya, ukuran persegi panjang secara eksplisit diatur agar lebih besar dari penampil gulir. Dalam kasus konten penampil gulir diizinkan untuk tumbuh secara alami, seperti dalam daftar atau blok teks, Anda dapat mengonfigurasi penampil gulir untuk membiarkan kontennya ( sejauh) diperluas secara vertikal, horizontal, keduanya, atau tidak keduanya.

Misalnya, blok teks ini akan tumbuh secara horizontal sampai kontainer induknya membatasinya, lalu membungkus teks dan tumbuh secara vertikal.

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

Saat blok teks dibungkus dalam penampil gulir, penampil gulir membatasi pertumbuhan horizontal dan vertikalnya.

Vertikal berarti bahwa konten dibatasi secara horizontal, tetapi dapat tumbuh secara vertikal di luar batas viewport, dan pengguna dapat menggulir konten ke atas dan ke bawah.

A block of text that extends vertically beyond the viewport, or visible area of the control, with a vertical scroll bar shown.

Horizontal berarti bahwa konten dibatasi secara vertikal, tetapi dapat tumbuh secara horizontal di luar batas viewport, dan pengguna dapat menggulir konten ke kiri dan kanan.

A block of text that extends horizontally beyond the viewport, or visible area of the control, with a horizontal scroll bar shown.

Visibilitas bilah gulir

Kontrol ScrollViewer dan ScrollView menggunakan cara yang sedikit berbeda untuk mengonfigurasi pengguliran konten horizontal dan vertikal.

Tabel ini menjelaskan opsi visibilitas untuk properti ini.

Nilai Deskripsi
Otomatis Bilah gulir hanya muncul ketika viewport tidak dapat menampilkan semua konten.
Dinonaktifkan (khusus ScrollViewer) Bilah gulir tidak muncul bahkan ketika viewport tidak dapat menampilkan semua isi. Menggulir menurut interaksi pengguna dinonaktifkan. (Pengguliran terprogram masih dimungkinkan.)
Tersembunyi Bilah gulir tidak muncul bahkan ketika viewport tidak dapat menampilkan semua isi. Pengguliran masih diaktifkan, dan dapat terjadi melalui interaksi sentuhan, keyboard, atau roda mouse.
Dapat dilihat Bilah gulir selalu muncul. (Dalam desain UX saat ini, bilah gulir hanya muncul ketika kursor mouse berada di atasnya kecuali viewport tidak dapat menampilkan semua konten. )

(ScrollViewer menggunakan Enum ScrollBarVisibility ; ScrollView menggunakan enum ScrollingScrollBarVisibility .)

Orientasi

Kontrol ScrollView memiliki properti ContentOrientation yang memungkinkan Anda mengontrol tata letak konten. Properti ini menentukan bagaimana konten dapat tumbuh ketika tidak dibatasi secara eksplisit. Jika Height dan Width secara eksplisit diatur pada konten, ContentOrientation tidak berpengaruh.

Tabel ini memperlihatkan ContentOrientation opsi untuk ScrollView dan pengaturan yang setara untuk ScrollViewer.

Orientasi ScrollView ScrollViewer
Vertikal ContentOrientation="Vertical" VerticalScrollBarVisibility="[Auto][Visible][Hidden]"
HorizontalScrollBarVisibility="Disabled"
Horizontal ContentOrientation="Horizontal" VerticalScrollBarVisibility="Disabled"
HorizontalScrollBarVisibility="[Auto][Visible][Hidden]"
Keduanya ContentOrientation="Both" VerticalScrollBarVisibility="[Auto][Visible][Hidden]"
HorizontalScrollBarVisibility="[Auto][Visible][Hidden]"
Tidak ada ContentOrientation="None"
 VerticalScrollBarVisibility="Disabled"
HorizontalScrollBarVisibility="Disabled"

Tata letak vertikal

Secara default, tata letak konten (orientasi) penampil gulir bersifat vertikal.

Dalam contoh ini, ItemsRepeater digunakan sebagai ScrollView Content. UniformGridLayout untuk ItemRepeater memosisikan item secara horizontal dalam baris hingga kehabisan ruang (500px dalam contoh ini), lalu memosisikan item berikutnya pada baris berikutnya. ItemsRepeater mungkin lebih tinggi dari 400px yang dapat dilihat pengguna, tetapi pengguna kemudian dapat menggulir konten secara vertikal.

Nilai defaultnya ContentOrientation adalah Vertical, sehingga tidak ada perubahan yang diperlukan pada ScrollView.

<ScrollView Width="500" Height="400">
    <ItemsRepeater ItemsSource="{x:Bind Albums}"
                   ItemTemplate="{StaticResource MyTemplate}">
        <ItemsRepeater.Layout>
            <UniformGridLayout RowSpacing="8" ColumnSpacing="8"/>
        </ItemsRepeater.Layout>
    </ItemsRepeater>
</ScrollView>

Tata letak horizontal

Dalam contoh ini, konten adalah StackPanel yang menata itemnya secara horizontal. Konfigurasi penampil gulir diubah untuk mendukung pengguliran horizontal dan menonaktifkan pengguliran vertikal.

ScrollViewProperti diatur ContentOrientation ke Horizontal untuk memungkinkan konten tumbuh secara horizontal sebanyak yang diperlukan.

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

Pengguliran terprogram

Properti offset penampil gulir bersifat baca-saja, tetapi metode disediakan untuk memungkinkan Anda menggulir secara terprogram.

Untuk kontrol ScrollView, panggil metode ScrollTo dan teruskan offset horizontal dan vertikal untuk menggulir ke. Dalam hal ini, pengguliran hanya vertikal, sehingga nilai HorizontalOffset saat ini digunakan. Untuk menggulir ke bagian atas, VerticalOffset 0 digunakan. Untuk menggulir ke bagian bawah, VerticalOffset sama dengan ScrollableHeight.

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

ScrollView juga menyediakan metode ScrollBy yang memungkinkan Anda menggulir secara vertikal atau horizontal oleh delta tertentu dari offset saat ini.

Zoom

Anda dapat menggunakan penampil gulir untuk memungkinkan pengguna memperbesar dan memperkecil konten secara optik. Interaksi zoom optik dilakukan melalui gerakan mencubit dan meregangkan (jari bergerak lebih jauh memperbesar dan memindahkannya lebih dekat bersama-sama memperkecil), atau dengan menekan tombol Ctrl saat menggulir roda gulir mouse. Untuk informasi selengkapnya tentang memperbesar tampilan, lihat Zoom optik dan mengubah ukuran.

Untuk mengaktifkan perbesar tampilan menurut interaksi pengguna, atur properti ke ZoomModeEnabled ( Disabled secara default). Perubahan pada ZoomMode properti segera berlaku dan dapat memengaruhi interaksi pengguna yang sedang berlangsung.

Contoh ini memperlihatkan Gambar yang dibungkus dalam penampil gulir yang dikonfigurasi untuk memungkinkan pembesaran tampilan.

<ScrollView Width="500" Height="400"
            ContentOrientation="Both"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.jpg"/>
</ScrollView>

Dalam hal ini, Gambar tidak dibatasi oleh penampil gulir, sehingga awalnya ditampilkan pada ukuran aslinya. Jika sumber gambar lebih besar dari viewport, pengguna harus memperkecil untuk melihat seluruh gambar, yang mungkin bukan perilaku yang dimaksudkan.

A picture of a mountain zoomed in so far that only blue sky and clouds in the upper left of the picture are visible.

Contoh berikutnya menunjukkan cara mengonfigurasi penampil gulir untuk membatasi gambar ke viewport sehingga awalnya dimuat diperkecil, dan pengguna dapat memperbesar dan menggulir jika mereka mau.

A picture of a mountain zoomed out so that the foreground, mountain, and sky are all visible.

Untuk membatasi gambar ke viewport ScrollView, atur properti ContentOrientation ke None. Karena visibilitas bilah gulir tidak terkait dengan batasan ini, bilah gulir muncul secara otomatis saat pengguna memperbesar tampilan.

<ScrollView Width="500" Height="400"
            ContentOrientation="None"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.jpg"/>
</ScrollView>

Faktor pembesaran

MinZoomFactor Gunakan properti dan MaxZoomFactor untuk mengontrol jumlah pengguna yang dapat memperbesar konten. Properti ini efektif untuk interaksi pengguna dan pembesaran terprogram.

  • Defaultnya adalah: 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>

Zoom terprogram

Properti ZoomFactor bersifat baca-saja, tetapi metode disediakan untuk memungkinkan Anda memperbesar tampilan secara terprogram. Penggunaan umum untuk ini adalah menyambungkan penampil gulir ke Penggeser yang mengontrol jumlah zoom, atau tombol untuk mengatur ulang tingkat perbesar tampilan. (Lihat ScrollViewer di aplikasi Galeri WinUI 3 untuk melihat contoh penggeser zoom.)

Untuk kontrol ScrollView, panggil metode ZoomTo dan berikan faktor zoom baru sebagai parameter pertama.

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

ScrollView juga menyediakan metode ZoomBy yang memungkinkan Anda memperbesar dan memperkecil oleh delta tertentu dari tingkat perbesar tampilan saat ini.

Mendapatkan kode sampel

  • Sampel Galeri WinUI - Lihat semua kontrol XAML dalam format interaktif.