Kontrol kalender, tanggal, dan waktu

  • Artikel

Kontrol tanggal dan waktu memberi Anda cara standar dan dilokalkan untuk memungkinkan pengguna melihat dan mengatur nilai tanggal dan waktu di aplikasi Anda. Artikel ini menyediakan panduan desain dan membantu Anda memilih kontrol yang tepat.

Buka aplikasi Galeri WinUI 3 dan lihat DateAndTime beraksi.

Aplikasi WinUI 3 Gallery mencakup contoh interaktif sebagian besar kontrol, fitur, dan fungsi WinUI 3. Dapatkan aplikasi dari Microsoft Store atau dapatkan kode sumber di GitHub

Kontrol tanggal atau waktu mana yang harus Anda gunakan?

Ada empat kontrol tanggal dan waktu untuk dipilih; kontrol yang Anda gunakan tergantung pada skenario Anda. Gunakan info ini untuk memilih kontrol yang tepat untuk digunakan di aplikasi Anda.

Kontrol Contoh Deskripsi
Tampilan kalender Contoh tampilan kalender Gunakan untuk memilih satu tanggal atau rentang tanggal dari kalender yang selalu terlihat.
Pemilih tanggal kalender Cuplikan layar pemilih tanggal kalender. Gunakan untuk memilih satu tanggal dari kalender kontekstual.
Pemilih tanggal Contoh pemilih tanggal Gunakan untuk memilih satu tanggal yang diketahui saat info kontekstual tidak penting.
Pemilih waktu Contoh pemilih waktu Gunakan untuk memilih satu nilai waktu.

Tampilan kalender

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

Tampilan kalender terdiri dari 3 tampilan terpisah: tampilan bulan, tampilan tahun, dan tampilan dekade. Secara default, dimulai dengan tampilan bulan terbuka, tetapi Anda dapat menentukan tampilan apa pun sebagai tampilan startup.

Cuplikan layar tiga Tampilan Kalender memperlihatkan Tampilan Bulan, Tampilan Tahun, dan Tampilan Dekade.

  • Jika Anda perlu mengizinkan pengguna memilih beberapa tanggal, Anda harus menggunakan CalendarView.
  • Jika Anda perlu membiarkan pengguna hanya memilih satu tanggal dan tidak memerlukan kalender untuk selalu terlihat, pertimbangkan untuk menggunakan kontrol CalendarDatePicker atau DatePicker .

Pemilih tanggal kalender

CalendarDatePicker adalah kontrol drop-down yang dioptimalkan untuk memilih satu tanggal dari tampilan kalender di mana informasi kontekstual seperti hari dalam seminggu atau kepenuhan kalender penting. Anda dapat mengubah kalender untuk memberikan konteks tambahan atau membatasi tanggal yang tersedia.

Titik entri menampilkan teks tempat penampung jika tanggal belum ditetapkan; jika tidak, ia menampilkan tanggal yang dipilih. Saat pengguna memilih titik entri, tampilan kalender diperluas bagi pengguna untuk membuat pilihan tanggal. Tampilan kalender melapisi UI lainnya; itu tidak mendorong UI lain keluar dari jalan.

Cuplikan layar Pemilih Tanggal Kalender memperlihatkan kotak teks pilih tanggal kosong lalu diisi dengan kalender di bawahnya.

  • Gunakan pemilih tanggal kalender untuk hal-hal seperti memilih janji temu atau tanggal keberangkatan.

Pemilih tanggal

Kontrol DatePicker menyediakan cara standar untuk memilih tanggal tertentu.

Titik entri menampilkan tanggal yang dipilih, dan ketika pengguna memilih titik masuk, permukaan pemilih diperluas secara vertikal dari tengah agar pengguna membuat pilihan. Pemilih tanggal melapisi UI lainnya; itu tidak mendorong UI lain keluar dari jalan.

Contoh perluasan pemilih tanggal

  • Gunakan pemilih tanggal untuk mengizinkan pengguna memilih tanggal yang diketahui, seperti tanggal lahir, di mana konteks kalender tidak penting.

Pemilih waktu

TimePicker digunakan untuk memilih nilai waktu tunggal untuk hal-hal seperti janji temu atau waktu keberangkatan. Ini adalah tampilan statis yang diatur oleh pengguna atau dalam kode, tetapi tidak diperbarui untuk menampilkan waktu saat ini.

Titik entri menampilkan waktu yang dipilih, dan ketika pengguna memilih titik masuk, permukaan pemilih diperluas secara vertikal dari tengah bagi pengguna untuk membuat pilihan. Pemilih waktu melapisi UI lainnya; itu tidak mendorong UI lain keluar dari jalan.

Contoh perluasan pemilih waktu

  • Gunakan pemilih waktu untuk memungkinkan pengguna memilih satu nilai waktu.

Membuat kontrol tanggal atau waktu

Lihat artikel ini untuk info dan contoh khusus untuk setiap kontrol tanggal dan waktu.

Menggunakan pemilih tanggal dan pemilih waktu bersama-sama

Contoh ini menunjukkan cara menggunakan DatePicker dan TimePicker bersama-sama untuk memungkinkan pengguna memilih tanggal dan waktu kedatangan mereka. Anda menangani SelectedDateChanged peristiwa dan SelectedTimeChanged untuk memperbarui satu instans DateTime bernama arrivalDateTime. Pengguna juga dapat menghapus pemilih tanggal dan waktu setelah ditetapkan.

Pemilih tanggal, pemilih waktu, tombol, dan label teks. 

<StackPanel>
    <DatePicker x:Name="arrivalDatePicker" Header="Arrival date"
                DayFormat="{}{day.integer} ({dayofweek.abbreviated})"
                SelectedDateChanged="ArrivalDatePicker_SelectedDateChanged"/>
    <StackPanel Orientation="Horizontal">
        <TimePicker x:Name="arrivalTimePicker" Header="Arrival time"
                MinuteIncrement="15"
                SelectedTimeChanged="ArrivalTimePicker_SelectedTimeChanged"/>
        <Button Content="Clear" Click="ClearDateButton_Click"
                VerticalAlignment="Bottom" Height="30" Width="54"/>
    </StackPanel>
    <TextBlock x:Name="arrivalText" Margin="0,12"/>
</StackPanel>

public sealed partial class MainPage : Page
{
    DateTime arrivalDateTime;

    public MainPage()
    {
        this.InitializeComponent();

        // Set minimum to the current year and maximum to five years from now.
        arrivalDatePicker.MinYear = DateTimeOffset.Now;
        arrivalDatePicker.MaxYear = DateTimeOffset.Now.AddYears(5);
    }

    private void ArrivalTimePicker_SelectedTimeChanged(TimePicker sender, TimePickerSelectedValueChangedEventArgs args)
    {
        if (arrivalTimePicker.SelectedTime != null)
        {
            arrivalDateTime = new DateTime(arrivalDateTime.Year, arrivalDateTime.Month, arrivalDateTime.Day,
                                           args.NewTime.Value.Hours, args.NewTime.Value.Minutes, args.NewTime.Value.Seconds);
        }
        arrivalText.Text = arrivalDateTime.ToString();
    }

    private void ArrivalDatePicker_SelectedDateChanged(DatePicker sender, DatePickerSelectedValueChangedEventArgs args)
    {
        if (arrivalDatePicker.SelectedDate != null)
        {
            if (VerifyDateIsFuture((DateTimeOffset)arrivalDatePicker.SelectedDate) == true)
            {
                arrivalDateTime = new DateTime(args.NewDate.Value.Year, args.NewDate.Value.Month, args.NewDate.Value.Day,
                                               arrivalDateTime.Hour, arrivalDateTime.Minute, arrivalDateTime.Second);
                arrivalText.Text = arrivalDateTime.ToString();
            }
            else
            {
                arrivalDatePicker.SelectedDate = null;
                arrivalText.Text = "Arrival date must be later than today.";
            }
        }
    }

    private bool VerifyDateIsFuture(DateTimeOffset date)
    {
        if (date > DateTimeOffset.Now)
        {
            return true;
        }
        return false;
    }

    private void ClearDateButton_Click(object sender, RoutedEventArgs e)
    {
        arrivalDateTime = new DateTime();
        arrivalDatePicker.SelectedDate = null;
        arrivalTimePicker.SelectedTime = null;
        arrivalText.Text = string.Empty;
    }
}

Globalisasi

Kontrol tanggal XAML mendukung setiap sistem kalender yang didukung oleh Windows. Kalender ini ditentukan di kelas Windows.Globalization.CalendarIdentifiers . Setiap kontrol menggunakan kalender yang benar untuk bahasa default aplikasi Anda, atau Anda dapat mengatur properti CalendarIdentifier untuk menggunakan sistem kalender tertentu.

Kontrol pemilih waktu mendukung setiap sistem jam yang ditentukan di kelas Windows.Globalization.ClockIdentifiers . Anda dapat mengatur properti ClockIdentifier untuk menggunakan jam 12 jam atau jam 24 jam. Jenis properti adalah String, tetapi Anda harus menggunakan nilai yang sesuai dengan properti string statis kelas ClockIdentifiers. Ini adalah: TwelveHour (string "12HourClock")dan TwentyFourHour (string "24HourClock"). "12HourClock" adalah nilai default.

Nilai DateTime dan Kalender

Objek tanggal yang digunakan dalam kontrol tanggal dan waktu XAML memiliki representasi yang berbeda tergantung pada bahasa pemrograman Anda.

Konsep terkait adalah kelas Kalender, yang memengaruhi bagaimana tanggal ditafsirkan dalam konteks. Semua aplikasi Windows Runtime dapat menggunakan kelas Windows.Globalization.Calendar . Aplikasi C# dan Visual Basic dapat menggunakan kelas System.Globalization.Calendar , yang memiliki fungsionalitas yang sangat mirip. (Aplikasi Windows Runtime dapat menggunakan kelas .NET Calendar dasar tetapi bukan implementasi tertentu; misalnya, GregorianCalendar.)

.NET juga mendukung jenis bernama DateTime, yang secara implisit dapat dikonversi ke DateTimeOffset. Jadi Anda mungkin melihat jenis "DateTime" yang digunakan dalam kode .NET yang digunakan untuk mengatur nilai yang benar-benar DateTimeOffset. Untuk informasi selengkapnya tentang perbedaan antara DateTime dan DateTimeOffset, lihat Komentar di kelas DateTimeOffset .

Catatan

Properti yang mengambil objek tanggal tidak dapat ditetapkan sebagai string atribut XAML, karena pengurai XAML Windows Runtime tidak memiliki logika konversi untuk mengonversi string ke tanggal sebagai objek DateTime/DateTimeOffset. Anda biasanya mengatur nilai-nilai ini dalam kode. Teknik lain yang mungkin adalah menentukan tanggal yang tersedia sebagai objek data atau dalam konteks data, lalu mengatur properti sebagai atribut XAML yang mereferensikan ekspresi ekstensi markup {Binding} yang dapat mengakses tanggal sebagai data.

Dapatkan kode sampel

Untuk pengembang (XAML)