共用方式為

日期選取器

  • 發行項

日期選取器提供了一種標準化方法，讓使用者可以使用觸控、滑鼠或鍵盤輸入來選擇當地語系化日期值。

日期選擇器範例

這是正確的控制項嗎？

使用日期選取器讓使用者選擇已知日期，例如出生日期，行事曆的內容並不重要。

如果行事曆的內容很重要，請考慮使用行事曆日期選取器或行事曆檢視。

如需如何選擇正確日期控制項的詳細資訊，請參閱日期和時間控制項文章。

範例

進入點會顯示所選日期，當使用者選擇進入點時，選取器介面會從中間垂直展開，供使用者進行選擇。 日期選取器會重疊在其他 UI 上; 不會推開其他 UI。

展開日期選擇器範例

UWP 和 WinUI 2

重要

本文中的資訊和範例針對使用 Windows App SDK 和 WinUI 3 的應用程式進行了最佳化，但通常適用於使用 WinUI 2 的 UWP 應用程式。 如需平台特定資訊和範例，請參閱 UWP API 參考。

本節包含您在 UWP 或 WinUI 2 應用程式中使用控制項所需的資訊。

此控制項的 API 位在 Windows.UI.Xaml.Controls 命名空間中。

建議使用最新的 WinUI 2 來取得所有控制項的最新樣式和範本。 WinUI 2.2 或更新版本包含此使用圓角之控制項的新範本。 如需詳細資訊，請參閱圓角半徑。

建立日期選取器

開啟 WinUI 3 資源庫應用程式，並查看 DatePicker 運作情形。

WinUI 3 資源庫應用程式包含大多數 WinUI 3 控制項和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub 上取得原始程式碼

此範例會示範如何建立具有標題的簡單日期選取器。

<DatePicker x:Name="exampleDatePicker" Header="Pick a date"/>

DatePicker exampleDatePicker = new DatePicker();
exampleDatePicker.Header = "Pick a date";

產生的日期選取器看起來會像這樣：

日期選擇器範例

格式化日期選取器

根據預設，日期選取器會顯示日期、月份和年份。 如果您的日期選取器不需要所有欄位，則可以隱藏不需要的欄位。 若要隱藏欄位，請將其對應的 fieldVisible 屬性設為false：DayVisible、MonthVisible 或 YearVisible。

在此案例中只需要年份，因此隱藏日期和月份欄位。

<DatePicker x:Name="yearDatePicker" Header="In what year was Microsoft founded?" 
            MonthVisible="False" DayVisible="False"/>

隱藏日期和月份欄位的日期選擇器。

DatePicker 中每個 ComboBox 的字串內容都由 DateTimeFormatter 建立。 您可以透過提供格式範本或格式模式的字串來通知 DateTimeFormatter 如何格式化日期值。 如需詳細資訊，請參閱 DayFormat、MonthFormat 和 YearFormat 屬性。

在此案例中，使用格式模式將月份顯示為整數和縮寫。 您可以將常值字串新增至格式模式中，例如月份縮寫周圍的括號：({month.abbreviated})。

<DatePicker MonthFormat="{}{month.integer(2)} ({month.abbreviated})" DayVisible="False"/>

隱藏日期欄位的日期選擇器。

日期值

日期選取器控制項具有 Date/DateChanged 和 SelectedDate/SelectedDateChanged API。 它們之間的差異在於 Date 不可為 Null，而 SelectedDate 可為 Null。

SelectedDate 的值用於填入日期選取器，預設為 null。 如果 SelectedDate是 null，則 Date 屬性設定為 12/31/1600; 否則，Date 值會與 SelectedDate 值同步。 當 SelectedDate 是 null 時，選取器處於「未設定」狀態，並顯示欄位名稱而不是日期。

未選取日期的日期選擇器。

您可以設定 MinYear 和 MaxYear 屬性來限制選取器中的日期值。 預設情況下，MinYear 設定為目前日期之前 100 年，MaxYear 設定為目前日期之後 100 年。

如果只設定 MinYear 或 MaxYear，則需要確認您設定的日期和其他日期的預設值會建立一個有效的日期範圍; 否則，選取器中將無法選擇日期。 例如，只設定 yearDatePicker.MaxYear = new DateTimeOffset(new DateTime(900, 1, 1)); 會建立一個預設值為 MinYear 的無效日期範圍。

初始化日期值

日期屬性不能設定為 XAML 屬性字串，因為 Windows 執行階段 XAML 剖析器沒有可將字串轉換為 DateTime / DateTimeOffset 物件形式之日期的轉換邏輯。 以下是一些建議的方法，可以在程式碼中定義這些物件，並將其設定為目前日期以外的日期。

另一個可能的技術是定義可做為資料物件或在資料內容中使用的日期，然後將日期屬性設定為 XAML 屬性，參考可存取日期做為資料的 {Binding} 標記擴充功能。

注意

注意如需有關日期值的重要資訊，請參閱日期和時間控制項文章中的 DateTime 與 Calendar 值。

此範例示範在不同的 DatePicker 控制項上設定 SelectedDate、MinYear 和 MaxYear 屬性。

<DatePicker x:Name="yearDatePicker" MonthVisible="False" DayVisible="False"/>
<DatePicker x:Name="arrivalDatePicker" Header="Arrival date"/>

public MainPage()
{
    this.InitializeComponent();

    // Set minimum year to 1900 and maximum year to 1999.
    yearDatePicker.SelectedDate = new DateTimeOffset(new DateTime(1950, 1, 1));
    yearDatePicker.MinYear = new DateTimeOffset(new DateTime(1900, 1, 1));
    // Using a different DateTimeOffset constructor.
    yearDatePicker.MaxYear = new DateTimeOffset(1999, 12, 31, 0, 0, 0, new TimeSpan());

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

使用日期值

若要在應用程式中使用日期值，通常會使用繫結到 SelectedDate 屬性的資料，或處理 SelectedDateChanged 事件。

有關一起使用 DatePicker 和 TimePicker 來更新單一 DateTime 值的範例，請參閱行事曆、日期和時間控制項 - 將日期選取器和時間選取器一起使用。

在這裡，您可以使用 DatePicker 來讓使用者選取其抵達日期。 您處理 SelectedDateChanged 事件以更新名為 arrivalDateTime 的 DateTime 執行個體。

<StackPanel>
    <DatePicker x:Name="arrivalDatePicker" Header="Arrival date"
                DayFormat="{}{day.integer} ({dayofweek.abbreviated})"
                SelectedDateChanged="arrivalDatePicker_SelectedDateChanged"/>
    <Button Content="Clear" Click="ClearDateButton_Click"/>
    <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 arrivalDatePicker_SelectedDateChanged(DatePicker sender, DatePickerSelectedValueChangedEventArgs args)
    {
        if (arrivalDatePicker.SelectedDate != null)
        {
            arrivalDateTime = new DateTime(args.NewDate.Value.Year, args.NewDate.Value.Month, args.NewDate.Value.Day);
        }
        arrivalText.Text = arrivalDateTime.ToString();
    }

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

取得範例程式碼