行事曆日期選擇器Calendar date picker

行事曆日期選擇器是一種下拉式控制項,最適合用來從行事曆檢視中挑選單一日期,然後取得各種重要的相關資訊,例如星期幾、行事曆行程密度。The calendar date picker is a drop down control that's optimized for picking a single date from a calendar view where contextual information like the day of the week or fullness of the calendar is important. 您可以修改行事曆來提供其他內容,或限制可用的日期。You can modify the calendar to provide additional context or to limit available dates.

取得 Windows UI 程式庫Get the Windows UI Library

WinUI 標誌

Windows UI 程式庫 2.2 或更新版本中有這個控制項使用圓角的新範本。Windows UI Library 2.2 or later includes a new template for this control that uses rounded corners. 如需詳細資訊,請參閱圓角半徑For more info, see Corner radius. WinUI 是 NuGet 套件,其中包含適用於 Windows 應用程式的新控制項和 UI 功能。WinUI is a NuGet package that contains new controls and UI features for Windows apps. 如需詳細資訊 (包括安裝指示),請參閱 Windows UI 程式庫For more info, including installation instructions, see Windows UI Library.

平台 APICalendarDatePicker 類別Date 屬性DateChanged 事件Platform APIs: CalendarDatePicker class, Date property, DateChanged event

這是正確的控制項嗎?Is this the right control?

使用者可以使用行事曆日期選擇器,從內容相關行事曆檢視中挑選單一日期。Use a calendar date picker to let a user pick a single date from a contextual calendar view. 它的用途包括選擇約會或出發日期。Use it for things like choosing an appointment or departure date.

若要讓使用者挑選已知的日期,例如出生日期 (行事曆內容不重要),請考慮使用日期選擇器To let a user pick a known date, such as a date of birth, where the context of the calendar is not important, consider using a date picker.

如需有關如何選擇正確控制項的詳細資訊,請參閱日期和時間控制項文章。For more info about choosing the right control, see the Date and time controls article.

範例Examples

XAML 控制項庫XAML Controls Gallery
XAML controls gallery

如果您已安裝 XAML 控制項庫應用程式,請按一下這裡開啟應用程式並查看 CalendarDatePicker 運作情形If you have the XAML Controls Gallery app installed, click here to open the app and see the CalendarDatePicker in action.

如果尚未設定日期,進入點會顯示預留位置文字;否則,它會顯示所選的日期。The entry point displays placeholder text if a date has not been set; otherwise, it displays the chosen date. 當使用者選取進入點時,行事曆檢視會展開,方便使用者選擇日期。When the user selects the entry point, a calendar view expands for the user to make a date selection. 行事曆檢視與其他 UI 重疊;它不會將其他 UI 移開。The calendar view overlays other UI; it doesn't push other UI out of the way.

行事曆日期選擇器的螢幕擷取畫面,其中顯示一個空白的 [選取日期] 文字方塊,然後是一個底下填入行事曆的文字方塊。

建立日期選擇器Create a date picker

<CalendarDatePicker x:Name="arrivalCalendarDatePicker" Header="Arrival date"/>
CalendarDatePicker arrivalCalendarDatePicker = new CalendarDatePicker();
arrivalCalendarDatePicker.Header = "Arrival date";

產生的行事曆日期選擇器看起來像這樣︰The resulting calendar date picker looks like this:

已填入行事曆日期選擇器的螢幕擷取畫面,其標籤顯示 [抵達日期]。

行事曆日期選擇器有一個內部 CalendarView,可用來挑選日期。The calendar date picker has an internal CalendarView for picking a date. CalendarView 屬性的子集 (例如 IsTodayHighlightedFirstDayOfWeek) 存在於 CalendarDatePicker 上面,而且會被轉送到內部 CalendarView 供您修改。A subset of CalendarView properties, like IsTodayHighlighted and FirstDayOfWeek, exist on CalendarDatePicker and are forwarded to the internal CalendarView to let you modify it.

不過,您無法變更內部 CalendarView 的 SelectionMode 以允許複選。However, you can't change the SelectionMode of the internal CalendarView to allow multiple selection. 如果您想讓使用者挑選多個日期或一律顯示行事曆,請考慮使用行事曆檢視,而不要使用行事曆日期選擇器。If you need to let a user pick multiple dates or need a calendar to be always visible, consider using a calendar view instead of a calendar date picker. 請參閱行事曆檢視文章,以取得有關如何修改行事曆顯示方式的詳細資訊。See the Calendar view article for more info on how you can modify the calendar display.

選取日期Selecting dates

使用 Date 屬性來取得日期或設定選取的日期。Use the Date property to get or set the selected date. 根據預設,Date 屬性是 nullBy default, the Date property is null. 當使用者在行事曆檢視中選取一個日期時,便會更新這個屬性。When a user selects a date in the calendar view, this property is updated. 使用者可以按一下行事曆檢視中選取的日期,以取消選取該日期。A user can clear the date by clicking the selected date in the calendar view to deselect it.

您可以在程式碼中按照以下方式設定日期。You can set the date in your code like this.

myCalendarDatePicker.Date = new DateTime(1977, 1, 5);

當您在程式碼中設定日期時,值會受到 MinDateMaxDate 屬性的約束。When you set the Date in code, the value is constrained by the MinDate and MaxDate properties.

  • 如果 Date 小於 MinDate,值會設定為 MinDateIf Date is smaller than MinDate, the value is set to MinDate.
  • 如果 Date 大於 MaxDate,值會設定為 MaxDateIf Date is greater than MaxDate, the value is set to MaxDate.

您可以處理 DateChanged 事件,以便在 Date 值變更時收到通知。You can handle the DateChanged event to be notified when the Date value has changed.

注意

如需日期值的重要資訊,請參閱<日期和時間控制項>文章中的 DateTime 和 Calendar 值For important info about date values, see DateTime and Calendar values in the Date and time controls article.

設定標頭與預留位置文字Setting a header and placeholder text

您可以新增 Header (或標籤) 與 PlaceholderText (或浮水印) 到行事曆日期選擇器,以告知使用者其用途。You can add a Header (or label) and PlaceholderText (or watermark) to the calendar date picker to give the user an indication of what it's used for. 若要自訂標頭的外觀,您可以設定 HeaderTemplate 屬性,而不是 Header。To customize the look of the header, you can set the HeaderTemplate property instead of Header.

預設預留位置文字是「選取日期」。The default placeholder text is "select a date". 您可以將 PlaceholderText 屬性設定為空字串以移除預設文字,或者您可以提供自訂文字,如下所示。You can remove this by setting the PlaceholderText property to an empty string, or you can provide custom text as shown here.

<CalendarDatePicker x:Name="arrivalCalendarDatePicker" Header="Arrival date" 
                    PlaceholderText="Choose your arrival date"/>

取得範例程式碼Get the sample code