syncfusion-winui-calendar-date-range-picker

实现日历日期范围选择器

WinUI CalendarDateRangePicker（SfCalendarDateRangePicker）控件提供直观、适合触控的界面，让用户能够通过下拉日历快速选择日期范围。它支持不同的日期格式、日期范围限制、预设项、周数、本地化以及丰富的 UI 自定义选项。

何时使用此技能

在以下情况下使用此技能：

• 实现日期范围选择 - 允许用户从日历中选择连续的日期范围（开始日期和结束日期）
• 将 CalendarDateRangePicker 添加到 WinUI 应用 - 安装、配置并使用 SfCalendarDateRangePicker 控件
• 配置范围选择 - 以编程方式设置所选范围、处理范围变更事件、验证范围选择
• 限制日期选择 - 设置最小/最大日期、将特定日期设为不可选、限制范围时长、禁用周末日期
• 自定义日历 UI - 更改下拉对齐方式、自定义项模板、应用主题、修改外观
• 支持本地化 - 使用不同的日历类型（Gregorian、Hebrew、Hijri 等）、更改语言、应用 RTL
• 设置日期显示格式 - 自定义日期和范围在编辑器及日历中的显示方式
• 显示预设范围 - 显示预定义的日期范围（本周、本月、上月、今年、自定义范围）
• 启用周数 - 在日历中显示周数，并自定义规则和格式
• 处理导航 - 控制视图导航（月、年、十年、世纪）、键盘快捷键
• 验证日期范围 - 确保所选范围符合最短/最长时长要求

组件概述

CalendarDateRangePicker 控件包括：

• 编辑器 - 显示所选日期范围的文本输入框
• 下拉按钮 - 打开下拉日历
• 下拉日历 - 用于选择日期范围的交互式日历，支持月/年/十年/世纪视图
• 预设项面板 - 可选的预定义日期范围列表
• 提交按钮 - 可选的“确定”/“取消”按钮，用于确认范围
• 周数列 - 可选的周数显示
• 标题和说明 - 可选的标题和辅助文本

主要功能：

• 适合触控的范围选择
• 多种日历系统（Gregorian、Hebrew、Hijri、Korean 等）
• 可自定义日期格式
• 日期范围限制与验证
• 支持不可选日期
• 预设日期范围
• 周数显示
• 键盘导航
• 主题自定义

文档与导航指南

入门

📄 阅读： references/getting-started.md

适用于：

• 首次安装 CalendarDateRangePicker 控件
• 将控件添加到 XAML 或 C# 代码中
• 以编程方式或交互方式设置所选范围
• 配置标题、说明和占位文本
• 处理选择变更事件（SelectedDateRangeChanged）
• 显示或隐藏下拉按钮
• 配置提交按钮（“确定”/“取消”）
• 了解基本的控件结构和设置

UI 自定义

📄 阅读： references/ui-customization.md

适用于：

• 更改下拉对齐方式（顶部、底部、左侧、右侧、居中）
• 自定义下拉日历尺寸
• 创建自定义日历项模板
• 使用自定义样式突出显示特殊日期
• 应用用于设置颜色和字体的主题键
• 自定义日期、周和标题的外观
• 使用 AttachedFlyout 和 DropDownFlyout 进行高级自定义
• 设置 CalendarItem 控件的样式
• 创建基于事件的日期装饰

本地化与格式设置

📄 阅读： references/localization-formatting.md

适用场景：

• 使用不同的历法（希伯来历、伊斯兰历、韩国历、泰国历、波斯历等）
• 更改显示语言（阿拉伯语、法语、日语等）
• 自定义编辑器显示格式（DisplayDateFormat）
• 设置日历日期、月份和标题的格式
• 更改一周的第一天
• 实现从右到左（RTL）的流向
• 应用特定区域设置的日期格式
• 支持国际日期惯例

在视图之间导航

📄 阅读： references/navigation.md

适用场景：

• 启用月、年、十年和世纪视图之间的导航
• 使用 MinDisplayMode 和 MaxDisplayMode 限制导航
• 实现基于视图的选择（例如，信用卡的月份/年份）
• 了解键盘导航快捷键
• 控制用户可访问的视图
• 导航到特定日期或视图级别
• 在代码中处理视图切换

限制日期范围选择

📄 阅读： references/date-restrictions.md

适用场景：

• 设置可选日期的最小值和最大值（MinDate、MaxDate）
• 使用 BlackoutDates 集合屏蔽特定日期
• 动态禁用周末日期或节假日
• 使用 ItemPrepared 事件自定义日期限制
• 限制范围时长（MinDatesCountInRange、MaxDatesCountInRange）
• 验证所选日期范围
• 防止选择无效日期范围
• 自定义被屏蔽日期的显示文本

预设项

📄 阅读： references/preset-items.md

适用场景：

• 显示预定义日期范围（本周、本月、上月、今年）
• 创建自定义预设项集合
• 使用 PresetTemplate 实现自定义预设项 UI
• 处理预设项选择事件
• 选择预设项后隐藏日历（ShowCalendar）
• 计算预设项的日期范围
• 允许与预设项同时选择自定义范围

周数

📄 阅读： references/week-numbers.md

适用场景：

• 启用周数显示（ShowWeekNumbers）
• 配置周数规则（FirstDay、FirstFourDayWeek、FirstFullWeek）
• 使用前缀/后缀自定义周数格式
• 使用 WeekNumberTemplate 自定义周数外观
• 使用 WeekNameTemplate 自定义星期标题
• 了解 CalendarWeekRule 选项
• 应用基于周的业务逻辑

快速入门

基本实现

XAML：

<Window xmlns:calendar="using:Syncfusion.UI.Xaml.Calendar">
    <Grid>
        <calendar:SfCalendarDateRangePicker 
            x:Name="sfCalendarDateRangePicker"
            HorizontalAlignment="Center"
            VerticalAlignment="Center"
            PlaceholderText="Select a date range" />
    </Grid>
</Window>

C#：

using Syncfusion.UI.Xaml.Calendar;

SfCalendarDateRangePicker sfCalendarDateRangePicker = new SfCalendarDateRangePicker();
sfCalendarDateRangePicker.PlaceholderText = "Select a date range";
this.Content = sfCalendarDateRangePicker;

通过编程方式设置所选范围

// Set a date range
sfCalendarDateRangePicker.SelectedRange = new DateTimeOffsetRange(
    new DateTimeOffset(new DateTime(2026, 3, 1)), 
    new DateTimeOffset(new DateTime(2026, 3, 15))
);

// Clear selection
sfCalendarDateRangePicker.SelectedRange = null;

处理选择更改

sfCalendarDateRangePicker.SelectedDateRangeChanged += (sender, e) =>
{
    var startOld = e.RangeStartOldValue;
    var startNew = e.RangeStartNewValue;
    var endOld = e.RangeEndOldValue;
    var endNew = e.RangeEndNewValue;
    
    // Process the new range
    if (startNew.HasValue && endNew.HasValue)
    {
        TimeSpan duration = endNew.Value - startNew.Value;
        Debug.WriteLine($"Selected range: {duration.Days} days");
    }
};

常见模式

模式 1：带限制的日期范围

// Restrict to future dates within 90 days
sfCalendarDateRangePicker.MinDate = DateTimeOffset.Now;
sfCalendarDateRangePicker.MaxDate = DateTimeOffset.Now.AddDays(90);
sfCalendarDateRangePicker.MinDatesCountInRange = 3;  // Minimum 3 days
sfCalendarDateRangePicker.MaxDatesCountInRange = 14; // Maximum 14 days

模式 2：屏蔽周末日期

sfCalendarDateRangePicker.ItemPrepared += (sender, e) =>
{
    if (e.ItemInfo.ItemType == CalendarItemType.Day &&
        (e.ItemInfo.Date.DayOfWeek == DayOfWeek.Saturday ||
         e.ItemInfo.Date.DayOfWeek == DayOfWeek.Sunday))
    {
        e.ItemInfo.IsBlackout = true;
    }
};

模式 3：包含标题和说明

<calendar:SfCalendarDateRangePicker 
    Header="Travel Dates"
    Description="Select your departure and return dates"
    PlaceholderText="Choose dates"
    Width="300" />

模式 4：自定义显示格式

// Display as full date names
sfCalendarDateRangePicker.DisplayDateFormat = "{0:D} - {1:D}";
// Example: "Saturday, March 1, 2026 - Sunday, March 15, 2026"

模式 5：本地化日历

// Hebrew calendar with RTL support
sfCalendarDateRangePicker.CalendarIdentifier = "HebrewCalendar";
sfCalendarDateRangePicker.Language = "he-IL";
sfCalendarDateRangePicker.FlowDirection = FlowDirection.RightToLeft;

关键属性

选择属性

• SelectedRange - 获取或设置所选日期范围（DateTimeOffsetRange）
• MinDatesCountInRange - 所选范围内日期数量的最小值
• MaxDatesCountInRange - 所选范围内日期数量的最大值

限制属性

• MinDate - 可选日期的最小值（默认值：1/1/1920）
• MaxDate - 可选日期的最大值（默认值：12/31/2120）
• BlackoutDates - 要禁用的日期集合

显示属性

• DisplayDateFormat - 在编辑器中显示所选范围的格式（默认值："{0:d}-{1:d}"）
• PlaceholderText - 未选择范围时显示的水印文本
• Header - 控件上方的标题
• HeaderTemplate - 标题的自定义模板
• Description - 控件下方的辅助文本

日历属性

• CalendarIdentifier - 日历系统（Gregorian、Hebrew、Hijri 等）
• FirstDayOfWeek - 每周的起始日
• ShowWeekNumbers - 显示周数
• WeekNumberRule - 确定第一周的规则（FirstDay、FirstFourDayWeek、FirstFullWeek）
• WeekNumberFormat - 周数格式（默认值："#"）

格式属性

• DayFormat - 日历中日期数字的格式
• MonthFormat - 年视图中月份名称的格式
• MonthHeaderFormat - 月份/年份标题的格式
• DayOfWeekFormat - 星期名称的格式

导航属性

• MinDisplayMode - 最低视图级别（Month、Year、Decade、Century）
• MaxDisplayMode - 最高视图级别（Month、Year、Decade、Century）

下拉框属性

• ShowDropDownButton - 显示或隐藏下拉按钮
• ShowSubmitButtons - 显示或隐藏“确定/取消”按钮
• ShowCalendar - 显示或隐藏下拉框中的日历
• DropDownPlacement - 下拉框对齐方式（Bottom、Top、Left、Right、Center）
• DropDownHeight - 下拉日历的高度

预设属性

• Preset - 预设日期范围集合
• PresetTemplate - 预设项的显示模板
• PresetPosition - 预设项的位置（Left、Right、Top、Bottom）

常见用例

1. 预订系统 - 酒店预订、机票预订、租赁服务
2. 报告工具 - 为报告和分析选择日期范围
3. 项目管理 - 定义项目的开始和结束日期、规划冲刺
4. 日历应用 - 活动安排、会议规划
5. 金融应用 - 选择对账单周期、交易日期范围
6. 人力资源系统 - 假期管理、休假规划、工时跟踪
7. 电子商务 - 选择配送日期、设置促销时段
8. 医疗保健 - 预约安排、规划治疗周期

相关技能

• 日历 - 用于选择单个日期
• CalendarDatePicker - 用于带下拉框的单日期选择器