SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场syncfusion-winui-calendar-date-range-picker

syncfusion-winui-calendar-date-range-picker

前端与建站

查看项目

更新于 10-16 02:10

技能介绍

用途

Syncfusion WinUI CalendarDateRangePicker（SfCalendarDateRangePicker）控件为桌面应用提供直观、触摸友好的界面，让用户从下拉日历中快速选择一段连续的日期范围（开始日期与结束日期）。该技能用于在 WinUI 应用中实现日期范围选择功能。

主要能力

控件由以下部分组成：编辑器（显示所选日期范围的文本输入框）、下拉按钮（打开日历下拉）、下拉日历（支持月/年/十年/世纪视图的交互式日历）、预设项面板（可选）、提交按钮（可选 OK/Cancel）、周数列（可选）、标题与描述（可选）。

关键能力包括：触摸友好的范围选择；多种日历系统（公历、希伯来历、伊斯兰历、韩历等）；可自定义日期格式；日期范围限制与校验；屏蔽日期支持；预设日期范围；周数显示；键盘导航；主题自定义。

使用方式

快速开始

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（日历系统，如公历、希伯来历、伊斯兰历等）、FirstDayOfWeek（一周起始日）、ShowWeekNumbers（显示周数）、WeekNumberRule（确定第一周的规则：FirstDay、FirstFourDayWeek、FirstFullWeek）、WeekNumberFormat（周数格式，默认 "#"）。

格式属性：DayFormat（日历中日期数字格式）、MonthFormat（年视图中月份名称格式）、MonthHeaderFormat（月/年标题格式）、DayOfWeekFormat（星期名称格式）。

导航属性：MinDisplayMode（最小视图级别：Month、Year、Decade、Century）、MaxDisplayMode（最大视图级别）。

下拉属性：ShowDropDownButton（显示或隐藏下拉按钮）、ShowSubmitButtons（显示或隐藏 OK/Cancel 按钮）、ShowCalendar（显示或隐藏下拉中的日历）、DropDownPlacement（下拉对齐方式：Bottom、Top、Left、Right、Center）、DropDownHeight（下拉日历高度）。

预设属性：Preset（预设日期范围集合）、PresetTemplate（预设项显示模板）、PresetPosition（预设项位置：Left、Right、Top、Bottom）。

文档导航指南

  • 入门：references/getting-started.md，用于首次安装控件、在 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、处理预设选择事件、选择预设时隐藏日历（ShowCalendar）、计算预设项的日期范围、允许在预设之外自定义范围选择。
  • 周数：references/week-numbers.md，用于启用周数显示（ShowWeekNumbers）、配置周数规则（FirstDay、FirstFourDayWeek、FirstFullWeek）、自定义周数格式前后缀、使用 WeekNumberTemplate、自定义 WeekNameTemplate、了解 CalendarWeekRule 选项、应用基于周的业务逻辑。

适用场景

预订系统（酒店预订、航班预订、租赁服务）；报表工具（为报表和分析选择日期范围）；项目管理（定义项目起止日期、冲刺规划）；日历应用（事件排程、会议规划）；金融应用（选择对账单周期、交易日期范围）；HR 系统（请假管理、休假规划、工时跟踪）；电子商务（配送日期选择、促销期设置）；医疗健康（预约排程、治疗时长规划）。

限制

资料未提供该控件的收费、价格、平台兼容性细节、性能指标或效果保证等信息。相关技能：Calendar（用于单日期选择）、CalendarDatePicker（用于带下拉的单日期选择器）。