Kontrol penampil gulir
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).
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.
- Untuk informasi selengkapnya tentang gulir dan panning, lihat Panduan untuk panning.
- Pembesaran: Meningkatkan atau mengurangi skala konten secara optik.
- Untuk informasi selengkapnya tentang memperbesar tampilan, lihat Zoom optik dan mengubah ukuran.
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.
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.
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 .
- API UWP: Kelas ScrollViewer, kelas ScrollBar
- Buka aplikasi Galeri WinUI 2 dan lihat ScrollViewer beraksi. Aplikasi Galeri WinUI 2 mencakup contoh interaktif dari sebagian besar kontrol, fitur, dan fungsi WinUI 2. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub.
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
- API Penting: Kelas ScrollView, kelas ScrollViewer, kelas ScrollBar
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.
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.
Visibilitas bilah gulir
Kontrol ScrollViewer dan ScrollView menggunakan cara yang sedikit berbeda untuk mengonfigurasi pengguliran konten horizontal dan vertikal.
- Dalam kontrol ScrollViewer, properti VerticalScrollBarVisibility dan HorizontalScrollBarVisibility mengontrol visibilitas bilah gulir dan apakah menggulir ke arah tertentu diizinkan. Saat properti diatur ke
Disabled
, konten tidak dapat digulir ke arah tersebut oleh interaksi pengguna.- Defaultnya adalah:
VerticalScrollBarVisibility="Auto"
,HorizontalScrollBarVisibility="Disabled"
- Defaultnya adalah:
- Dalam kontrol ScrollView, properti VerticalScrollBarVisibility dan HorizontalScrollBarVisibility hanya mengontrol visibilitas bilah gulir.
- Defaultnya adalah:
VerticalScrollBarVisibility="Auto"
,HorizontalScrollBarVisibility="Auto"
- Defaultnya adalah:
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 | 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.
ScrollView
Properti 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 ZoomMode
Enabled
( 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.
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.
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.
Topik terkait
Windows developer