Bagikan melalui

Pengendali bilah gulir yang dianotasi

Bilah gulir yang diannotasi membantu pengguna dengan mudah menavigasi koleksi item yang besar. Ini menggantikan bilah gulir default dan dapat digunakan bersama dengan kontainer yang dapat digulir. Bilah gulir vertikal ini memungkinkan pengguna untuk menggulir ke atas dan ke bawah melalui item dalam koleksi. Pengguna dapat melihat label kategori di sepanjang area bilah gulir untuk memberikan referensi visual tempat mereka berada dalam koleksi mereka. Indikator panning (garis berwarna aksen) menunjukkan posisi pengguna saat ini dalam koleksi. Tooltip terungkap saat pengguna menggerakkan kursor di area bilah gulir. Tipsalat ini berisi label untuk memberikan informasi lebih lanjut kepada pengguna tentang posisi mereka saat ini dalam koleksi. Panah gulir terletak di bagian atas dan bawah area bilah gulir. Mereka dapat digunakan untuk memindahkan posisi saat ini dengan langkah kecil

Cuplikan layar yang menampilkan bilah gulir beranomasi di aplikasi Foto.

Bilah gulir yang dianomasi dapat digunakan bersama dengan kontrol ItemsView untuk membuat ulang pengalaman galeri foto. Label kategori dapat diatur ke tahun yang berbeda untuk membantu pengguna menavigasi ke lokasi tertentu dalam koleksi foto mereka.

Interaksi

Ketika penunjuk diarahkan, tooltip muncul untuk menampilkan pratinjau lokasi tersebut. Pengguna kemudian dapat mengklik untuk menavigasi ke lokasi tertentu. Pengguna juga dapat mengklik dan menyeret di mana saja di area bilah gulir untuk menavigasi ke posisi baru dalam koleksi mereka. Saat diseret, indikator panning tetap melekat pada kursor mouse dan konten menggulir untuk menunjukkan posisi baru. Pengguna juga dapat menggulir koleksi mereka dengan menggunakan roda mouse. Menggulirkan roda tetikus ke atas dan ke bawah memindahkan posisi mereka dalam daftar dan menggeser indikator panning sesuai ke atas atau ke bawah dengan jumlah tetap.

Nota

Tidak seperti di kontrol ScrollBar , Anda tidak dapat mengklik dan menyeret ibu jari. Jempol adalah elemen non-interaktif yang hanya untuk memvisualisasikan posisi viewport saat ini. Ibu jari memiliki tinggi tetap yang tidak mewakili tinggi viewport.

Perilaku label

  • Untuk pengalaman yang dioptimalkan untuk input sentuh, pengguna dapat mengetuk dan menahan area bilah gulir untuk melihat tooltip. Tooltip akan sedikit dinaikkan untuk mempermudah membaca bagi pengguna perangkat layar sentuh. Mengetuk dan menyeret di mana saja di area bilah gulir akan berfungsi sama dengan klik dan seret dengan mouse.
  • Label tipsalat tidak pernah dipotong karena tujuannya adalah untuk menampilkan teks yang jelas. Sebaliknya, teks akan dibungkus jika melebihi lebar maksimum dari tooltip 360px.
  • Label kategori terpotong jika teks melebihi lebar area bilah gulir.
  • Ketika ada tabrakan antara dua label kategori (misalnya, ketika ukuran jendela berkurang dan dua label saling tumpang tindih), label atas dihapus. Sebagai pengecualian untuk aturan ini, label pertama koleksi selalu disimpan karena membantu menunjukkan rentang koleksi kepada pengguna. Label kategori harus selalu memiliki jarak minimal 4px (2px di atas, 2px di bawah) di antaranya, jika tidak, akan terjadi tabrakan etiket.

Apakah ini kontrol yang tepat?

Sebaiknya gunakan bilah gulir yang dianotasi, bukan bilah gulir default, saat berhadapan dengan koleksi item yang besar atau ketika sejumlah besar pengguliran diharapkan. Bilah gulir yang dianotasi akan memberikan cara mudah bagi pengguna untuk menemukan diri mereka dalam koleksi mereka dan untuk melintasinya.

Untuk koleksi yang hanya memiliki beberapa item atau yang hanya memerlukan sedikit pengguliran, sebaiknya gunakan bilah gulir default.

Recommendations

  • Hanya tambahkan label kategori jika memberikan informasi bermanfaat kepada pengguna
  • Pertahankan string yang digunakan untuk label kategori dan tooltip sesingkat mungkin.
  • Bilah gulir yang dianotasi paling baik digunakan ketika ada ruang vertikal yang memadai. Menggunakan bilah gulir yang dianotasi dalam ruang vertikal terbatas akan mengurangi jumlah label yang terlihat
  • Jangan gunakan bilah gulir yang dianotasi sebagai satu-satunya cara bagi pengguna untuk menemukan diri mereka dalam koleksi. Sebaiknya gunakan header lekat atau label kategori di seluruh koleksi Anda untuk melengkapi bilah gulir yang dianotasikan.

Membuat bilah gulir dengan anotasi

Buka aplikasi Galeri WinUI 3 dan lihat AnnotatedScrollBar beraksi

Ikon Galeri WinUI 3 Aplikasi Galeri WinUI 3 mencakup contoh interaktif kontrol dan fitur WinUI. Dapatkan aplikasi dari Microsoft Store atau telusuri kode sumber pada GitHub.

Untuk menggunakan AnnotatedScrollBar, Anda perlu menyelesaikan beberapa langkah:

  • Sambungkan AnnotatedScrollBar ke kontainer gulir.
  • Tambahkan label ke bilah gulir.
  • Tambahkan label rinci (tooltip).

Menyambungkan AnnotatedScrollBar ke kontainer gulir

Untuk menggunakan AnnotatedScrollBar, Anda menyambungkannya ke kontainer yang dapat digulir melalui antarmuka IScrollController. AnnotatedScrollBar menyediakan implementasi IScrollController melalui properti ScrollController-nya, sementara ScrollView menggunakannya melalui properti ScrollPresenter -nya (khususnya, ScrollPresenter.VerticalScrollController).

Nota

Kontrol ScrollView memiliki dukungan bawaan untuk menggunakan antarmuka IScrollController. Untuk kontainer gulir lainnya, seperti ScrollViewer, Anda harus menulis adaptor untuk IScrollController. Lihat contohnya nanti di artikel ini.

Di sini, properti VerticalScrollController dari ItemsView terikat ke ScrollController dari AnnotatedScrollBar. (Properti ItemsView.VerticalScrollPresenter diteruskan ke nilai ScrollPresenter.VerticalScrollController dari ScrollView dalam ItemsView.)

<Grid ColumnDefinitions="*,Auto">
    <ItemsView VerticalScrollController="{x:Bind annotatedScrollBar.ScrollController}"/>
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"/>
</Grid>

Anda juga dapat menghubungkannya dalam kode, seperti yang ditunjukkan di sini. Contoh ini menggunakan ScrollView untuk membungkus ItemsRepeater dan menyediakan fungsionalitas pengguliran untuk elemen tersebut. AnnotatedScrollBar menggantikan bilah gulir default ScrollView.

<Grid ColumnDefinitions="*, Auto">
    <ScrollView x:Name="scrollView"
                Background="LightGray" 
                MaxWidth="800" MaxHeight="500"
                VerticalScrollBarVisibility="Hidden">
        <ItemsRepeater x:Name="itemsRepeater"
                ItemsSource="{x:Bind ColorCollection}"
                Margin="2"
                SizeChanged="ItemsRepeater_SizeChanged">
            <ItemsRepeater.Layout>
                <UniformGridLayout/>
            </ItemsRepeater.Layout>
            <ItemsRepeater.ItemTemplate>
                <DataTemplate x:DataType="media:SolidColorBrush">
                    <Grid Background="{x:Bind}" Width="112" Height="82" 
                          CornerRadius="4" Margin="4"/>
                </DataTemplate>
            </ItemsRepeater.ItemTemplate>
        </ItemsRepeater>
    </ScrollView>
                
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"
        Margin="4,0,48,0" MaxHeight="500" HorizontalAlignment="Right"
        DetailLabelRequested="AnnotatedScrollBar_DetailLabelRequested"/>
</Grid>

private void AnnotatedScrollBarPage_Loaded(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
    scrollView.ScrollPresenter.VerticalScrollController = annotatedScrollBar.ScrollController;
}

Labels

AnnotatedScrollBar dapat menampilkan dua jenis label, yang keduanya bersifat opsional.

Label kategori

Anda menambahkan label dengan mengisi koleksi Label . Setiap Label diwakili oleh kelas AnnotatedScrollBarLabel dan memerlukan dua informasi:

  • Konten: Konten yang ditampilkan pada bilah gulir.
  • ScrollOffset: Nilai offset tempat konten label ditampilkan.

Label (jika ditentukan) selalu terlihat pada bilah gulir, kecuali jika bertabrakan dengan label lain atau melewati batas rel. (Lihat Perilaku label untuk info lebih lanjut.)

Perhitungan nilai offset label tergantung pada detail aplikasi Anda dan datanya. Untuk salah satu contoh bagaimana offset dapat dihitung, lihat contoh Galeri WinUI 3 pada GitHub.

Label detail-detail

Label detail adalah elemen tipsalat yang ditampilkan saat kursor berada di atas bilah gulir. Untuk membuat label detail, Anda menangani peristiwa DetailLabelRequested . Argumen peristiwa menyediakan ScrollOffset tempat label tooltip akan ditampilkan. Gunakan nilai ini untuk menentukan label yang benar untuk ditampilkan untuk posisi tersebut, dan atur label sebagai properti Konten dari arg peristiwa.

Pengguliran

Pengguna dapat menggulir AnnotatedScrollBar dengan mengklik tombol panah di bagian atas dan bawah bilah gulir. Anda dapat mengatur properti SmallChange untuk menentukan jumlah di mana tombol panah menggulir konten.

Anda dapat menangani peristiwa Pengguliran untuk menentukan bagaimana pengguliran dilakukan, mengambil tindakan saat pengguliran terjadi, atau untuk Membatalkan tindakan gulir.

Dapatkan kode contoh

  • Last updated on