Bagikan melalui


Tampilan kalender

Tampilan kalender memungkinkan pengguna menampilkan dan berinteraksi dengan kalender yang bisa mereka navigasikan menurut bulan, tahun, atau dekade. Pengguna dapat memilih satu tanggal atau rentang tanggal. Ini tidak memiliki permukaan pemilih dan kalender selalu terlihat.

Apakah ini kontrol yang tepat?

Gunakan tampilan kalender untuk memungkinkan pengguna memilih satu tanggal atau rentang tanggal dari kalender yang selalu terlihat.

Jika Anda perlu mengizinkan pengguna memilih beberapa tanggal sekali pakai, Anda harus menggunakan tampilan kalender. Jika Anda perlu membiarkan pengguna hanya memilih satu tanggal dan tidak memerlukan kalender untuk selalu terlihat, pertimbangkan untuk menggunakan pemilih tanggal kalender atau kontrol pemilih tanggal.

Untuk informasi selengkapnya tentang memilih kontrol yang tepat, lihat artikel Kontrol tanggal dan waktu.

Contoh

Tampilan kalender terdiri dari 3 tampilan terpisah: tampilan bulan, tampilan tahun, dan tampilan dekade. Secara default, dimulai dengan tampilan bulan terbuka. Anda dapat menentukan tampilan startup dengan mengatur properti DisplayMode .

3 tampilan tampilan kalender

Pengguna mengklik header dalam tampilan bulan untuk membuka tampilan tahun, dan klik header dalam tampilan tahun untuk membuka tampilan dekade. Pengguna memilih tahun dalam tampilan dekade untuk kembali ke tampilan tahun, dan memilih sebulan dalam tampilan tahunan untuk kembali ke tampilan bulan. Dua panah ke sisi header menavigasi maju atau mundur menurut bulan, menurut tahun, atau dengan dekade.

UWP dan WinUI 2

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

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

Contoh ini memperlihatkan cara membuat tampilan kalender sederhana.

<CalendarView/>

Tampilan kalender yang dihasilkan terlihat seperti ini:

Contoh tampilan kalender

Memilih tanggal

Secara default, properti SelectionMode diatur ke Tunggal. Ini memungkinkan pengguna memilih satu tanggal di kalender. Atur SelectionMode ke Tidak Ada untuk menonaktifkan pilihan tanggal.

Atur SelectionMode ke Multiple untuk memungkinkan pengguna memilih beberapa tanggal. Anda dapat memilih beberapa tanggal secara terprogram dengan menambahkan objek DateTime/DateTimeOffset ke koleksi SelectedDates , seperti yang ditunjukkan di sini:

calendarView1.SelectedDates.Add(DateTimeOffset.Now);
calendarView1.SelectedDates.Add(new DateTime(1977, 1, 5));

Pengguna dapat membatalkan pilihan tanggal yang dipilih dengan mengklik atau mengetuknya di kisi kalender.

Anda dapat menangani peristiwa SelectedDatesChanged untuk diberi tahu saat koleksi SelectedDates telah berubah.

Catatan

Untuk informasi penting tentang nilai tanggal, lihat nilai DateTime dan Kalender di artikel Kontrol tanggal dan waktu.

Menyesuaikan tampilan tampilan kalender

Tampilan kalender terdiri dari kedua elemen XAML yang ditentukan dalam elemen ControlTemplate dan visual yang dirender langsung oleh kontrol.

  • Elemen XAML yang ditentukan dalam templat kontrol mencakup batas yang mencakup kontrol, header, tombol sebelumnya dan berikutnya, dan elemen DayOfWeek. Anda dapat menata dan membuat templat ulang elemen-elemen ini seperti kontrol XAML apa pun.
  • Kisi kalender terdiri dari objek CalendarViewDayItem . Anda tidak dapat menata atau membuat templat ulang elemen-elemen ini, tetapi berbagai properti disediakan untuk memungkinkan Anda menyesuaikan tampilannya.

Diagram ini memperlihatkan elemen yang membentuk tampilan bulan kalender. Untuk informasi selengkapnya, lihat Komentar di kelas CalendarViewDayItem .

Elemen tampilan bulan kalender

Tabel ini mencantumkan properti yang bisa Anda ubah untuk mengubah tampilan elemen kalender.

Elemen Properti
DayOfWeek DayOfWeekFormat
CalendarItem CalendarItemBackground, CalendarItemBorderBrush, CalendarItemBorderThickness, CalendarItemForeground
DayItem DayItemFontFamily, DayItemFontSize, DayItemFontStyle, DayItemFontWeight, HorizontalDayItemAlignment, VerticalDayItemAlignment, CalendarViewDayItemStyle
MonthYearItem (dalam tampilan tahun dan dekade, setara dengan DayItem) MonthYearItemFontFamily, MonthYearItemFontSize, MonthYearItemFontStyle, MonthYearItemFontWeight
FirstOfMonthLabel FirstOfMonthLabelFontFamily, FirstOfMonthLabelFontSize, FirstOfMonthLabelFontStyle, FirstOfMonthLabelFontWeight, HorizontalFirstOfMonthLabelAlignment, VerticalFirstOfMonthLabelAlignment, IsGroupLabelVisible
FirstofYearDecadeLabel (dalam tampilan tahun dan dekade, setara dengan FirstOfMonthLabel) FirstOfYearDecadeLabelFontFamily, FirstOfYearDecadeLabelFontSize, FirstOfYearDecadeLabelFontStyle, FirstOfYearDecadeLabelFontWeight
Batas Status Visual FocusBorderBrush, HoverBorderBrush, PressedBorderBrush, SelectedBorderBrush, SelectedForeground, SelectedHoverBorderBrush, SelectedPressedBorderBrush
OutofScope IsOutOfScopeEnabled, OutOfScopeBackground, OutOfScopeForeground
Hari Ini IsTodayHighlighted, TodayFontWeight, TodayForeground

Secara default, tampilan bulan menunjukkan 6 minggu dalam satu waktu. Anda dapat mengubah jumlah minggu yang ditampilkan dengan mengatur properti NumberOfWeeksInView . Jumlah minimum minggu untuk ditampilkan adalah 2; maksimumnya adalah 8.

Secara default, tampilan tahun dan dekade ditampilkan dalam kisi 4x4. Untuk mengubah jumlah baris atau kolom, panggil SetYearDecadeDisplayDimensions dengan jumlah baris dan kolom yang Anda inginkan. Ini akan mengubah kisi untuk tampilan tahun dan dekade.

Di sini, tampilan tahun dan dekade diatur untuk ditampilkan dalam kisi 3x4.

calendarView1.SetYearDecadeDisplayDimensions(3, 4);

Secara default, tanggal minimum yang ditampilkan dalam tampilan kalender adalah 100 tahun sebelum tanggal saat ini, dan tanggal maksimum yang ditampilkan adalah 100 tahun melewati tanggal saat ini. Anda dapat mengubah tanggal minimum dan maksimum yang diperlihatkan kalender dengan mengatur properti MinDate dan MaxDate .

calendarView1.MinDate = new DateTime(2000, 1, 1);
calendarView1.MaxDate = new DateTime(2099, 12, 31);

Memperbarui item hari kalender

Setiap hari di kalender diwakili oleh objek CalendarViewDayItem . Untuk mengakses item hari individual dan menggunakan properti dan metodenya, tangani acara CalendarViewDayItemChanging dan gunakan properti Item dari arg peristiwa untuk mengakses CalendarViewDayItem.

Anda dapat membuat hari tidak dapat dipilih dalam tampilan kalender dengan mengatur properti CalendarViewDayItem.IsBlackout ke true.

Anda dapat menampilkan informasi kontekstual tentang kepadatan peristiwa dalam sehari dengan memanggil metode CalendarViewDayItem.SetDensityColors . Anda dapat menampilkan dari 0 hingga 10 bilah kepadatan untuk setiap hari, dan mengatur warna setiap bilah.

Berikut adalah beberapa item hari dalam kalender. Hari 1 dan 2 pingsan. Hari 2, 3, dan 4 memiliki berbagai bilah kepadatan yang ditetapkan.

Hari kalender dengan bilah kepadatan

Penyajian bertahas

Tampilan kalender dapat berisi sejumlah besar objek CalendarViewDayItem. Untuk menjaga antarmuka pengguna tetap responsif dan mengaktifkan navigasi yang lancar melalui kalender, tampilan kalender mendukung penyajian bertahis. Ini memungkinkan Anda memecah pemrosesan item hari menjadi fase. Jika satu hari dipindahkan dari tampilan sebelum semua fase selesai, tidak ada lagi waktu yang digunakan untuk mencoba memproses dan merender item tersebut.

Contoh ini memperlihatkan penyajian bertahap tampilan kalender untuk menjadwalkan janji temu.

  • Pada fase 0, item hari default dirender.
  • Pada fase 1, Anda blackout tanggal yang tidak dapat dipesan. Ini termasuk tanggal, Minggu, dan tanggal yang sudah dipesan sepenuhnya.
  • Pada fase 2, Anda memeriksa setiap janji temu yang dipesan untuk hari itu. Anda menunjukkan bilah kepadatan hijau untuk setiap janji temu yang dikonfirmasi dan bilah kepadatan biru untuk setiap janji temu tentatif.

Kelas Bookings dalam contoh ini berasal dari aplikasi pemesanan janji temu fiktif, dan tidak ditampilkan.

<CalendarView CalendarViewDayItemChanging="CalendarView_CalendarViewDayItemChanging"/>
private void CalendarView_CalendarViewDayItemChanging(CalendarView sender,
                                   CalendarViewDayItemChangingEventArgs args)
{
    // Render basic day items.
    if (args.Phase == 0)
    {
        // Register callback for next phase.
        args.RegisterUpdateCallback(CalendarView_CalendarViewDayItemChanging);
    }
    // Set blackout dates.
    else if (args.Phase == 1)
    {
        // Blackout dates in the past, Sundays, and dates that are fully booked.
        if (args.Item.Date < DateTimeOffset.Now ||
            args.Item.Date.DayOfWeek == DayOfWeek.Sunday ||
            Bookings.HasOpenings(args.Item.Date) == false)
        {
            args.Item.IsBlackout = true;
        }
        // Register callback for next phase.
        args.RegisterUpdateCallback(CalendarView_CalendarViewDayItemChanging);
    }
    // Set density bars.
    else if (args.Phase == 2)
    {
        // Avoid unnecessary processing.
        // You don't need to set bars on past dates or Sundays.
        if (args.Item.Date > DateTimeOffset.Now &&
            args.Item.Date.DayOfWeek != DayOfWeek.Sunday)
        {
            // Get bookings for the date being rendered.
            var currentBookings = Bookings.GetBookings(args.Item.Date);

            List<Color> densityColors = new List<Color>();
            // Set a density bar color for each of the days bookings.
            // It's assumed that there can't be more than 10 bookings in a day. Otherwise,
            // further processing is needed to fit within the max of 10 density bars.
            foreach (booking in currentBookings)
            {
                if (booking.IsConfirmed == true)
                {
                    densityColors.Add(Colors.Green);
                }
                else
                {
                    densityColors.Add(Colors.Blue);
                }
            }
            args.Item.SetDensityColors(densityColors);
        }
    }
}

Mendapatkan kode sampel

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