CalendarView 類別
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
代表可讓使用者使用視覺行事曆顯示選取日期的控制項。
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 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(Microsoft.UI.Xaml.WinUIContract), 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- 繼承
- 屬性
範例
提示
如需詳細資訊、設計指引和程式碼範例，請參閱 行事歷檢視。
WinUI 3 資源庫應用程式包含大部分 WinUI 3 控制件、特性和功能的互動式範例。 從 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 控件搭配最少數量的 Extensible Application Markup Language (XAML) 或其他程式代碼，或者您可以用各種方式自定義它以符合您的應用程式。
CalendarView 是由 3 個不同的檢視所組成：月份檢視、年份檢視和十年檢視。 根據預設，開啟時會顯示月份檢視。 您可以設定 DisplayMode 屬性，以指定啟動檢視。
用戶單擊月份檢視中的標頭以開啟年份檢視，然後按兩下年份檢視中的標頭以開啟十年檢視。 使用者在十年份檢視中挑選某一年，即可返回年份檢視；挑選年份檢視中的某個月份，即可返回月份檢視。 標頭兩側的箭頭可用來往前或往回瀏覽月份、年份或十年。
選取日期
根據預設，SelectionMode 屬性是設定為 Single。 這可讓使用者在行事曆中挑選單一日期。 將 SelectionMode 設定為 [無 ] 以停用日期選取。
將 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 ，讓控件具有唯一的外觀。 如需修改控件樣式和範本的相關信息，請參閱 XAML 樣式。 定義控件外觀的預設樣式、範本和資源會包含在檔案中 generic.xaml 。 為了設計目的，generic.xaml會與 Windows 應用程式 SDK NuGet 套件一起安裝。 根據預設，此位置為 \Users\<username>\.nuget\packages\microsoft.windowsappsdk\<version>\lib\uap10.0\Microsoft.UI\Themes\generic.xaml。 不同 SDK 版本的樣式和資源可能會有不同的值。
XAML 也包含可用來修改不同視覺狀態中控件色彩的資源，而不需修改控件範本。 建議您修改這些資源來設定 背景 和 前景等屬性。 如需詳細資訊，請參閱 XAML 樣式一文的輕量樣式一節。
建構函式
| 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 |
當使用者按下遊戲控制器上的 B/上一頁按鈕時，會從控件放開焦點時發生。 (繼承來源 Control) |
| FocusEngaged |
發生於使用者按下遊戲控制器上的 A/Select 按鈕時，焦點受限於控件。 (繼承來源 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 |
發生於先前起始 「按下」 動作的指標裝置釋放時，同時在此元素內。 請注意， Press 動作的結尾不保證會引發 |
| PointerWheelChanged |
發生於指標滾輪的差異值變更時。 (繼承來源 UIElement) |
| PreviewKeyDown |
發生於 UIElement 有焦點時按下鍵盤按鍵時。 (繼承來源 UIElement) |
| PreviewKeyUp |
發生於 UIElement 有焦點時放開鍵盤按鍵時。 (繼承來源 UIElement) |
| ProcessKeyboardAccelerators |
發生於按下 鍵盤快捷方式 (或快捷鍵) 時。 (繼承來源 UIElement) |
| RightTapped |
發生於指標位於元素上方時發生右點選輸入壓力時。 (繼承來源 UIElement) |
| SelectedDatesChanged |
發生於選取日期的集合變更時。 |
| SizeChanged |
發生於 ActualHeight 或 ActualWidth 屬性變更 FrameworkElement 上的值時。 (繼承來源 FrameworkElement) |
| Tapped |
發生於此元素的點擊測試區域上發生未處理的 Tap 互動時。 (繼承來源 UIElement) |
| Unloaded |
當這個物件不再連接到主物件樹狀結構時發生。 (繼承來源 FrameworkElement) |