syncfusion-maui-calendar

实现 .NET MAUI 日历（SfCalendar）

一份全面的指南，介绍如何实现和自定义 Syncfusion .NET MAUI 日历控件。SfCalendar 提供强大的日期选择功能，支持多种视图模式、丰富的自定义选项和灵活的日期限制。

何时使用此指南

在以下情况下使用此指南：

• 在 .NET MAUI 应用程序中实现日历控件
• 启用日期选择（单个日期、多个日期或日期范围）
• 显示日历视图（月、年、十年、世纪）
• 使用 MinimumDisplayMode 和 MaximumDisplayMode 限制可导航的视图范围
• 使用最小/最大日期或自定义验证限制日期选择
• 自定义日历外观（背景、文本样式）
• 处理日历事件（选择变化、视图变化、点击）
• 配置周数、每周首日或前置/后置日期
• 为日历实现本地化或 RTL 支持
• 添加特殊日期高亮或周末样式
• 以编程方式在日期或视图之间导航

组件概览

SfCalendar 是一款功能丰富的日历控件，允许用户：

• 选择单个日期、多个日期或日期范围
• 在月、年、十年和世纪视图之间导航
• 使用 MinimumDate、MaximumDate、EnablePastDates 或 SelectableDayPredicate 限制日期
• 自定义日历外观的方方面面
• 通过丰富的事件响应用户交互

主要功能：

• 提供 4 种日历视图，实现灵活导航
• 提供 3 种选择模式（单选、多选、范围选择）
• 使用 MinimumDisplayMode 和 MaximumDisplayMode 限定用户可导航的视图范围
• 提供全面的日期限制选项
• 完整的自定义功能（日期、今天、前置/后置日期）
• 丰富的用户交互事件系统
• 支持本地化和全球化
• 支持 RTL（从右向左）语言

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置（Syncfusion.Maui.Calendar）
• 在 MauiProgram.cs 中注册处理程序
• 在 XAML 和 C# 中初始化基本的 SfCalendar
• 自定义每周首日
• 配置圆角半径

日历视图

📄 阅读： references/calendar-views.md

• 月视图（默认且最常用）
• 用于选择月份的年视图
• 用于选择年份的十年视图
• 用于选择十年的世纪视图
• NumberOfVisibleWeeks 属性
• 显示周数（ShowWeekNumber）
• 使用 MinimumDisplayMode 和 MaximumDisplayMode 限定用户可导航的视图范围
• 视图导航和切换

日期选择

📄 阅读： references/date-selection.md

• 单选模式（每次选择一个日期）
• 多选模式（选择多个日期）
• 范围选择模式（选择日期范围）
• 使用 EnableSwipeSelection 进行范围选择
• RangeSelectionDirection（Forward、Backward、Both、None）
• 使用 SelectedDate/SelectedDates/SelectedRange 以编程方式选择
• 不同视图中的选择行为

日期限制

📄 阅读： references/date-restrictions.md

• MinimumDate 属性（限制向前导航）
• MaximumDate 属性（限制向后导航）
• EnablePastDates 属性（禁用今天之前的日期）
• SelectableDayPredicate（自定义日期验证逻辑）
• 禁用周末或特定日期
• 日期验证模式

日期导航

📄 阅读： references/date-navigation.md

• 使用 DisplayDate 属性以编程方式导航
• 以编程方式切换视图
• AllowViewNavigation 属性
• NavigateToAdjacentMonth（前置/后置日期导航）
• 用于按月/年导航的滑动手势
• 点击标题在视图之间导航

日历模式和显示选项

📄 阅读： references/calendar-modes.md

• 默认模式（内嵌显示）
• 对话框模式（居中弹出）
• 相对对话框模式（定位弹出）
• CalendarRelativePosition 枚举（AlignTop、AlignBottom、AlignToLeftOf、AlignToRightOf 等）
• 用于以编程方式控制的 IsOpen 属性
• 自定义 PopupWidth 和 PopupHeight
• 日期选择器模式

自定义和样式

📄 阅读： references/customizations.md

• 月份单元格自定义（日期、今天、前置／后置日期）
• 文本样式（TextStyle、TodayTextStyle、DisabledDatesTextStyle）
• 所有单元格状态的背景颜色
• 周末日期样式
• 使用图标突出显示特殊日期（Dot、Heart、Diamond、Star、Bell）
• 年、十年和世纪视图自定义
• CalendarTextStyle 属性（TextColor、FontSize、FontFamily）

事件和交互

📄 阅读： references/events.md

• ViewChanged 事件（视图／日期范围变化）
• SelectionChanged 事件（日期选择变化）
• Tapped 事件（单击日期）
• DoubleTapped 事件（双击日期）
• LongPressed 事件（长按日期）
• 事件参数和数据
• 事件处理模式

标题和页脚

📄 阅读： references/headers-footers.md

• HeaderView 自定义（高度、背景、文本样式）
• 标题文本格式自定义
• ShowNavigationArrows 属性
• 用于自定义标题 UI 的 HeaderTemplate
• FooterView 自定义
• 自定义页脚模板

本地化和高级功能

📄 阅读： references/localization-advanced.md

• 全球化和本地化设置
• CurrentUICulture 配置
• 为多种语言创建资源文件
• RTL（从右到左）支持
• CalendarIdentifier（公历、伊斯兰历等）
• 日历模式
• 液态玻璃效果
• 高级视觉自定义