CalendarView 類別
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
代表可讓使用者使用視覺行事曆顯示選取日期的控制項。
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class CalendarView : Control[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class CalendarView : ControlPublic Class CalendarView
Inherits Control- 繼承
- 屬性
Windows 需求
| 裝置系列 |
Windows 10 (已於 10.0.10240.0 引進)
|
| API contract |
Windows.Foundation.UniversalApiContract (已於 v1.0 引進)
|
範例
提示
如需詳細資訊、設計指引和程式碼範例，請參閱 行事曆檢視。
WinUI 2 資源庫應用程式包含大部分 WinUI 2 控制項、特性和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub上取得原始程式碼。
此範例顯示排程約會的 CalendarView 階段轉譯。 在階段 0 中，會轉譯預設日期項目。 在階段 1，您封鎖不能預約的日期。 這包含過去的日期、週日以及已完全預訂的日期。 在階段 2 中，您勾選針對該日期預訂的每個約會。 您為每個已確認的約會顯示綠色密度列，並為每個暫定的約會顯示藍色密度列。 此範例中的 Bookings 類別是來自虛構約會預約 App，而且不會顯示。
(若要查看此程式碼在完整的應用程式範例中執行，請參閱 午餐排程器範例。)
<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);
}
}
}
備註
提示
如需詳細資訊、設計指引和程式碼範例，請參閱 行事曆檢視。
CalendarView 提供標準化的方式，讓使用者檢視和與行事曆互動。 若您需要讓使用者選取多個日期，則必須使用 CalendarView。 若您需要讓使用者只挑選單一日期，而且不需要一律顯示行事曆，請考慮使用 CalendarDatePicker 或 DatePicker 控制項。 您可以使用預設表單中的 CalendarView 控制項，搭配最少量的可延伸應用程式標記語言 (XAML) 或其他程式碼，或者您可以透過各種方式自訂它以符合您的應用程式。
CalendarView 是由 3 個不同的檢視所組成：月份檢視、年份檢視和十年檢視。 根據預設，開啟時會顯示月份檢視。 您可以設定 DisplayMode 屬性，以指定啟動檢視。
使用者按一下月份檢視中的標頭以開啟年份檢視，然後按一下年份檢視中的標頭，以開啟十年檢視。 使用者在十年份檢視中挑選某一年，即可返回年份檢視；挑選年份檢視中的某個月份，即可返回月份檢視。 標頭兩側的箭頭可用來往前或往回瀏覽月份、年份或十年。
選取日期
根據預設，SelectionMode 屬性是設定為 Single。 這可讓使用者在行事曆中挑選單一日期。 將 SelectionMode 設定為 None 以停用日期選取範圍。
將 SelectionMode 設定為 Multiple ，讓使用者選取多個日期。 您可以將 DateTime/DateTimeOffset 物件新增至 SelectedDates集合，以選取多個日期，如下所示︰
calendarView1.SelectedDates.Add(DateTimeOffset.Now);
calendarView1.SelectedDates.Add(new DateTime(1977, 1, 5));
使用者可以按一下或點選行事曆格線，以取消選取已選取的日期。
您可以處理 SelectedDatesChanged 事件，以在 SelectedDates 集合變更時接收通知。
全球化
CalendarView 支援 Windows 支援的每個行事曆系統。 這些行事曆是在 Windows.Globalization.CalendarIdentifiers 類別中指定。 CalendarView 會針對您應用程式的預設語言使用正確的行事曆，或者您可以將 CalendarIdentifier 屬性設定為使用特定的行事曆系統。
DateTime 與 Calendar 值
CalendarView 中使用的日期物件會根據您的程式設計語言而有不同的標記法。 C# 和 Visual Basic 使用屬於 .NET 一部分的 System.DateTimeOffset 結構。 Visual C++ 元件延伸模組 (C++/CX) 會使用 Windows：：Foundation：:D ateTime 結構。 相關的概念是 Calendar 類別，會影響在內容中解譯日期的方式。 所有 Windows 執行階段應用程式都可以使用 Windows.Globalization.Calendar 類別。 C# 和 Visual Basic 應用程式也可以使用 System.Globalization.Calendar 類別，它包含非常類似的功能。 (Windows 執行階段 應用程式可以使用基底 .NET行事曆類別，但不能使用特定的實作，例如GregorianCalendar.)
.NET 亦支援名為 DateTime 的類型，隱含可轉換為 DateTimeOffset。 因此，您可能會在 .NET 程式碼中看到用來設定真正 DateTimeOffset 值的 「DateTime」 類型。 如需 DateTime 與 DateTimeOffset之間差異的詳細資訊，請參閱 DateTimeOffset中的。
注意
採用日期物件的屬性無法設定為 XAML 屬性字串，因為Windows 執行階段 XAML 剖析器沒有將字串轉換成日期做為DateTime/DateTimeOffset物件的轉換邏輯。 您通常會在程式碼中設定這些值。 另一個可能的技巧是定義可用為數據物件或資料內容中的日期，然後將 屬性設定為 XAML 屬性，以參考 {Binding} 標記延伸 運算式來存取日期做為資料。
自訂 CalendarView 的外觀
CalendarView 是由 Extensible Application Markup Language (XAML 所組成，) 由控制項直接轉譯的 ControlTemplate 和視覺化元素中所定義的元素。 在控制項範本中定義的可延伸應用程式標記語言 (XAML) 元素包含括住控制項的框線、標頭、上一個和下一個按鈕，以及 DayOfWeek 元素。 您可以設定這些元素的樣式並重新範本，例如任何可延伸的應用程式標記語言 (XAML) 控制項。 行事曆格線是由 CalendarViewDayItem 物件所組成。 您無法設定這些元素的樣式或重新套用範本，但我們提供不同的屬性，讓您可以自訂它們的外觀。
下圖顯示行事曆月份檢視的組成元素。 如需詳細資訊，請參閱 CalendarViewDayItem 類別的「備註」。
您可以變更這個表格列出的屬性，以修改行事曆元素的外觀。
根據預設，月份檢視一次會顯示 6 週。 您可以設定 NumberOfWeeksInView 屬性，以變更顯示的週數。 顯示的週數最小值是 2；最大值是 8。
根據預設，年份和十年份檢視會顯示在 4x4 方格中。 若要變更列數或欄數，請呼叫 SetYearDecadeDisplayDimensions 並指定您需要的列數與欄數。 這樣會變更年份和十年份檢視的方格。
在這裡，年份和十年份檢視會設定成顯示在 3x4 方格中。
calendarView1.SetYearDecadeDisplayDimensions(3, 4);
根據預設，CalendarView 中顯示的最小日期是目前日期之前的 100 年，而顯示的最大日期是目前日期的 100 年。 您可以設定 MinDate 和 MaxDate 屬性，以變更行事曆的最小和最大顯示日期。
calendarView1.MinDate = new DateTime(2000, 1, 1);
calendarView1.MaxDate = new DateTime(2099, 12, 31);
更新行事曆日期項目
行事曆中的每一天都是由 CalendarViewDayItem 物件來表示。 若要存取個別日期專案並使用其屬性和方法，請處理 CalendarViewDayItemChanging 事件，並使用事件引數的 Item 屬性來存取 CalendarViewDayItem。
您可以將 CalendarViewDayItem.IsBlackout 屬性設定為 true，讓 CalendarView 中無法選取一天。
您可以呼叫 CalendarViewDayItem.SetDensityColors 方法，以顯示一天中活動密度的內容相關資訊。 您可以為每一天顯示 0 到 10 個密度列，並設定每一列的色彩。
以下是行事曆中的某些日期項目。 第 1 天和第 2 天被封鎖。第 2 天、第 3 天和第 4 天設定了不同的密度列。
CalendarView 可以包含大量的 CalendarViewDayItem 物件。 若要讓 UI 保持回應，並透過行事曆啟用順暢導覽，CalendarView 支援階段式轉譯。 這樣可以讓您將日期項目分成數個階段來處理。 如果在所有階段都已完成之前，某一個日期移出檢視，則不會再花任何時間來處理及轉譯該項目。
控制項樣式和範本
您可以修改預設 的 Style 和 ControlTemplate ，讓控制項具有唯一的外觀。 如需修改控制項樣式和範本的相關資訊，請參閱 設定控制項的樣式。 定義控制面板的預設樣式、範本和資源會包含在 檔案中 generic.xaml 。 為了設計目的， generic.xaml 可在本機使用 SDK 或 NuGet 套件安裝。
-
WinUI 樣式 (建議) ：如需來自 WinUI 的更新樣式，請參閱
\Users\<username>\.nuget\packages\microsoft.ui.xaml\<version>\lib\uap10.0\Microsoft.UI.Xaml\Themes\generic.xaml。 -
非 WinUI 樣式： 如需內建樣式，請參閱
%ProgramFiles(x86)%\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic\generic.xaml。
如果您自訂安裝，位置可能會不同。 不同 SDK 版本的樣式和資源可能會有不同的值。
XAML 也包含可用來修改不同視覺狀態中控制項色彩的資源，而不需修改控制項範本。 建議您修改這些資源來設定 背景 和 前景等屬性。 如需詳細資訊，請參閱XAML 樣式一文的輕量樣式一節。 從 Windows 10 1607 版 (SDK 14393) 開始，即可使用輕量型樣式資源。
建構函式
| CalendarView() |
初始化 CalendarView 類別的新實例。 |
屬性
方法
事件
| AccessKeyDisplayDismissed |
發生于不應再顯示存取金鑰時。 (繼承來源 UIElement) |
| AccessKeyDisplayRequested |
發生于使用者要求顯示存取金鑰時。 (繼承來源 UIElement) |
| AccessKeyInvoked |
發生于使用者完成存取金鑰序列時。 (繼承來源 UIElement) |
| ActualThemeChanged |
發生于 ActualTheme 屬性值已變更時。 (繼承來源 FrameworkElement) |
| BringIntoViewRequested |
在這個專案或其中一個子代上呼叫 StartBringIntoView 時發生。 (繼承來源 UIElement) |
| CalendarViewDayItemChanging |
當 CalendarViewDayItem 正在載入時發生。 |
| CharacterReceived |
發生于輸入佇列收到單一、撰寫的字元時。 (繼承來源 UIElement) |
| ContextCanceled |
發生于內容輸入手勢繼續進入操作手勢時，通知專案不應開啟內容飛出視窗。 (繼承來源 UIElement) |
| ContextRequested |
發生于使用者已完成內容輸入手勢時，例如按一下滑鼠右鍵。 (繼承來源 UIElement) |
| DataContextChanged |
發生于 FrameworkElement.DataCoNtext 屬性的值變更時。 (繼承來源 FrameworkElement) |
| DoubleTapped |
發生于在此元素的點擊測試區域上發生未處理的 DoubleTap 互動時。 (繼承來源 UIElement) |
| DragEnter |
當輸入系統報告基礎拖曳事件，並將這個專案當做目標時發生。 (繼承來源 UIElement) |
| DragLeave |
當輸入系統報告基礎拖曳事件，並將這個專案當做原點時發生。 (繼承來源 UIElement) |
| DragOver |
在輸入系統回報以此項目作為可能置放目標的基礎拖曳事件時發生。 (繼承來源 UIElement) |
| DragStarting |
發生于起始拖曳作業時。 (繼承來源 UIElement) |
| Drop |
輸入系統報告其下以這個項目作為置放目標的置放事件時發生。 (繼承來源 UIElement) |
| DropCompleted |
發生于以這個專案做為結束來源的拖放作業時。 (繼承來源 UIElement) |
| EffectiveViewportChanged |
發生于 FrameworkElement的有效檢視區 變更時。 (繼承來源 FrameworkElement) |
| FocusDisengaged |
當焦點從遊戲台/遠端互動 (的控制項界限釋出時發生) 。 (繼承來源 Control) |
| FocusEngaged |
當遊戲台/遠端互動 (控制項界限內限制焦點時發生) 。 (繼承來源 Control) |
| GettingFocus |
發生于 UIElement 收到焦點之前。 此事件會同步引發，以確保事件反升時不會移動焦點。 (繼承來源 UIElement) |
| GotFocus |
發生于 UIElement 收到焦點時。 此事件會以非同步方式引發，因此焦點可以在反升完成之前再次移動。 (繼承來源 UIElement) |
| Holding |
發生于在此元素的點擊測試區域上發生未處理的 保留 互動時。 (繼承來源 UIElement) |
| IsEnabledChanged |
發生于 IsEnabled 屬性變更時。 (繼承來源 Control) |
| KeyDown |
在 UIElement 有焦點時按下鍵盤按鍵時發生。 (繼承來源 UIElement) |
| KeyUp |
發生于 UIElement 有焦點時放開鍵盤按鍵時。 (繼承來源 UIElement) |
| LayoutUpdated |
發生于視覺化樹狀結構的版面配置變更時，因為配置相關屬性變更值或重新整理版面配置的其他動作。 (繼承來源 FrameworkElement) |
| Loaded |
發生于 架構Element 已建構並新增至物件樹狀結構，並準備好進行互動時。 (繼承來源 FrameworkElement) |
| Loading |
當 FrameworkElement 開始載入時發生。 (繼承來源 FrameworkElement) |
| LosingFocus |
發生于 UIElement 失去焦點之前。 此事件會同步引發，以確保事件反升時不會移動焦點。 (繼承來源 UIElement) |
| LostFocus |
發生于 UIElement 失去焦點時。 此事件會以非同步方式引發，因此焦點可以在反升完成之前再次移動。 (繼承來源 UIElement) |
| ManipulationCompleted |
發生于 UIElement 上的操作完成時。 (繼承來源 UIElement) |
| ManipulationDelta |
輸入裝置在操作期間變更位置時發生。 (繼承來源 UIElement) |
| ManipulationInertiaStarting |
在操作和慣性開始的時候，只要輸入裝置不與 UIElement 物件接觸便發生。 (繼承來源 UIElement) |
| ManipulationStarted |
當輸入裝置開始在 UIElement 進行操作時發生。 (繼承來源 UIElement) |
| ManipulationStarting |
發生於第一次建立操作處理器時。 (繼承來源 UIElement) |
| NoFocusCandidateFound |
發生于使用者嘗試透過索引標籤或方向箭號移動焦點 () ，但焦點不會移動，因為不會在移動方向找到任何焦點候選項目。 (繼承來源 UIElement) |
| PointerCanceled |
發生于讓連絡人異常失去連絡人的指標時。 (繼承來源 UIElement) |
| PointerCaptureLost |
發生于這個專案先前保留的指標擷取移至另一個專案或其他地方時。 (繼承來源 UIElement) |
| PointerEntered |
發生于指標進入這個專案的點擊測試區域時。 (繼承來源 UIElement) |
| PointerExited |
發生于指標離開這個專案的點擊測試區域時。 (繼承來源 UIElement) |
| PointerMoved |
當指標在指標保留在這個專案的點擊測試區域中時移動時發生。 (繼承來源 UIElement) |
| PointerPressed |
發生于指標裝置在這個專案內起始 Press 動作時。 (繼承來源 UIElement) |
| PointerReleased |
發生于先前起始 按下 動作的指標裝置放開時，同時在此元素內。 請注意， 按下動作的 結尾不保證會引發 PointerReleased 事件;其他事件可能會改為引發。 如需詳細資訊，請參閱。 (繼承來源 UIElement) |
| PointerWheelChanged |
發生于指標滾輪的差異值變更時。 (繼承來源 UIElement) |
| PreviewKeyDown |
在 UIElement 有焦點時按下鍵盤按鍵時發生。 (繼承來源 UIElement) |
| PreviewKeyUp |
發生于 UIElement 有焦點時放開鍵盤按鍵時。 (繼承來源 UIElement) |
| ProcessKeyboardAccelerators |
發生于按下 鍵盤快速鍵 (或快速鍵) 時。 (繼承來源 UIElement) |
| RightTapped |
發生于在指標位於 元素上方時發生右鍵輸入回應時。 (繼承來源 UIElement) |
| SelectedDatesChanged |
發生于選取日期的集合變更時。 |
| SizeChanged |
發生于 ActualHeight 或 ActualWidth 屬性變更 FrameworkElement上的值時。 (繼承來源 FrameworkElement) |
| Tapped |
發生于未處理的 點 選互動發生于這個專案的點擊測試區域。 (繼承來源 UIElement) |
| Unloaded |
當這個物件不再連接到主物件樹狀結構時發生。 (繼承來源 FrameworkElement) |