Tutorial: Membuat penampil foto sederhana dengan WinUI 3

Catatan

Untuk informasi tentang manfaat WinUI 3, serta opsi jenis aplikasi lainnya, lihat Gambaran Umum opsi kerangka kerja.

Dalam topik ini kita membahas proses pembuatan proyek WinUI 3 baru di Visual Studio; dan kemudian membangun aplikasi sederhana untuk menampilkan foto. Kita akan menggunakan kontrol, panel tata letak, dan pengikatan data. Dan kami akan menulis markup XAML (yang deklaratif) dan pilihan Anda dari kode C# atau C++ (yang penting, atau prosedural). Gunakan pemilih bahasa di atas judul topik untuk memilih C# atau C++/WinRT.

Petunjuk / Saran

Kode sumber dalam topik ini disediakan dalam C# dan C++/WinRT. Jika Anda adalah pengembang C++, maka untuk detail dan konsep lebih lanjut yang menjelaskan cara kerja kode yang kami tampilkan di sini, lihat dokumentasi C++/WinRT . Topik yang relevan di sana mencakup kontrol XAML; mengikat properti C++/WinRT, kontrol item XAML; mengikat koleksi C++/WinRT, dan aplikasi sampel Photo Editor C++/WinRT.

Langkah 1: Menginstal alat untuk SDK Aplikasi Windows

Untuk menyiapkan komputer pengembangan Anda, lihat Mulai menggunakan WinUI. Dalam artikel itu, Anda juga akan menemukan instruksi untuk membuat dan meluncurkan proyek WinUI 3.

Penting

Anda akan menemukan topik catatan rilis bersama dengan topik saluran rilis SDK Aplikasi Windows. Ada catatan rilis untuk setiap saluran. Pastikan untuk memeriksa batasan dan masalah yang diketahui dalam catatan rilis tersebut, karena hal tersebut dapat memengaruhi hasil berikut bersama dengan tutorial ini dan/atau menjalankan aplikasi yang akan kita buat.

Langkah 2: Membuat proyek baru

Di Visual Studio, buat pilihan proyek C# atau C++ baru Anda dari templat proyek Aplikasi Kosong, Dipaketkan (WinUI 3 di Desktop). Beri nama proyek SimplePhotos, dan (sehingga struktur folder Anda akan cocok dengan yang dijelaskan dalam tutorial ini) hapus centang Tempatkan solusi dan proyek di direktori yang sama. Anda dapat menargetkan rilis terbaru (bukan pratinjau) dari sistem operasi klien.

Langkah 3: Salin file aset

Aplikasi yang akan kita bangun membawa file gambar di sekitarnya dalam bentuk file aset; dan itu adalah foto-foto yang ditampilkannya. Di bagian ini Anda akan menambahkan aset tersebut ke proyek Anda. Tetapi pertama-tama Anda harus mendapatkan salinan file.

1. Jadi kloning (atau unduh sebagai .zip) repositori sampel SDK Aplikasi Windows (lihat WindowsAppSDK-Samples). Setelah melakukannya, Anda akan menemukan file aset yang akan kita gunakan di folder \WindowsAppSDK-Samples\Samples\PhotoEditor\cs-winui\Assets\Samples (gunakan folder ini untuk proyek C# dan C++/WinRT). Jika Anda ingin melihat file-file tersebut di repositori online, maka Anda dapat mengunjungi WindowsAppSDK-Samples/Samples/PhotoEditor/cs-winui/Assets/Samples/.

2. Di File Explorer, pilih folder Sampel tersebut, dan salin ke clipboard.

C#

3. Buka Penjelajah Solusi di Visual Studio. Klik kanan folder Aset (ini adalah anak dari simpul proyek), dan klik Buka Folder di File Explorer. Yang membuka folder Aset di File Explorer.

4. Tempelkan (ke folder Aset ) folder Sampel yang baru saja Anda salin.

C++/WinRT

3. Buka Penjelajah Solusi di Visual Studio. Tambahkan filter baru sebagai anak dari filter Aset ; beri nama filter baru "Sampel". Jika Anda hanya melihat opsi untuk Menambahkan folder baru, maka (dengan simpul proyek yang dipilih) pastikan bahwa Tampilkan Semua File dinonaktifkan.

4. Klik kanan simpul proyek, dan klik Buka Folder di File Explorer. Yang membuka folder proyek di File Explorer.

5. Navigasikan ke folder Aset , dan tempelkan (sebagai anak dari folder Aset ) folder Sampel yang baru saja Anda salin.

6. Kembali ke Penjelajah Solusi di Visual Studio, klik Samples kanan filter >Tambahkan>item yang Sudah Ada....

7. Di pemilih file, navigasikan ke \SimplePhotos\SimplePhotos\Assets\Samples (folder yang baru saja Anda tempel), pilih beberapa semua file aset, dan klik Tambahkan.

Langkah 4: Menambahkan kontrol GridView

Aplikasi kami perlu menampilkan baris dan kolom foto. Dengan kata lain, kisi gambar. Untuk UI seperti itu, kontrol utama yang akan digunakan adalah tampilan Daftar dan tampilan kisi.

1. Buka MainWindow.xaml. Saat ini, ada elemen Window , dan di dalam panel tata letak StackPanel . Di dalam StackPanel adalah kontrol Tombol, yang dikaitkan ke metode penanganan aktivitas.

   Jendela utama aplikasi apa pun mewakili tampilan yang Anda lihat terlebih dahulu saat menjalankan aplikasi. Dalam aplikasi yang akan kita buat, tugas jendela utama adalah memuat foto dari folder Sampel , dan untuk menampilkan tampilan petak gambar tersebut bersama dengan berbagai info tentangnya.

2. Ganti markup StackPanel dan Button dengan panel tata letak Kisi dan kontrol GridView yang diperlihatkan dalam daftar di bawah ini.

   <Window ...>
       <Grid>
           <GridView x:Name="ImageGridView"/>
       </Grid>
   </Window>
   

   Petunjuk / Saran

   x:Name mengidentifikasi elemen XAML sehingga Anda dapat merujuknya ke tempat lain di XAML dan di kode di belakang.

3. C#. Buka MainWindow.xaml.cs, dan hapus metode myButton_Click .

4. C++/WinRT. Buka MainWindow.xaml.h dan MainWindow.xaml.cpp, dan hapus metode myButton_Click .

Anda dapat membangun dan menjalankan sekarang, tetapi jendela akan kosong pada tahap ini. Agar kontrol GridView menampilkan apa pun, kita perlu memberinya kumpulan objek untuk ditampilkan. Kita akan memulainya selanjutnya.

Untuk informasi latar belakang tentang beberapa jenis yang baru saja kami sebutkan, lihat Panel tata letak dan Kontrol untuk aplikasi Windows.

Langkah 5: Model ImageFileInfo

Model (dalam arti model, tampilan, dan model tampilan) adalah kelas yang hingga beberapa derajat mewakili objek atau konsep dunia nyata (seperti rekening bank). Ini adalah abstraksi dari hal dunia nyata. Di bagian ini kita akan menambahkan ke proyek kita kelas baru yang disebut ImageFileInfo. ImageFileInfo akan menjadi model file gambar, seperti foto. Bagian ini akan membawa kita selangkah lebih dekat untuk dapat menampilkan foto di antarmuka pengguna (UI) aplikasi.

Petunjuk / Saran

Dalam persiapan untuk contoh kode di bawah ini, mari kita perkenalkan istilah yang dapat diamati. Properti yang dapat terikat secara dinamis ke kontrol XAML (sehingga UI diperbarui setiap kali nilai properti berubah) dikenal sebagai properti yang dapat diamati. Ide ini didasarkan pada pola desain perangkat lunak yang dikenal sebagai pola pengamat. Dalam aplikasi yang kami bangun dalam tutorial ini, properti model ImageFileInfo kami tidak akan berubah. Namun demikian, kita akan menunjukkan cara membuat ImageFileInfo dapat diamati, dengan mengimplementasikan antarmuka INotifyPropertyChanged.

C#

1. Klik kanan simpul proyek (SimplePhotos), dan klik Tambahkan>Item Baru.... Di bawah Kode Item>C#, pilih Kelas. Atur nama ke ImageFileInfo.cs, dan klik Tambahkan.

2. Ganti konten ImageFileInfo.cs dengan daftar kode di bawah ini.

   using Microsoft.UI.Xaml.Media.Imaging;
   using System;
   using System.ComponentModel;
   using System.Runtime.CompilerServices;
   using System.Threading.Tasks;
   using Windows.Storage;
   using Windows.Storage.FileProperties;
   using Windows.Storage.Streams;
   
   namespace SimplePhotos
   {
       public class ImageFileInfo : INotifyPropertyChanged
       {
           public ImageFileInfo(ImageProperties properties,
               StorageFile imageFile,
               string name,
               string type)
           {
               ImageProperties = properties;
               ImageName = name;
               ImageFileType = type;
               ImageFile = imageFile;
               var rating = (int)properties.Rating;
               var random = new Random();
               ImageRating = rating == 0 ? random.Next(1, 5) : rating;
           }
   
           public StorageFile ImageFile { get; }
   
           public ImageProperties ImageProperties { get; }
   
           public async Task<BitmapImage> GetImageSourceAsync()
           {
               using IRandomAccessStream fileStream = await ImageFile.OpenReadAsync();
   
               // Create a bitmap to be the image source.
               BitmapImage bitmapImage = new();
               bitmapImage.SetSource(fileStream);
   
               return bitmapImage;
           }
   
           public async Task<BitmapImage> GetImageThumbnailAsync()
           {
               StorageItemThumbnail thumbnail = 
                   await ImageFile.GetThumbnailAsync(ThumbnailMode.PicturesView);
               // Create a bitmap to be the image source.
               var bitmapImage = new BitmapImage();
               bitmapImage.SetSource(thumbnail);
               thumbnail.Dispose();
   
               return bitmapImage;
           }
   
           public string ImageName { get; }
   
           public string ImageFileType { get; }
   
           public string ImageDimensions => $"{ImageProperties.Width} x {ImageProperties.Height}";
   
           public string ImageTitle
           {
               get => string.IsNullOrEmpty(ImageProperties.Title) ? ImageName : ImageProperties.Title;
               set
               {
                   if (ImageProperties.Title != value)
                   {
                       ImageProperties.Title = value;
                       _ = ImageProperties.SavePropertiesAsync();
                       OnPropertyChanged();
                   }
               }
           }
   
           public int ImageRating
           {
               get => (int)ImageProperties.Rating;
               set
               {
                   if (ImageProperties.Rating != value)
                   {
                       ImageProperties.Rating = (uint)value;
                       _ = ImageProperties.SavePropertiesAsync();
                       OnPropertyChanged();
                   }
               }
           }
   
           public event PropertyChangedEventHandler PropertyChanged;
   
           protected void OnPropertyChanged([CallerMemberName] string propertyName = null) =>
               PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
       }
   }
   

3. Simpan dan tutup ImageFileInfo.cs file.

C++/WinRT

1. Klik kanan simpul proyek (SimplePhotos), dan klik Tambahkan>Item Baru.... Di bawah Visual C++>Code, pilih File Midl (.idl). Atur nama ke ImageFileInfo.idl, dan klik Tambahkan.

2. Ganti konten ImageFileInfo.idl dengan daftar kode di bawah ini.

   // ImageFileInfo.idl
   namespace SimplePhotos
   {
       runtimeclass ImageFileInfo : Microsoft.UI.Xaml.Data.INotifyPropertyChanged
       {
           ImageFileInfo(Windows.Storage.FileProperties.ImageProperties properties, Windows.Storage.StorageFile imageFile, String name, String type);
           Windows.Storage.FileProperties.ImageProperties ImageProperties{ get; };
           Windows.Storage.StorageFile ImageFile{ get; };
           String ImageName{ get; };
           String ImageFileType{ get; };
           String ImageDimensions{ get; };
           String ImageTitle;
           UInt32 ImageRating;
       }
   }
   

3. Simpan ImageFileInfo.idl, dan bangun proyek. Build belum berhasil (sepenuhnya), tetapi akan menghasilkan beberapa file untuk kami.

4. Jadi sekarang klik kanan simpul proyek lagi, dan klik Buka Folder di File Explorer. Navigasikan ke \Generated Files\sources\ folder, dan salin dua file ImageFileInfo.h dan .cpp ke clipboard. Navigasikan cadangan ke folder proyek (\SimplePhotos\SimplePhotos\), dan tempelkan dua file yang baru saja Anda salin. Terakhir, di Penjelajah Solusi dengan simpul proyek dipilih, pastikan Tampilkan Semua File diaktifkan. Klik kanan dua file yang Anda salin, dan klik Sertakan Dalam Proyek.

5. Tambahkan hal berikut yang diperlukan termasuk ke akhir pch.h file:

   // pch.h
   ...
   #include <winrt/Windows.Storage.FileProperties.h>
   #include <winrt/Windows.Storage.Search.h>
   #include <winrt/Windows.Storage.Streams.h>
   #include <winrt/Microsoft.UI.Xaml.Media.Imaging.h>
   

6. Ganti konten ImageFileInfo.h dengan daftar kode di bawah ini.

   // ImageFileInfo.h
   #pragma once
   #include "ImageFileInfo.g.h"
   
   namespace winrt::SimplePhotos::implementation
   {
       struct ImageFileInfo : ImageFileInfoT<ImageFileInfo>
       {
           ImageFileInfo() = default;
   
           ImageFileInfo(
               winrt::Windows::Storage::FileProperties::ImageProperties const& properties,
               winrt::Windows::Storage::StorageFile const& imageFile,
               hstring const& name,
               hstring const& type);
   
           winrt::Windows::Storage::FileProperties::ImageProperties ImageProperties()
           {
               return m_imageProperties;
           }
   
           winrt::Windows::Storage::StorageFile ImageFile()
           {
               return m_imageFile;
           }
   
           hstring ImageName()
           {
               return m_imageName;
           }
   
           hstring ImageFileType()
           {
               return m_imageFileType;
           }
   
           hstring ImageDimensions()
           {
               return to_hstring(ImageProperties().Width()) + L" x " + to_hstring(ImageProperties().Height());
           }
   
           hstring ImageTitle()
           {
               return ImageProperties().Title() == L"" ? ImageName() : ImageProperties().Title();
           }
   
           void ImageTitle(hstring const& value);
   
           uint32_t ImageRating()
           {
               return ImageProperties().Rating();
           }
   
           void ImageRating(uint32_t value);
   
           winrt::event_token PropertyChanged(winrt::Microsoft::UI::Xaml::Data::PropertyChangedEventHandler const& handler)
           {
               return m_propertyChanged.add(handler);
           }
   
           void PropertyChanged(winrt::event_token const& token) noexcept
           {
               m_propertyChanged.remove(token);
           }
   
           Windows::Foundation::IAsyncOperation<Microsoft::UI::Xaml::Media::Imaging::BitmapImage> GetImageSourceAsync();
   
           Windows::Foundation::IAsyncOperation<Microsoft::UI::Xaml::Media::Imaging::BitmapImage> GetImageThumbnailAsync();
   
       private:
           // File and information fields.
           Windows::Storage::FileProperties::ImageProperties m_imageProperties{ nullptr };
           Windows::Storage::StorageFile m_imageFile{ nullptr };
           hstring m_imageName;
           hstring m_imageFileType;
   
           event<Microsoft::UI::Xaml::Data::PropertyChangedEventHandler> m_propertyChanged;
           void OnPropertyChanged(hstring propertyName)
           {
               m_propertyChanged(*this, Microsoft::UI::Xaml::Data::PropertyChangedEventArgs(propertyName));
           }
       };
   }
   namespace winrt::SimplePhotos::factory_implementation
   {
       struct ImageFileInfo : ImageFileInfoT<ImageFileInfo, implementation::ImageFileInfo>
       {
       };
   }
   

7. Ganti konten ImageFileInfo.cpp dengan daftar kode di bawah ini.

   // ImageFileInfo.cpp
   #include "pch.h"
   #include "ImageFileInfo.h"
   #include "ImageFileInfo.g.cpp"
   #include <random>
   
   using namespace std;
   namespace winrt
   {
       using namespace Microsoft::UI::Xaml;
       using namespace Microsoft::UI::Xaml::Media::Imaging;
       using namespace Windows::Foundation;
       using namespace Windows::Storage;
       using namespace Windows::Storage::FileProperties;
       using namespace Windows::Storage::Streams;
   }
   
   namespace winrt::SimplePhotos::implementation
   {
       ImageFileInfo::ImageFileInfo(
           winrt::Windows::Storage::FileProperties::ImageProperties const& properties,
           winrt::Windows::Storage::StorageFile const& imageFile,
           hstring const& name,
           hstring const& type) :
           m_imageProperties{ properties },
           m_imageName{ name },
           m_imageFileType{ type },
           m_imageFile{ imageFile }
       {
           auto rating = properties.Rating();
           auto random = std::random_device();
           std::uniform_int_distribution<> dist(1, 5);
           ImageRating(rating == 0 ? dist(random) : rating);
       }
   
       void ImageFileInfo::ImageTitle(hstring const& value)
       {
           if (ImageProperties().Title() != value)
           {
               ImageProperties().Title(value);
               ImageProperties().SavePropertiesAsync();
               OnPropertyChanged(L"ImageTitle");
           }
       }
   
       void ImageFileInfo::ImageRating(uint32_t value)
       {
           if (ImageProperties().Rating() != value)
           {
               ImageProperties().Rating(value);
               ImageProperties().SavePropertiesAsync();
               OnPropertyChanged(L"ImageRating");
           }
       }
   
       IAsyncOperation<BitmapImage> ImageFileInfo::GetImageSourceAsync()
       {
           IRandomAccessStream stream{ co_await ImageFile().OpenAsync(FileAccessMode::Read) };
           BitmapImage bitmap{};
           bitmap.SetSource(stream);
           co_return bitmap;
       }
   
       IAsyncOperation<BitmapImage> ImageFileInfo::GetImageThumbnailAsync()
       {
           auto thumbnail = co_await m_imageFile.GetThumbnailAsync(FileProperties::ThumbnailMode::PicturesView);
           BitmapImage bitmapImage{};
           bitmapImage.SetSource(thumbnail);
           thumbnail.Close();
           co_return bitmapImage;
       }
   }
   

8. Konfirmasikan bahwa Anda dapat membuat (tetapi belum berjalan).

Langkah 6: Tentukan dan isi properti untuk kumpulan gambar

Di bagian ini kita akan menambahkan properti baru ke kelas MainWindow . Properti (bernama Gambar) akan menjadi kelas koleksi yang berisi gambar yang ingin kita tampilkan.

C#

1. Tentukan properti seperti ini, di MainWindow.xaml.cs:

   ...
   using System.Collections.ObjectModel;
   ...
   namespace SimplePhotos
   {
       public sealed partial class MainWindow : Window
       {
           public ObservableCollection<ImageFileInfo> Images { get; } = 
               new ObservableCollection<ImageFileInfo>();
           ...
       }
   }
   

2. Kode untuk mengisi properti koleksi baru dengan gambar ditampilkan dalam metode GetItemsAsync dan LoadImageInfoAsync di bawah ini. Tempelkan direktif using , dan dua implementasi metode, ke dalam MainWindow.xaml.cs, juga. Metode ini adalah anggota kelas MainWindow , jadi tempelkan di dalam sana seperti yang Anda lakukan dengan properti Gambar di atas.

   ...
   using System.Threading.Tasks;
   using Windows.ApplicationModel;
   using Windows.Storage;
   using Windows.Storage.Search;
   ...
   private async Task GetItemsAsync()
   {
       StorageFolder appInstalledFolder = Package.Current.InstalledLocation;
       StorageFolder picturesFolder = await appInstalledFolder.GetFolderAsync("Assets\\Samples");
   
       var result = picturesFolder.CreateFileQueryWithOptions(new QueryOptions());
   
       IReadOnlyList<StorageFile> imageFiles = await result.GetFilesAsync();
       foreach (StorageFile file in imageFiles)
       {
           Images.Add(await LoadImageInfoAsync(file));
       }
   
       ImageGridView.ItemsSource = Images;
   }
   
   public async static Task<ImageFileInfo> LoadImageInfoAsync(StorageFile file)
   {
       var properties = await file.Properties.GetImagePropertiesAsync();
       ImageFileInfo info = new(properties, 
                                file, file.DisplayName, file.DisplayType);
   
       return info;
   }
   

3. Hal terakhir yang perlu kita lakukan di bagian ini adalah memperbarui konstruktor MainWindow untuk memanggil GetItemsAsync.

   public MainWindow()
   {
       ...
       GetItemsAsync();
   }
   

C++/WinRT

1. Kami akan merujuk properti Gambar di UI XAML kami. Untuk alasan itu, kita perlu mendeklarasikan properti Gambar dalam file IDL untuk kelas MainWindow. Jadi ganti konten MainWindow.idl dengan daftar kode di bawah ini.

   // MainWindow.idl
   namespace SimplePhotos
   {
       [default_interface]
       runtimeclass MainWindow : Microsoft.UI.Xaml.Window
       {
           MainWindow();
           Windows.Foundation.Collections.IVector<IInspectable> Images{ get; };
       }
   }
   

2. Saat kami mengedit kelas MainWindow , lanjutkan dan hapus properti MyProperty dari MainWindow.idl (sudah dihapus dalam daftar di atas), dan dari MainWindow.h, dan dari MainWindow.cpp.

3. Kode untuk mengisi properti koleksi baru dengan gambar ditampilkan dalam metode GetItemsAsync dan LoadImageInfoAsync di bawah ini. Tempelkan include, arahan using namespace , dan dua deklarasi dan definisi metode, ke dalam MainWindow.xaml.h dan MainWindow.xaml.cpp.

   // MainWindow.xaml.h
   ...
   struct MainWindow : MainWindowT<MainWindow>
   {
       ...
   
       Windows::Foundation::Collections::IVector<Windows::Foundation::IInspectable> Images() const
       {
           return m_images;
       }
   
   private:
       Windows::Foundation::Collections::IVector<IInspectable> m_images{ nullptr };
   
       Windows::Foundation::IAsyncAction GetItemsAsync();
       Windows::Foundation::IAsyncOperation<SimplePhotos::ImageFileInfo> LoadImageInfoAsync(Windows::Storage::StorageFile);
   };
   ...
   

   // MainWindow.xaml.cpp
   ...
   #include "ImageFileInfo.h"
   namespace winrt
   {
       using namespace Windows::ApplicationModel;
       using namespace Windows::Foundation;
       using namespace Windows::Foundation::Collections;
       using namespace Windows::Storage;
       using namespace Windows::Storage::Search;
       using namespace Microsoft::UI::Xaml;
   }
   ...
   IAsyncAction MainWindow::GetItemsAsync()
   {
       StorageFolder appInstalledFolder = Package::Current().InstalledLocation();
       StorageFolder picturesFolder = co_await appInstalledFolder.GetFolderAsync(L"Assets\\Samples");
   
       auto result = picturesFolder.CreateFileQueryWithOptions(QueryOptions());
   
       IVectorView<StorageFile> imageFiles = co_await result.GetFilesAsync();
       for (auto&& file : imageFiles)
       {
           Images().Append(co_await LoadImageInfoAsync(file));
       }
   
       ImageGridView().ItemsSource(Images());
   }
   
   IAsyncOperation<SimplePhotos::ImageFileInfo> MainWindow::LoadImageInfoAsync(StorageFile file)
   {
       auto properties = co_await file.Properties().GetImagePropertiesAsync();
       SimplePhotos::ImageFileInfo info(properties,
                          file, file.DisplayName(), file.DisplayType());
       co_return info;
   }
   ...
   

4. Hal terakhir yang perlu kita lakukan di bagian ini adalah memperbarui konstruktor MainWindow untuk menginisialisasi anggota data m_images , dan untuk memanggil GetItemsAsync.

   // MainWindow.xaml.cpp
   MainWindow::MainWindow() :
       m_images(winrt::single_threaded_observable_vector<IInspectable>())
   {
       InitializeComponent();
       GetItemsAsync();
   }
   

Anda dapat membangun dan menjalankan sekarang jika Anda mau (untuk mengonfirmasi bahwa Anda telah mengikuti langkah-langkah ok), tetapi tidak banyak yang bisa dilihat di jendela pada tahap ini. Itu karena apa yang telah kita lakukan sejauh ini adalah meminta GridView untuk merender kumpulan objek jenis ImageFileInfo; dan GridView belum cukup tahu cara melakukannya.

Ingatlah bahwa properti Gambar adalah kumpulan objek ImageFileInfo yang dapat diamati. Dan baris terakhir GetItemsAsync memberi tahu GridView (yang bernama ImageGridView) bahwa sumber itemnya (ItemsSource) adalah properti Gambar. Dan pekerjaan GridView kemudian adalah menampilkan item tersebut.

Tetapi kami belum memberi tahu GridView apa pun tentang kelas ImageFileInfo . Jadi yang terbaik yang dapat dilakukan sejauh ini adalah menampilkan nilai ToString dari setiap objek ImageFileInfo dalam koleksi. Dan secara default, itu hanya nama jenis. Di bagian berikutnya kita akan membuat templat data untuk menentukan bagaimana kita ingin objek ImageFileInfo ditampilkan.

Petunjuk / Saran

Saya menggunakan istilah koleksi yang dapat diamati di atas. Dalam aplikasi yang kita buat dalam tutorial ini, jumlah gambar tidak berubah (dan seperti yang telah kami katakan, juga tidak melakukan nilai properti dari setiap gambar). Tetapi masih nyaman, dan praktik yang baik, untuk menggunakan pengikatan data untuk awalnya menghubungkan UI ke data. Jadi itulah yang akan kita lakukan.

Langkah 7: Menambahkan templat data

Untuk memulainya, mari kita gunakan templat data tempat penampung seperti sketsa. Itu akan berfungsi sampai kita selesai menjelajahi beberapa opsi tata letak. Setelah itu kita dapat memperbarui templat data untuk menampilkan foto yang sebenarnya.

Petunjuk / Saran

Itu sebenarnya hal yang sangat praktis untuk dilakukan. Ditemukan bahwa jika UI terlihat seperti sketsa (dengan kata lain, keakuratan rendah), maka orang lebih bersedia untuk menyarankan dan/atau menguji ide cepat dengannya—terkadang melibatkan perubahan yang cukup substansial. Itu karena kita menebak (dengan benar) bahwa perubahan seperti itu akan murah untuk dicoba.

Di sisi lain, semakin selesai UI terlihat (semakin tinggi keakuratannya), semakin kita menebak (sekali lagi, dengan benar) bahwa banyak pekerjaan telah masuk ke tampilan saat ini. Dan itu membuat kita kurang cenderung untuk menyarankan, atau untuk mencoba, ide-ide baru.

1. Buka MainWindow.xaml, dan ubah konten Jendela sehingga terlihat seperti markup ini:

   <Window ...>
       <Grid>
           <Grid.Resources>
               <DataTemplate x:Key="ImageGridView_ItemTemplate">
                   <Grid/>
               </DataTemplate>
           </Grid.Resources>
           <GridView x:Name="ImageGridView"
                   ItemTemplate="{StaticResource ImageGridView_ItemTemplate}">
           </GridView>
       </Grid>
   </Window>
   

   Ke akar tata letak, kami telah menambahkan sumber daya DataTemplate sederhana, dan memberinya kunci .ImageGridView_ItemTemplate Dan kami telah menggunakan kunci yang sama untuk mengatur ItemTemplate dari GridView. Kontrol item seperti GridView memiliki properti ItemTemplate (sama seperti mereka memiliki properti ItemsSource yang kita lihat sebelumnya). Templat item adalah templat data; dan digunakan untuk menampilkan setiap item dalam koleksi.

   Untuk informasi selengkapnya, lihat Kontainer dan templat item.

2. Sekarang kita dapat mengambil beberapa edit melewati templat data —menambahkan ke, dan mengedit, elemen di dalamnya untuk membuatnya lebih menarik dan berguna. Kita akan memberi Kisi akar tinggi dan lebar 300, dan margin 8. Kemudian kita akan menambahkan dua definisi baris, dan mengatur tinggi definisi baris kedua ke Otomatis.

   <DataTemplate x:Key="ImageGridView_ItemTemplate">
       <Grid Height="300"
             Width="300"
             Margin="8">
           <Grid.RowDefinitions>
               <RowDefinition />
               <RowDefinition Height="Auto" />
           </Grid.RowDefinitions>
       </Grid>
   </DataTemplate>
   

   Untuk informasi selengkapnya, lihat Perataan, margin, padding.

3. Kami ingin templat data menampilkan gambar, nama, jenis file, dimensi, dan peringkat setiap foto. Jadi kita akan menambahkan, masing-masing, kontrol Gambar, beberapa kontrol TextBlock, dan kontrol RatingControl. Kita akan menjabarkan teks di dalam panel tata letak StackPanel. Gambar awalnya akan menampilkan logo Microsoft Store seperti sketsa proyek sebagai tempat penampung.

4. Setelah semua pengeditan tersebut, berikut tampilan templat data:

   <DataTemplate x:Key="ImageGridView_ItemTemplate">
       <Grid Height="300"
             Width="300"
             Margin="8">
           <Grid.RowDefinitions>
               <RowDefinition />
               <RowDefinition Height="Auto" />
           </Grid.RowDefinitions>
   
           <Image x:Name="ItemImage"
                  Source="Assets/StoreLogo.png"
                  Stretch="Uniform" />
   
           <StackPanel Orientation="Vertical"
                       Grid.Row="1">
               <TextBlock Text="ImageTitle"
                          HorizontalAlignment="Center"
                          Style="{StaticResource SubtitleTextBlockStyle}" />
               <StackPanel Orientation="Horizontal"
                           HorizontalAlignment="Center">
                   <TextBlock Text="ImageFileType"
                              HorizontalAlignment="Center"
                              Style="{StaticResource CaptionTextBlockStyle}" />
                   <TextBlock Text="ImageDimensions"
                              HorizontalAlignment="Center"
                              Style="{StaticResource CaptionTextBlockStyle}"
                              Margin="8,0,0,0" />
               </StackPanel>
   
               <RatingControl Value="3" IsReadOnly="True"/>
           </StackPanel>
       </Grid>
   </DataTemplate>
   

Bangun proyek sekarang, dan jalankan aplikasi untuk melihat kontrol GridView dengan templat item yang baru saja Anda buat. Selanjutnya, kita akan melihat bagaimana item ditata. Kita akan mengubah beberapa kuas, dan kita akan menambahkan ruang di antara item.

Langkah 8: Mengedit gaya kontainer item

Konsep lain yang terkait dengan kontrol item seperti GridView adalah kontainer item. Kontainer item adalah kontrol konten yang menampilkan item sebagai nilai properti Kontennya. Kontrol item membuat kontainer item sebanyak yang diperlukan untuk menampilkan item yang terlihat di layar kapan saja.

Menjadi kontrol, kontainer item memiliki gaya dan templat kontrol. Gaya dan templat kontrolnya menentukan bagaimana kontainer item terlihat dalam berbagai statusnya (seperti pemilihan, penunjuk, dan fokus). Dan, seperti yang telah kita lihat, templat item (yang merupakan templat data) menentukan tampilan item itu sendiri.

Untuk GridView, jenis kontainer itemnya adalah GridViewItem.

Jadi di bagian ini kita akan fokus pada desain gaya kontainer item. Dan untuk itu kita akan membuat sumber daya Gaya untuk GridViewItem, lalu mengaturnya sebagai ItemContainerStyle dari *GridView. Dalam gaya, kita akan mengatur properti Latar Belakang dan Margin kontainer item untuk memberinya latar belakang abu-abu dan sedikit margin di luarnya.

1. Di MainWindow.xaml, tambahkan sumber daya Gaya baru ke elemen XML Grid.Resources yang sama tempat kita memasukkan templat data.

   <Grid>
       <Grid.Resources>
       ...
           <Style x:Key="ImageGridView_ItemContainerStyle"
               TargetType="GridViewItem">
               <Setter Property="Background" Value="Gray"/>
               <Setter Property="Margin" Value="8"/>
           </Style>
       </Grid.Resources>
   

2. Selanjutnya, kita menggunakan kunci ImageGridView_ItemContainerStyle untuk mengatur ItemContainerStyle dari GridView.

   <GridView x:Name="ImageGridView"
           ...
           ItemContainerStyle="{StaticResource ImageGridView_ItemContainerStyle}">
   </GridView>
   

Buat dan jalankan aplikasi, dan lihat tampilannya sekarang. Saat Anda mengubah ukuran jendela, kontrol GridView mengurus pengaturan ulang item agar paling sesuai dengan ruang. Pada beberapa lebar, ada banyak ruang di sisi kanan jendela aplikasi. Akan terlihat lebih baik jika GridView, dan/atau kontennya, dipusatkan. Jadi kita akan mengurus itu berikutnya.

Petunjuk / Saran

Jika Anda ingin bereksperimen, coba atur setter Latar Belakang dan Margin ke nilai yang berbeda untuk melihat efek apa yang dimiliki.

Langkah 9: Bereksperimen dengan tata letak

Anda mungkin bertanya-tanya apakah yang terbaik adalah mempusatkan GridView itu sendiri, atau untuk mempusatkan kontennya. Mari kita coba pusatkan GridView terlebih dahulu.

1. Untuk memudahkan untuk melihat dengan tepat di mana GridView berada di Jendela—dan apa yang terjadi saat kita bereksperimen dengan tata letak—kita akan mengatur properti Latar Belakangnya menjadi merah.

   <GridView x:Name="ImageGridView"
           ...
           Background="Red">
   </GridView>
   

2. Dan sekarang kita akan mengatur properti HorizontalAlignment-nya ke Tengah.

   <GridView x:Name="ImageGridView"
           ...
           HorizontalAlignment="Center">
   </GridView>
   

   Lihat juga Perataan, margin, padding.

Bangun dan jalankan sekarang, dan bereksperimenlah dengan menyesuaikan lebar jendela. Anda dapat melihat bahwa ada jumlah ruang kosong yang sama di salah satu sisi latar belakang merah GridView. Jadi, kami telah mencapai tujuan untuk mempusatkan gambar. Tetapi sekarang lebih jelas daripada sebelumnya bahwa bilah gulir milik GridView, dan bukan ke jendela. Jadi kita perlu mengubah GridView kembali untuk mengisi jendela. Kami telah menunjukkan bahwa (alih-alih memusatkan GridView di jendela) kita perlu memusatkan gambar di GridView.

3. Jadi sekarang hapus atribut HorizontalAlignment yang Anda tambahkan di langkah sebelumnya.

Langkah 10: Edit templat panel item

Item mengontrol tata letak kontainer item mereka di dalam apa yang dikenal sebagai panel item. Kita dapat menentukan jenis panel apa yang digunakan, dan mengatur properti di panel tersebut, dengan mengedit templat panel item GridView. Jadi itulah yang akan kita lakukan di bagian ini.

1. Di MainWindow.xaml, tambahkan sumber daya ItemsPanelTemplate ke kamus sumber daya kami. Panel item berjenis ItemsWrapGrid, dan kami mengatur properti HorizontalAlignment-nyake Tengah.

   <Grid>
       <Grid.Resources>
       ...
           <ItemsPanelTemplate x:Key="ImageGridView_ItemsPanelTemplate">
               <ItemsWrapGrid Orientation="Horizontal"
                              HorizontalAlignment="Center"/>
           </ItemsPanelTemplate>
       </Grid.Resources>
   

2. Selanjutnya, kita menggunakan kunci ImageGridView_ItemsPanelTemplate untuk mengatur ItemsPanel dari GridView.

   <GridView x:Name="ImageGridView"
           ...
           ItemsPanel="{StaticResource ImageGridView_ItemsPanelTemplate}">
   </GridView>
   

Saat Anda membangun dan menjalankan kali ini, dan bereksperimen dengan menyesuaikan lebar jendela, ada jumlah latar belakang merah GridView yang sama di kedua sisi gambar. Dan karena GridView mengisi jendela, bilah gulir selaras dengan baik dengan tepi jendela, di mana pengguna mungkin mengharapkannya.

3. Sekarang setelah kita selesai bereksperimen dengan tata letak, hapus Background="Red" dari GridView.

Langkah 11: Ganti gambar tempat penampung dengan foto

Sekarang saatnya untuk memindahkan sketsa kita ke tingkat keakuratan yang lebih tinggi; dan itu berarti mengganti gambar tempat penampung dengan gambar asli, dan mengganti teks tempat penampung gaya "lorem ipsum" dengan data nyata. Mari kita mengurus gambar terlebih dahulu.

Penting

Teknik yang akan kita gunakan untuk menampilkan foto di Assets\Samples folder melibatkan pembaruan item GridView secara progresif. Secara khusus, itulah kode dalam metode ImageGridView_ContainerContentChanging dan ShowImage dalam contoh kode di bawah ini, termasuk penggunaan properti ContainerContentChangingEventArgs.InRecycleQueue dan ContainerContentChangingEventArgs.Phase . Untuk informasi selengkapnya, lihat Pengoptimalan UI ListView dan GridView. Namun singkatnya, GridView akan memberi tahu kami (dengan cara acara) ketika salah satu kontainer itemnya siap menampilkan itemnya. Dan kemudian kita akan melacak fase mana dari siklus hidup pembaruannya tempat kontainer item berada sehingga kita dapat menentukan kapan siap untuk menampilkan data foto.

C#

1. Di MainWindow.xaml.cs, tambahkan metode baru ke MainWindow bernama ImageGridView_ContainerContentChanging. Ini adalah metode penanganan peristiwa, dan peristiwa yang ditanganinya adalah ContainerContentChanging. Kita juga perlu memberikan implementasi metode ShowImage yang ImageGridView_ContainerContentChanging tergantung pada. Tempel direktif using dan dua implementasi metode ke dalam MainWindow.xaml.cs:

   ...
   using Microsoft.UI.Xaml.Controls;
   ...
   private void ImageGridView_ContainerContentChanging(
       ListViewBase sender,
       ContainerContentChangingEventArgs args)
   {
       if (args.InRecycleQueue)
       {
           var templateRoot = args.ItemContainer.ContentTemplateRoot as Grid;
           var image = templateRoot.FindName("ItemImage") as Image;
           image.Source = null;
       }
   
       if (args.Phase == 0)
       {
           args.RegisterUpdateCallback(ShowImage);
           args.Handled = true;
       }
   }
   
   private async void ShowImage(ListViewBase sender, ContainerContentChangingEventArgs args)
   {
       if (args.Phase == 1)
       {
           // It's phase 1, so show this item's image.
           var templateRoot = args.ItemContainer.ContentTemplateRoot as Grid;
           var image = templateRoot.FindName("ItemImage") as Image;
           var item = args.Item as ImageFileInfo;
           image.Source = await item.GetImageThumbnailAsync();
       }
   }
   

C++/WinRT

1. Tambahkan metode baru ke MainWindow bernama ImageGridView_ContainerContentChanging. Ini adalah metode penanganan peristiwa, dan peristiwa yang ditanganinya adalah ContainerContentChanging. Kita juga perlu memberikan implementasi metode ShowImage yang ImageGridView_ContainerContentChanging tergantung pada. Tempelkan direktif using namespace dan dua deklarasi metode dan definisi ke dalam MainWindow.xaml.h dan MainWindow.xaml.cpp:

   // MainWindow.xaml.h
   ...
   struct MainWindow : MainWindowT<MainWindow>
   {
       ...
       void ImageGridView_ContainerContentChanging(
           Microsoft::UI::Xaml::Controls::ListViewBase const& sender,
           Microsoft::UI::Xaml::Controls::ContainerContentChangingEventArgs const& args);
   
   private:
       ...
       fire_and_forget ShowImage(
           Microsoft::UI::Xaml::Controls::ListViewBase const& sender,
           Microsoft::UI::Xaml::Controls::ContainerContentChangingEventArgs const& args);
   };
   ...
   

   // MainWindow.xaml.cpp
   ...
   namespace winrt
   {
       ...
       using namespace Microsoft::UI::Xaml::Controls;
   }
   ...
   void MainWindow::ImageGridView_ContainerContentChanging(ListViewBase const& sender, ContainerContentChangingEventArgs const& args)
   {
       if (args.InRecycleQueue())
       {
           auto templateRoot = args.ItemContainer().ContentTemplateRoot().try_as<Grid>();
           auto image = templateRoot.FindName(L"ItemImage").try_as<Image>();
           image.Source(nullptr);
       }
       if (args.Phase() == 0)
       {
           args.RegisterUpdateCallback({ this, &MainWindow::ShowImage });
           args.Handled(true);
       }
   }
   
   fire_and_forget MainWindow::ShowImage(ListViewBase const& sender, ContainerContentChangingEventArgs const& args)
   {
       if (args.Phase() == 1)
       {
           // It's phase 1, so show this item's image.
           auto templateRoot = args.ItemContainer().ContentTemplateRoot().try_as<Grid>();
           auto image = templateRoot.FindName(L"ItemImage").try_as<Image>();
           auto item = args.Item().try_as<SimplePhotos::ImageFileInfo>();
           image.Source(co_await get_self<SimplePhotos::implementation::ImageFileInfo>(item)->GetImageThumbnailAsync());
       }
   }
   ...
   

2. Kemudian, di MainWindow.xaml, daftarkan penanganan aktivitas ImageGridView_ContainerContentChanging dengan peristiwa ContainerContentChanging GridView.

   <GridView x:Name="ImageGridView"
           ...
           ContainerContentChanging="ImageGridView_ContainerContentChanging">
   </GridView>
   

Langkah 12: Ganti teks tempat penampung dengan data nyata

Di bagian ini kita akan menggunakan pengikatan data satu kali. Pengikatan satu kali sangat bagus untuk data yang tidak berubah pada run-time. Dan itu berarti bahwa pengikatan satu kali berkinerja tinggi dan mudah dibuat.

1. Di MainWindow.xaml, temukan sumber daya templat data ImageGridView_ItemTemplate . Kita akan memberi tahu templat data bahwa tugasnya adalah menjadi templat untuk kelas ImageFileInfo, yang akan Anda ingat adalah jenis item yang ditampilkan GridView kami.

2. Untuk melakukannya, tambahkan x:DataType nilai ke templat, seperti ini:

   <DataTemplate x:Key="ImageGridView_ItemTemplate"
                 x:DataType="local:ImageFileInfo">
       ...
   

   Jika Anda tidak terbiasa dengan local: sintaks yang ditunjukkan di atas (atau dengan xmlns:local sintaks yang sudah ada di tag Jendela pembuka), lihat namespace XAML dan pemetaan namespace layanan.

   Sekarang setelah kita mengatur x:DataType, kita dapat menggunakan x:Bind ekspresi pengikatan data dalam templat data untuk mengikat properti jenis data yang kita tentukan (ImageFileInfo, dalam hal ini).

3. Dalam templat data, temukan elemen TextBlock pertama (yang teksnya saat ini diatur ke ImageTitle). Ganti nilai Teks seperti yang ditunjukkan di bawah ini.

   Petunjuk / Saran

   Anda dapat menyalin dan menempelkan markup di bawah ini, atau Anda dapat menggunakan IntelliSense di Visual Studio. Untuk melakukannya, pilih nilai saat ini yang ada di dalam tanda kutip, dan ketik {. IntelliSense secara otomatis menambahkan kurung kurawal penutup, dan menampilkan daftar penyelesaian kode. Anda dapat menggulir ke bawah ke x:Bind, dan mengklik dua kali. Tetapi mungkin lebih efisien untuk mengetik x: (perhatikan bagaimana x:Bind kemudian difilter ke bagian atas daftar penyelesaian), dan tekan tombol TAB. Sekarang tekan tombol SPACE, dan ketik ImageT (sebanyak mungkin nama ImageTitle properti yang diperlukan untuk mendapatkannya ke bagian atas daftar penyelesaian), dan TAB.

   <TextBlock Text="{x:Bind ImageTitle}"
       ... />
   

   Ekspresi x:Bind menautkan nilai properti UI dengan nilai properti objek data. Tentu saja, itu tergantung pada pengaturan x:DataType pertama ke jenis objek data tersebut sehingga alat dan runtime mengetahui properti apa yang tersedia untuk diikat.

   Untuk informasi selengkapnya, lihat ekstensi markup {x:Bind} dan Pengikatan data secara mendalam.

4. Dengan cara yang sama, ganti nilai TextBlocks lainnya dan RatingControl. Berikut hasilnya:

   <TextBlock Text="{x:Bind ImageTitle}" ... />
   <StackPanel ... >
       <TextBlock Text="{x:Bind ImageFileType}" ... />
       <TextBlock Text="{x:Bind ImageDimensions}" ... />
   </StackPanel>
   <RatingControl Value="{x:Bind ImageRating}" ... />
   

Jika Anda membuat dan menjalankan aplikasi sekarang, alih-alih tempat penampung, Anda akan melihat foto nyata, dan teks nyata (dan data lainnya). Secara visual dan fungsional, aplikasi kecil sederhana ini sekarang selesai. Tapi sebagai coda, mari kita lakukan sedikit pengikatan data terakhir.

Langkah 13: Ikat GridView ke koleksi Gambar (hanya C#)

Penting

Lakukan langkah terakhir ini hanya jika Anda membuat proyek C#.

Petunjuk / Saran

Anda akan menemukan bahwa ada beberapa hal (biasanya terkait dengan UI yang dihasilkan secara dinamis) yang tidak dapat Anda lakukan di markup XAML. Tetapi secara umum jika Anda dapat melakukan sesuatu dalam markup, maka itu lebih disukai. Ini memberikan pemisahan yang sedikit lebih bersih antara tampilan yang diwakili markup XAML dan model (atau model tampilan) yang diwakili kode imperatif. Dan itu cenderung meningkatkan alur kerja dalam alat dan antar anggota tim.

Saat ini kami menggunakan kode imperatif untuk mengaitkan properti GridView's ItemsSource) dengan properti Gambar MainWindow. Tapi kita bisa melakukannya dalam markup sebagai gantinya.

1. Di kelas MainWindow, hapus (atau beri komentar) baris terakhir GetItemsAsync, yang mengatur ItemsSourceImageGridView ke nilai properti Gambar.

2. Lalu di MainWindow.xaml, temukan GridView bernama ImageGridView, dan tambahkan atribut ItemsSource seperti ini. Anda dapat menggunakan IntelliSense untuk membuat perubahan ini jika Mau.

   <GridView x:Name="ImageGridView"
             ...
             ItemsSource="{x:Bind Images}"
   

Nilai properti Gambar tidak berubah pada run-time untuk aplikasi tertentu ini. Tetapi karena Gambar berjenis ObservableCollection<T> , konten koleksi dapat berubah (yaitu, elemen dapat ditambahkan atau dihapus), dan pengikatan akan secara otomatis melihat perubahan dan memperbarui UI.

Kesimpulan

Dalam tutorial ini kami berjalan melalui proses penggunaan Visual Studio untuk membangun aplikasi WinUI 3 sederhana yang menampilkan foto. Mudah-mudahan tutorial ini telah memberi Anda pengalaman bekerja di aplikasi WinUI 3 dengan kontrol, panel tata letak, pengikatan data, dan pengoptimalan UI GridView.

Lihat juga

Tutorial: Membangun penampil foto sederhana yang menargetkan beberapa platform