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 类来源于虚构的约会预订应用，并且不会显示。
(若要查看此代码在完整的应用示例中运行，请参阅 Lunch 计划程序示例。)
<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 设置为 “多个 ”以允许用户选择多个日期。 可通过将 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 和日历值
CalendarView 中使用的日期对象具有不同的表示形式，具体取决于编程语言。 C# 和 Visual Basic 使用 System.DateTimeOffset 结构，它是 .NET 的一部分。 Visual C++ 组件扩展 (C++/CX) 使用 Windows：：Foundation：:D ateTime 结构。 一个相关的概念是 Calendar 类，它影响日期在上下文中的解释方式。 所有 Windows 运行时应用都可以使用 Windows.Globalization.Calendar 类。 C# 和 Visual Basic 应用还可以使用 System.Globalization.Calendar 类，该类具有非常类似的功能。 (Windows 运行时 应用可以使用基本 .NET Calendar 类，但不能使用特定的实现，例如 GregorianCalendar.)
.NET 还支持名为 DateTime 的类型，该类型可隐式转换为 DateTimeOffset。 因此，你可能会在 .NET 代码中看到用于设置真正 DateTimeOffset 的值的“DateTime”类型。 有关 DateTime 和DateTimeOffset 之间的差异的详细信息，请参阅 DateTimeOffset 中的备注。
注意
无法将采用日期对象的属性设置为 XAML 属性字符串，因为Windows 运行时 XAML 分析程序没有将字符串转换为 DateTime/DateTimeOffset 对象的日期的转换逻辑。 通常使用代码设置这些值。 另一个可行的方法是定义可用作数据对象或在数据上下文中可用的日期，然后将该属性设置为引用 {Binding} 标记扩展表达式的 XAML 属性，以便可以作为数据访问该日期。
自定义 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 |
在已构造 FrameworkElement 并将其添加到对象树中并准备好交互时发生。 (继承自 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 |
当指针设备在此元素中启动 “按下” 操作时发生。 (继承自 UIElement) |
| PointerReleased |
在释放之前启动 Press 操作的指针设备时发生，而此元素中。 请注意， 不保证按下 操作的结束会触发 PointerReleased 事件;其他事件可能会改为触发。 有关详细信息，请参阅备注。 (继承自 UIElement) |
| PointerWheelChanged |
当指针滚轮的增量值更改时发生。 (继承自 UIElement) |
| PreviewKeyDown |
在 UIElement 具有焦点时按下键盘键时发生。 (继承自 UIElement) |
| PreviewKeyUp |
在 UIElement 具有焦点时释放键盘键时发生。 (继承自 UIElement) |
| ProcessKeyboardAccelerators |
按下 键盘快捷方式 (或快捷键) 时发生。 (继承自 UIElement) |
| RightTapped |
当指针位于 元素上时发生右点击输入刺激时发生。 (继承自 UIElement) |
| SelectedDatesChanged |
更改所选日期的集合时发生。 |
| SizeChanged |
当 ActualHeight 或 ActualWidth 属性更改 FrameworkElement 上的值时发生。 (继承自 FrameworkElement) |
| Tapped |
在此元素的命中测试区域上发生其他未经处理的 点击 交互时发生。 (继承自 UIElement) |
| Unloaded |
当此对象不再连接到main对象树时发生。 (继承自 FrameworkElement) |