Tampilan item

Gunakan tampilan item untuk menampilkan kumpulan item data, seperti foto dalam album atau item dalam katalog produk.

Tampilan item mirip dengan tampilan daftar dan kontrol tampilan kisi, dan Anda dapat menggunakannya dalam banyak kasus di mana Anda akan menggunakan kontrol tersebut. Salah satu keuntungan dari tampilan item adalah kemampuannya untuk mengalihkan tata letak dengan cepat sambil mempertahankan pilihan item.

Kontrol tampilan item dibangun menggunakan komponen ItemsRepeater, ScrollView, ItemContainer, dan ItemCollectionTransitionProvider, sehingga menawarkan kemampuan unik untuk mencolokkan implementasi Tata Letak atau ItemCollectionTransitionProvider kustom. Kontrol ScrollView dalam tampilan item memungkinkan pengguliran dan pembesaran item. Ini juga menawarkan fitur yang tidak tersedia dalam kontrol ScrollViewer yang digunakan oleh tampilan daftar dan tampilan kisi, seperti kemampuan untuk mengontrol animasi selama gulir terprogram.

Seperti tampilan daftar dan kontrol tampilan kisi, tampilan item dapat menggunakan UI dan virtualisasi data; handel keyboard, mouse, pena, dan input sentuh; dan memiliki dukungan aksesibilitas bawaan.

Apakah ini kontrol yang tepat?

Gunakan tampilan item untuk:

• Tampilkan koleksi di mana semua item harus memiliki perilaku visual dan interaksi yang sama.
• Tampilkan kumpulan konten dengan kemampuan untuk beralih antara daftar, kisi, dan tata letak kustom.
• Mengakomodasi berbagai kasus penggunaan, termasuk kasus umum berikut:
  • Antarmuka pengguna jenis etalase (yaitu aplikasi penjelajahan, lagu, produk)
  • Pustaka foto interaktif
  • Daftar kontak

Membuat tampilan item

• API Penting: Kelas ItemsView, properti ItemsSource, properti ItemTemplate, LinedFlowLayout, StackLayout, UniformGridLayout

Buka aplikasi Galeri WinUI 3 dan lihat tindakan ItemsView.

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

ItemView dapat menampilkan kumpulan item dengan jenis apa pun. Untuk mengisi tampilan, atur properti ItemsSource ke sumber data.

Catatan

Tidak seperti kontrol koleksi lain (yang berasal dari ItemsControl), ItemsView tidak memiliki properti Item yang dapat Anda tambahkan item data ke secara langsung.

Mengatur sumber item

Anda biasanya menggunakan tampilan item untuk menampilkan data dari sumber seperti database atau internet. Untuk mengisi tampilan item dari sumber data, Anda mengatur properti ItemsSource-nya ke kumpulan item data.

Atur ItemsSource dalam kode

Di sini, ItemsSource diatur dalam kode langsung ke instans koleksi.

 // Data source.
 List<String> itemsList = new List<string>();
 itemsList.Add("Item 1");
 itemsList.Add("Item 2");

 // Create a new ItemsView and set the data source.
 ItemsView itemsView1 = new ItemsView();
 itemsView1.ItemsSource = itemsList;

 // Add the ItemsView to a parent container in the visual tree.
 rootGrid.Children.Add(itemsView1);

Bind ItemsSource di XAML

Anda juga dapat mengikat properti ItemsSource ke koleksi di XAML. Untuk informasi selengkapnya, lihat Pengikatan data dengan XAML.

Penting

Saat Anda menggunakan ekstensi markup x:Bind di DataTemplate, Anda harus menentukan jenis data (x:DataType) pada templat data.

Di sini, ItemsSource terikat ke kumpulan objek data kustom (dari jenis Photo).

<ItemsView ItemsSource="{x:Bind Photos}">

</ItemsView>

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();
        Photos = new ObservableCollection<Photo>();
        PopulatePhotos();
    }

    public ObservableCollection<Photo> Photos
    {
        get; private set;
    }


    private void PopulatePhotos()
    {
        // Populate the Photos collection. 
    }
}

public class Photo
{
    public BitmapImage PhotoBitmapImage { get; set; }
    public string Title { get; set; }
    public int Likes { get; set; }
}

Tentukan tampilan item

Secara default, item data ditampilkan dalam tampilan item sebagai representasi string objek data yang terikat. Anda biasanya ingin memperlihatkan presentasi data Anda yang lebih kaya. Untuk menentukan dengan tepat bagaimana item dalam tampilan item ditampilkan, Anda membuat DataTemplate. XAML dalam DataTemplate menentukan tata letak dan tampilan kontrol yang digunakan untuk menampilkan item individual. Kontrol dalam tata letak dapat terikat ke properti objek data, atau memiliki konten statis yang ditentukan sebaris. DataTemplate ditetapkan ke properti ItemTemplate dari kontrol ItemsView.

Penting

Elemen akar DataTemplate harus berupa ItemContainer; jika tidak, pengecualian akan dilemparkan. ItemContainer adalah kontrol primitif independen yang digunakan oleh ItemsView untuk memperlihatkan status pilihan dan visualisasi item individual lainnya dalam kumpulan item.

Dalam contoh ini, DataTemplate didefinisikan dalam Page.ResourcesResourceDictionary. Ini termasuk kontrol Gambar untuk menampilkan gambar dan overlay yang berisi judul gambar dan jumlah suka yang diterimanya.

 <Page.Resources>
     <DataTemplate x:Key="PhotoItemTemplate" x:DataType="local:Photo">
         <ItemContainer AutomationProperties.Name="{x:Bind Title}">
             <Grid>
                 <Image Source="{x:Bind PhotoBitmapImage, Mode=OneWay}" 
                        Stretch="UniformToFill" MinWidth="70"
                        HorizontalAlignment="Center" VerticalAlignment="Center"/>
                 <StackPanel Orientation="Vertical" Height="40" Opacity=".75"
                             VerticalAlignment="Bottom" Padding="5,1,5,1" 
                             Background="{ThemeResource SystemControlBackgroundBaseMediumBrush}">
                     <TextBlock Text="{x:Bind Title}" 
                                Foreground="{ThemeResource SystemControlForegroundAltHighBrush}"/>
                     <StackPanel Orientation="Horizontal">
                         <TextBlock Text="{x:Bind Likes}"
                                    Style="{ThemeResource CaptionTextBlockStyle}"
                                    Foreground="{ThemeResource SystemControlForegroundAltHighBrush}"/>
                         <TextBlock Text=" Likes"
                                    Style="{ThemeResource CaptionTextBlockStyle}"
                                    Foreground="{ThemeResource SystemControlForegroundAltHighBrush}"/>
                     </StackPanel>
                 </StackPanel>
             </Grid>
         </ItemContainer>
     </DataTemplate>
 </Page.Resources>

 <Grid x:Name="rootGrid">
     <ItemsView ItemsSource="{x:Bind Photos}" Width="480" Height="400" 
                ItemTemplate="{StaticResource PhotoItemTemplate}">
     </ItemsView>
 </Grid>

Berikut tampilan tata letak item yang ditentukan oleh templat data.

Mengubah tata letak item

Saat Anda menambahkan item ke kontrol ItemsView, item secara otomatis membungkus setiap item dalam ItemContainer lalu meletakkan semua kontainer item. Bagaimana kontainer item ini ditata tergantung pada properti Tata Letak kontrol.

Anda dapat mengubah tata letak item dengan menyesuaikan properti pada tata letak saat ini, atau Anda dapat sepenuhnya mengganti tata letak saat ini dengan tata letak yang berbeda. Anda dapat menggunakan salah satu tata letak yang dijelaskan berikutnya, atau Anda dapat memperoleh tata letak kustom dari kelas Tata Letak .

StackLayout

Secara default, ItemsView menggunakan StackLayout, yang menghasilkan daftar vertikal, yang diperlihatkan di sini dengan pengaturan properti default dan templat gambar sederhana.

XAML ini mengatur penspasian antara item di StackLayout ke 5px.

<ItemsView ItemsSource="{x:Bind Photos}" Width="480" Height="400" 
           ItemTemplate="{StaticResource PhotoItemTemplate}">
    <ItemsView.Layout>
        <StackLayout Spacing="5"/>
    </ItemsView.Layout>
</ItemsView>

StackLayout menyediakan properti untuk dikontrol:

• apakah tata letak vertikal atau horizontal (Orientasi)
• penspasian item (Penspasian)

Anda dapat menggunakan tata letak dalam kombinasi dengan ItemTemplate untuk memberi koleksi Anda berbagai tampilan agar sesuai dengan kebutuhan Anda. Misalnya, sampel Galeri WinUI mengubah ItemTemplate yang digunakan dengan StackLayout agar terlihat seperti ini.

LinedFlowLayout

LinedFlowLayout memposisikan elemen secara berurutan dari kiri ke kanan, lalu atas ke bawah, dalam tata letak pembungkusan. Gunakan tata letak ini untuk menampilkan kumpulan item di mana item memiliki tinggi tetap tetapi lebar variabel. Kami merekomendasikannya untuk koleksi berbasis gambar. Tata letak ini juga memiliki animasi bawaan yang diputar ketika koleksi memiliki item yang ditambahkan atau dihapus, dan ketika tampilan diubah ukurannya.

Berikut adalah tampilan item yang memperlihatkan kumpulan foto dalam tata letak alur berbaris.

<ItemsView Width="500" Height="400" HorizontalAlignment="Left"
           ItemTemplate="{StaticResource LinedFlowLayoutItemTemplate}">
    <ItemsView.Layout>
        <LinedFlowLayout ItemsStretch="Fill" 
                         LineHeight="160" 
                         LineSpacing="5"
                         MinItemSpacing="5"/>
    </ItemsView.Layout>
</ItemsView>

LinedFlowLayout menyediakan properti untuk dikontrol:

• ukuran dan penspasian item (LineHeight, LineSpacing, MinItemSpacing)
• pengaturan item (ItemsJustification, ItemsStretch)

UniformGridLayout

UniformGridLayout memposisikan elemen secara berurutan dari kiri ke kanan atau atas ke bawah (tergantung pada Orientasi) dalam tata letak pembungkusan. Setiap item berukuran sama.

Berikut adalah tampilan item yang memperlihatkan kumpulan foto dalam tata letak kisi seragam.

<ItemsView ItemsSource="{x:Bind Photos}" Width="480" Height="400"
           ItemTemplate="{StaticResource PhotoItemTemplate}">
    <ItemsView.Layout>
        <UniformGridLayout MaximumRowsOrColumns="3" 
                           MinRowSpacing="5" 
                           MinColumnSpacing="5"/>
    </ItemsView.Layout>
</ItemsView>

UniformGridLayout menyediakan properti untuk dikontrol:

• apakah tata letak berbasis baris atau kolom (Orientasi)
• jumlah baris atau kolom (MaximumRowsOrColumns)
• ukuran dan penspasian item (MinItemHeight, MinItemWidth, MinColumnSpacing, MinRowSpacing)
• pengaturan item (ItemsJustification, ItemsStretch)

Tip

Gunakan demo interaktif di aplikasi Galeri WinUI 3 untuk melihat efek properti ini secara real time.

Pemilihan dan interaksi item

Anda dapat memilih dari berbagai cara untuk memungkinkan pengguna berinteraksi dengan tampilan item. Secara default, pengguna dapat memilih satu item. Anda dapat mengubah properti SelectionMode untuk mengaktifkan multi-pilihan atau menonaktifkan pilihan. Anda dapat mengatur properti IsItemInvokedEnabled sehingga pengguna mengklik item untuk memanggil tindakan alih-alih memilih item.

Tabel ini memperlihatkan cara pengguna dapat berinteraksi dengan tampilan item, dan bagaimana Anda bisa merespons interaksi.

Untuk mengaktifkan interaksi ini:	Gunakan pengaturan ini:	Tangani kejadian ini:	Gunakan properti ini untuk mendapatkan item yang dipilih:
Tidak ada interaksi	SelectionMode="None" IsItemInvokedEnabled="False"	T/A	T/A
Pilihan tunggal	SelectionMode="Single" IsItemInvokedEnabled="False"	SelectionChanged	SelectedItem
Beberapa pilihan	SelectionMode="Multiple" IsItemInvokedEnabled="False"	SelectionChanged	SelectedItems
Pilihan yang diperluas	SelectionMode="Extended" IsItemInvokedEnabled="False"	SelectionChanged	SelectedItems
Klik	SelectionMode="None" IsItemInvokedEnabled="True"	ItemInvoked	T/A

Catatan

Anda dapat mengaktifkan IsItemInvokedEnabled untuk menaikkan peristiwa ItemInvoked sementara SelectionMode juga diatur ke Single, Multiple, atau Extended. Jika Anda melakukan ini, peristiwa ItemInvoked dinaikkan terlebih dahulu, lalu peristiwa SelectionChanged dinaikkan. Dalam beberapa kasus (misalnya, jika Anda membuka halaman lain di penanganan aktivitas ItemInvoked), peristiwa SelectionChanged tidak dimunculkan dan item tidak dipilih.

Anda dapat mengatur properti ini di XAML atau dalam kode, seperti yang ditunjukkan di sini:

<ItemsView x:Name="myItemsView" SelectionMode="None" IsItemInvokedEnabled="True"/>

myItemsView.SelectionMode = ItemsViewSelectionMode.None;
myItemsView.IsItemInvokedEnabled = true;

Baca-saja

Anda dapat mengatur properti SelectionMode ke ItemsViewSelectionMode.None untuk menonaktifkan pilihan item. Ini menempatkan kontrol dalam mode baca-saja, sehingga digunakan untuk menampilkan data, tetapi tidak untuk berinteraksi dengannya. Artinya, pilihan item dinonaktifkan, tetapi kontrol itu sendiri tidak.

Catatan

Item masih dapat dipilih dan tidak dipilih secara terprogram, tetapi tidak melalui interaksi pengguna.

Pilihan tunggal

Tabel ini menjelaskan interaksi keyboard, mouse, dan sentuhan saat SelectionMode diatur ke Single.

Kunci pengubah	Interaksi
Tidak ada	Pengguna dapat memilih satu item dengan menggunakan bilah spasi, klik mouse, atau ketukan.
Ctrl	Pengguna dapat membatalkan pilihan satu item dengan menggunakan bilah spasi, klik mouse, atau ketukan. Dengan menggunakan tombol panah, pengguna dapat memindahkan fokus independen dari pilihan.

Saat SelectionMode diatur ke Single, Anda bisa mendapatkan item data yang dipilih dari properti SelectedItem . Jika tidak ada item yang dipilih, SelectedItem adalah null.

Jika Anda mencoba mengatur item yang tidak ada dalam koleksi item sebagai SelectedItem, operasi diabaikan dan SelectedItem adalah null.

Indikator pilihan default untuk Single pilihan terlihat seperti ini.

Beberapa pilihan

Tabel ini menjelaskan interaksi keyboard, mouse, dan sentuhan saat SelectionMode diatur ke Multiple.

Kunci pengubah	Interaksi
Tidak ada	Pengguna dapat memilih beberapa item dengan menggunakan bilah spasi, klik mouse, atau ketukan untuk memilih item yang difokuskan. Dengan menggunakan tombol panah, pengguna dapat memindahkan fokus independen dari pilihan mereka.
Shift	Pengguna dapat memilih beberapa item yang berdampingan dengan mengklik atau mengetuk item pertama dalam pilihan lalu mengklik atau mengetuk item terakhir dalam pilihan. Dengan menggunakan tombol panah, pengguna dapat memilih item yang berdampingan yang dimulai dengan item yang dipilih saat mereka memilih tombol Shift.

Indikator pilihan default untuk Multiple pilihan terlihat seperti ini.

Pilihan yang diperluas

Tabel ini menjelaskan interaksi keyboard, mouse, dan sentuhan saat SelectionMode diatur ke Extended.

Kunci pengubah	Interaksi
Tidak ada	Perilakunya sama Single dengan pilihan.
Ctrl	Pengguna dapat memilih beberapa item dengan menggunakan bilah spasi, klik mouse, atau ketukan untuk memilih item yang difokuskan. Dengan menggunakan tombol panah, pengguna dapat memindahkan fokus independen dari pilihan.
Shift	Pengguna dapat memilih beberapa item yang berdampingan dengan mengklik atau mengetuk item pertama dalam pilihan lalu mengklik atau mengetuk item terakhir dalam pilihan. Dengan menggunakan tombol panah, pengguna dapat memilih item yang berdampingan yang dimulai dengan item yang dipilih saat mereka memilih tombol Shift.

Saat SelectionMode diatur ke Multiple atau Extended, Anda bisa mendapatkan item data yang dipilih dari properti SelectedItems .

Properti SelectedItem dan SelectedItems disinkronkan. Misalnya, jika Anda mengatur SelectedItem ke null, SelectedItems kosong. Dalam mode multi-pilih, SelectedItem berisi item yang dipilih terlebih dahulu.

Indikator pilihan default untuk Extended pilihan sama dengan untuk Single pilihan dan terlihat seperti ini.

Mengelola pemilihan item secara terprogram

Catatan

Metode pilihan ini mengabaikan properti SelectionMode dan memiliki efek bahkan ketika SelectionMode adalah Single atau None.

Terkadang, Anda mungkin perlu memanipulasi pilihan item ItemsView secara terprogram. Misalnya, Anda mungkin menampilkan tombol Pilih semua untuk memungkinkan pengguna memilih semua item dalam daftar. Dalam hal ini, biasanya tidak terlalu efisien untuk menambahkan dan menghapus item dari koleksi SelectedItems satu per satu. Lebih efisien menggunakan metode Pilih, PilihSemua, Batal pilih, dan InvertSelection untuk mengubah pilihan daripada menggunakan properti SelectedItems.

Tip

Anda dapat memilih semua item dalam koleksi dengan memanggil metode SelectAll. Tidak ada metode yang sesuai untuk membatalkan pilihan semua item. Namun, Anda dapat membatalkan pilihan semua item dengan memanggil SelectAll diikuti segera oleh InvertSelection.

Mendapatkan kode sampel

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

Artikel terkait

• Panduan untuk daftar
• Kelas ItemsView
• StackLayout
• UniformGridLayout
• LinedFlowLayout