Back to Details

syncfusion-winui-calendar-date-range-picker

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Calendar DateRange Picker

实现日历日期范围选择器

The WinUI CalendarDateRangePicker (SfCalendarDateRangePicker) control provides an intuitive, touch-friendly interface to quickly select a date range from a drop-down calendar. It supports different date formats, date range restrictions, preset items, week numbers, localization, and extensive UI customization options.
WinUI CalendarDateRangePicker（SfCalendarDateRangePicker）控件提供了直观、适配触摸操作的界面，可从下拉日历中快速选择日期范围。它支持多种日期格式、日期范围限制、预设项、周数、本地化和丰富的UI自定义选项。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Implement date range selection - Allow users to select a continuous range of dates (start date and end date) from a calendar
  • Add CalendarDateRangePicker to WinUI apps - Install, configure, and use the SfCalendarDateRangePicker control
  • Configure range selection - Set selected range programmatically, handle range change events, validate range selection
  • Restrict date selection - Apply min/max dates, blackout specific dates, limit range duration, block weekend dates
  • Customize calendar UI - Change drop-down alignment, customize item templates, apply themes, modify appearance
  • Support localization - Use different calendar types (Gregorian, Hebrew, Hijri, etc.), change languages, apply RTL
  • Format date display - Customize how dates and ranges are displayed in the editor and calendar
  • Show preset ranges - Display predefined date ranges (This Week, This Month, Last Month, This Year, Custom Range)
  • Enable week numbers - Show week numbers in the calendar with customizable rules and formats
  • Handle navigation - Control view navigation (month, year, decade, century), keyboard shortcuts
  • Validate date ranges - Ensure selected ranges meet minimum/maximum duration requirements
当你需要完成以下需求时可使用本技能：
  • 实现日期范围选择 - 允许用户从日历中选择连续的日期范围（开始日期和结束日期）
  • 为WinUI应用添加CalendarDateRangePicker - 安装、配置并使用SfCalendarDateRangePicker控件
  • 配置范围选择逻辑 - 以编程方式设置选中范围、处理范围变更事件、校验范围选择结果
  • 限制可选日期 - 设置最小/最大可选日期、禁用指定日期、限制选择范围时长、屏蔽周末日期
  • 自定义日历UI - 修改下拉框对齐方式、自定义项模板、应用主题、调整外观样式
  • 支持本地化 - 使用不同日历类型（公历、希伯来历、伊斯兰历等）、切换语言、适配RTL布局
  • 格式化日期展示 - 自定义输入框和日历中日期、范围的展示样式
  • 展示预设范围 - 提供预定义的日期范围选项（本周、本月、上月、今年、自定义范围）
  • 启用周数显示 - 支持在日历中展示周数，可自定义计算规则和格式
  • 处理导航逻辑 - 控制视图导航（月、年、十年、世纪）、支持键盘快捷键
  • 校验日期范围 - 确保选中范围满足最小/最大时长要求

Component Overview

组件概述

The CalendarDateRangePicker control consists of:
  • Editor - Text input displaying the selected date range
  • Drop-down button - Opens the calendar drop-down
  • Drop-down calendar - Interactive calendar for range selection with month/year/decade/century views
  • Preset items panel - Optional list of predefined date ranges
  • Submit buttons - Optional OK/Cancel buttons for range confirmation
  • Week numbers column - Optional display of week numbers
  • Header and description - Optional title and helper text
Key capabilities:
  • Touch-friendly range selection
  • Multiple calendar systems (Gregorian, Hebrew, Hijri, Korean, etc.)
  • Customizable date formats
  • Date range restrictions and validation
  • Blackout dates support
  • Preset date ranges
  • Week number display
  • Keyboard navigation
  • Theme customization
CalendarDateRangePicker控件包含以下部分：
  • 输入框 - 展示选中日期范围的文本输入区域
  • 下拉按钮 - 用于打开日历下拉面板
  • 下拉日历 - 支持范围选择的交互式日历，包含月/年/十年/世纪视图
  • 预设项面板 - 可选的预定义日期范围列表
  • 提交按钮 - 可选的确认/取消按钮，用于确认范围选择结果
  • 周数列 - 可选的周数展示区域
  • 标题和描述 - 可选的控件标题和辅助提示文本
核心能力：
  • 适配触摸操作的范围选择
  • 支持多种日历系统（公历、希伯来历、伊斯兰历、韩国历等）
  • 可自定义的日期格式
  • 日期范围限制与校验
  • 禁用日期支持
  • 预设日期范围
  • 周数显示
  • 键盘导航
  • 主题自定义

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
Use when:
  • Installing the CalendarDateRangePicker control for the first time
  • Adding the control to XAML or C# code
  • Setting the selected range programmatically or interactively
  • Configuring header, description, and placeholder text
  • Handling selection changed events (SelectedDateRangeChanged)
  • Showing or hiding the drop-down button
  • Configuring submit buttons (OK/Cancel)
  • Understanding basic control structure and setup
📄 阅读： references/getting-started.md
适用场景：
  • 首次安装CalendarDateRangePicker控件
  • 在XAML或C#代码中添加控件
  • 以编程方式或交互方式设置选中范围
  • 配置标题、描述和占位符文本
  • 处理选择变更事件（SelectedDateRangeChanged）
  • 展示或隐藏下拉按钮
  • 配置提交按钮（确认/取消）
  • 了解基础控件结构和配置方法

UI Customization

UI自定义

📄 Read: references/ui-customization.md
Use when:
  • Changing drop-down alignment (top, bottom, left, right, center)
  • Customizing drop-down calendar size
  • Creating custom calendar item templates
  • Highlighting special dates with custom styling
  • Applying theme keys for colors and fonts
  • Customizing day, week, and header appearance
  • Using AttachedFlyout and DropDownFlyout for advanced customization
  • Styling the CalendarItem control
  • Creating event-based date decorations
📄 阅读： references/ui-customization.md
适用场景：
  • 修改下拉框对齐方式（上、下、左、右、居中）
  • 自定义下拉日历尺寸
  • 创建自定义日历项模板
  • 为特殊日期添加自定义高亮样式
  • 应用颜色和字体的主题键
  • 自定义日期、周、表头的外观
  • 使用AttachedFlyout和DropDownFlyout实现高级自定义
  • 自定义CalendarItem控件样式
  • 实现基于事件的日期装饰

Localization and Formatting

本地化与格式化

📄 Read: references/localization-formatting.md
Use when:
  • Using different calendar types (Hebrew, Hijri, Korean, Thai, Persian, etc.)
  • Changing the display language (Arabic, French, Japanese, etc.)
  • Customizing editor display format (DisplayDateFormat)
  • Formatting calendar days, months, and headers
  • Changing the first day of the week
  • Implementing right-to-left (RTL) flow direction
  • Applying locale-specific date formatting
  • Supporting international date conventions
📄 阅读： references/localization-formatting.md
适用场景：
  • 使用不同日历类型（希伯来历、伊斯兰历、韩国历、泰历、波斯历等）
  • 切换展示语言（阿拉伯语、法语、日语等）
  • 自定义输入框展示格式（DisplayDateFormat）
  • 格式化日历日期、月份和表头
  • 修改一周的起始日
  • 实现从右到左（RTL）的布局方向
  • 应用符合地区规范的日期格式
  • 适配国际日期使用习惯

Navigation Between Views

视图间导航

📄 Read: references/navigation.md
Use when:
  • Enabling navigation between month, year, decade, and century views
  • Restricting navigation with MinDisplayMode and MaxDisplayMode
  • Implementing view-based selection (e.g., month/year for credit cards)
  • Understanding keyboard navigation shortcuts
  • Controlling which views users can access
  • Navigating to specific dates or view levels
  • Handling view switching in code
📄 阅读： references/navigation.md
适用场景：
  • 启用月、年、十年、世纪视图之间的导航
  • 通过MinDisplayMode和MaxDisplayMode限制可导航的视图范围
  • 实现基于视图的选择（例如信用卡的月/年选择）
  • 了解键盘导航快捷键
  • 控制用户可访问的视图层级
  • 导航到指定日期或视图层级
  • 在代码中处理视图切换逻辑

Restricting Date Range Selection

日期范围选择限制

📄 Read: references/date-restrictions.md
Use when:
  • Setting minimum and maximum selectable dates (MinDate, MaxDate)
  • Blocking specific dates using BlackoutDates collection
  • Disabling weekend dates or holidays dynamically
  • Using ItemPrepared event for custom date restrictions
  • Limiting range duration (MinDatesCountInRange, MaxDatesCountInRange)
  • Validating selected date ranges
  • Preventing invalid date range selection
  • Customizing display text for blocked dates
📄 阅读： references/date-restrictions.md
适用场景：
  • 设置最小和最大可选日期（MinDate、MaxDate）
  • 通过BlackoutDates集合屏蔽指定日期
  • 动态禁用周末日期或节假日
  • 使用ItemPrepared事件实现自定义日期限制
  • 限制选择范围的时长（MinDatesCountInRange、MaxDatesCountInRange）
  • 校验选中的日期范围
  • 防止选择无效的日期范围
  • 自定义禁用日期的展示文本

Preset Items

预设项

📄 Read: references/preset-items.md
Use when:
  • Showing predefined date ranges (This Week, This Month, Last Month, This Year)
  • Creating custom preset items collection
  • Implementing PresetTemplate for custom preset UI
  • Handling preset selection events
  • Hiding calendar when preset is selected (ShowCalendar)
  • Calculating date ranges for preset items
  • Allowing custom range selection alongside presets
📄 阅读： references/preset-items.md
适用场景：
  • 展示预定义日期范围（本周、本月、上月、今年）
  • 创建自定义预设项集合
  • 实现PresetTemplate来自定义预设项UI
  • 处理预设选择事件
  • 选择预设后隐藏日历（ShowCalendar）
  • 计算预设项对应的日期范围
  • 支持同时使用预设范围和自定义范围选择

Week Numbers

周数

📄 Read: references/week-numbers.md
Use when:
  • Enabling week number display (ShowWeekNumbers)
  • Configuring week number rules (FirstDay, FirstFourDayWeek, FirstFullWeek)
  • Customizing week number format with prefix/suffix
  • Using WeekNumberTemplate for custom week number appearance
  • Customizing WeekNameTemplate for day-of-week headers
  • Understanding CalendarWeekRule options
  • Applying week-based business logic
📄 阅读： references/week-numbers.md
适用场景：
  • 启用周数展示（ShowWeekNumbers）
  • 配置周数计算规则（FirstDay、FirstFourDayWeek、FirstFullWeek）
  • 自定义周数格式的前缀/后缀
  • 使用WeekNumberTemplate自定义周数展示样式
  • 自定义WeekNameTemplate修改星期表头
  • 了解CalendarWeekRule的可选配置
  • 实现基于周的业务逻辑

Quick Start

快速开始

Basic Implementation

基础实现

XAML:
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#:
csharp
using Syncfusion.UI.Xaml.Calendar;

SfCalendarDateRangePicker sfCalendarDateRangePicker = new SfCalendarDateRangePicker();
sfCalendarDateRangePicker.PlaceholderText = "Select a date range";
this.Content = sfCalendarDateRangePicker;
XAML:
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#:
csharp
using Syncfusion.UI.Xaml.Calendar;

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

Setting Selected Range Programmatically

以编程方式设置选中范围

csharp
// 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;
csharp
// 设置日期范围
sfCalendarDateRangePicker.SelectedRange = new DateTimeOffsetRange(
    new DateTimeOffset(new DateTime(2026, 3, 1)), 
    new DateTimeOffset(new DateTime(2026, 3, 15))
);

// 清空选择
sfCalendarDateRangePicker.SelectedRange = null;

Handling Selection Changes

处理选择变更事件

csharp
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");
    }
};
csharp
sfCalendarDateRangePicker.SelectedDateRangeChanged += (sender, e) =>
{
    var startOld = e.RangeStartOldValue;
    var startNew = e.RangeStartNewValue;
    var endOld = e.RangeEndOldValue;
    var endNew = e.RangeEndNewValue;
    
    // 处理新的选择范围
    if (startNew.HasValue && endNew.HasValue)
    {
        TimeSpan duration = endNew.Value - startNew.Value;
        Debug.WriteLine($"Selected range: {duration.Days} days");
    }
};

Common Patterns

常见使用模式

Pattern 1: Date Range with Restrictions

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

csharp
// 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
csharp
// 限制只能选择90天内的未来日期
sfCalendarDateRangePicker.MinDate = DateTimeOffset.Now;
sfCalendarDateRangePicker.MaxDate = DateTimeOffset.Now.AddDays(90);
sfCalendarDateRangePicker.MinDatesCountInRange = 3;  // 最少选择3天
sfCalendarDateRangePicker.MaxDatesCountInRange = 14; // 最多选择14天

Pattern 2: Blocking Weekend Dates

模式2：屏蔽周末日期

csharp
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;
    }
};
csharp
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;
    }
};

Pattern 3: With Header and Description

模式3：带标题和描述的控件

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

Pattern 4: Custom Display Format

模式4：自定义展示格式

csharp
// Display as full date names
sfCalendarDateRangePicker.DisplayDateFormat = "{0:D} - {1:D}";
// Example: "Saturday, March 1, 2026 - Sunday, March 15, 2026"
csharp
// 展示完整日期名称
sfCalendarDateRangePicker.DisplayDateFormat = "{0:D} - {1:D}";
// 示例："Saturday, March 1, 2026 - Sunday, March 15, 2026"

Pattern 5: Localized Calendar

模式5：本地化日历

csharp
// Hebrew calendar with RTL support
sfCalendarDateRangePicker.CalendarIdentifier = "HebrewCalendar";
sfCalendarDateRangePicker.Language = "he-IL";
sfCalendarDateRangePicker.FlowDirection = FlowDirection.RightToLeft;
csharp
// 支持RTL布局的希伯来历日历
sfCalendarDateRangePicker.CalendarIdentifier = "HebrewCalendar";
sfCalendarDateRangePicker.Language = "he-IL";
sfCalendarDateRangePicker.FlowDirection = FlowDirection.RightToLeft;

Key Properties

核心属性

Selection Properties

选择属性

  • SelectedRange - Gets or sets the selected date range (DateTimeOffsetRange)
  • MinDatesCountInRange - Minimum number of dates in the selected range
  • MaxDatesCountInRange - Maximum number of dates in the selected range
  • SelectedRange - 获取或设置选中的日期范围（DateTimeOffsetRange类型）
  • MinDatesCountInRange - 选中范围的最小天数
  • MaxDatesCountInRange - 选中范围的最大天数

Restriction Properties

限制属性

  • MinDate - Minimum selectable date (default: 1/1/1920)
  • MaxDate - Maximum selectable date (default: 12/31/2120)
  • BlackoutDates - Collection of dates to disable
  • MinDate - 最小可选日期（默认值：1920/1/1）
  • MaxDate - 最大可选日期（默认值：2120/12/31）
  • BlackoutDates - 禁用的日期集合

Display Properties

展示属性

  • DisplayDateFormat - Format for displaying the selected range in the editor (default: "{0:d}-{1:d}")
  • PlaceholderText - Watermark text when no range is selected
  • Header - Title above the control
  • HeaderTemplate - Custom template for the header
  • Description - Helper text below the control
  • DisplayDateFormat - 输入框中选中范围的展示格式（默认值："{0:d}-{1:d}"）
  • PlaceholderText - 未选择范围时的水印文本
  • Header - 控件上方的标题
  • HeaderTemplate - 标题的自定义模板
  • Description - 控件下方的辅助提示文本

Calendar Properties

日历属性

  • CalendarIdentifier - Calendar system (Gregorian, Hebrew, Hijri, etc.)
  • FirstDayOfWeek - Starting day of the week
  • ShowWeekNumbers - Display week numbers
  • WeekNumberRule - Rule for determining first week (FirstDay, FirstFourDayWeek, FirstFullWeek)
  • WeekNumberFormat - Format for week numbers (default: "#")
  • CalendarIdentifier - 日历系统（公历、希伯来历、伊斯兰历等）
  • FirstDayOfWeek - 一周的起始日
  • ShowWeekNumbers - 是否展示周数
  • WeekNumberRule - 第一周的计算规则（FirstDay、FirstFourDayWeek、FirstFullWeek）
  • WeekNumberFormat - 周数的展示格式（默认值："#"）

Format Properties

格式属性

  • DayFormat - Format for day numbers in calendar
  • MonthFormat - Format for month names in year view
  • MonthHeaderFormat - Format for month/year header
  • DayOfWeekFormat - Format for day-of-week names
  • DayFormat - 日历中日期数字的格式
  • MonthFormat - 年视图中月份名称的格式
  • MonthHeaderFormat - 月/年表头的格式
  • DayOfWeekFormat - 星期名称的格式

Navigation Properties

导航属性

  • MinDisplayMode - Minimum view level (Month, Year, Decade, Century)
  • MaxDisplayMode - Maximum view level (Month, Year, Decade, Century)
  • MinDisplayMode - 最小视图层级（月、年、十年、世纪）
  • MaxDisplayMode - 最大视图层级（月、年、十年、世纪）

Drop-down Properties

下拉属性

  • ShowDropDownButton - Show or hide the drop-down button
  • ShowSubmitButtons - Show or hide OK/Cancel buttons
  • ShowCalendar - Show or hide the calendar in drop-down
  • DropDownPlacement - Alignment of drop-down (Bottom, Top, Left, Right, Center)
  • DropDownHeight - Height of the drop-down calendar
  • ShowDropDownButton - 是否展示下拉按钮
  • ShowSubmitButtons - 是否展示确认/取消按钮
  • ShowCalendar - 下拉面板中是否展示日历
  • DropDownPlacement - 下拉面板的对齐方式（下、上、左、右、居中）
  • DropDownHeight - 下拉日历的高度

Preset Properties

预设属性

  • Preset - Collection of preset date ranges
  • PresetTemplate - Template for displaying preset items
  • PresetPosition - Position of preset items (Left, Right, Top, Bottom)
  • Preset - 预设日期范围集合
  • PresetTemplate - 预设项的展示模板
  • PresetPosition - 预设项的展示位置（左、右、上、下）

Common Use Cases

常见使用场景

  1. Booking Systems - Hotel reservations, flight bookings, rental services
  2. Reporting Tools - Select date ranges for reports and analytics
  3. Project Management - Define project start and end dates, sprint planning
  4. Calendar Applications - Event scheduling, meeting planning
  5. Financial Applications - Select statement periods, transaction date ranges
  6. HR Systems - Leave management, vacation planning, time tracking
  7. E-commerce - Delivery date selection, promotional period setup
  8. Healthcare - Appointment scheduling, treatment duration planning
  1. 预订系统 - 酒店预订、机票预订、租赁服务
  2. 报表工具 - 为报表和分析选择日期范围
  3. 项目管理 - 定义项目起止日期、迭代规划
  4. 日历应用 - 事件调度、会议规划
  5. 金融应用 - 选择账单周期、交易日期范围
  6. HR系统 - 请假管理、休假规划、工时统计
  7. 电商应用 - 配送日期选择、促销周期设置
  8. 医疗系统 - 预约调度、治疗周期规划

Related Skills

相关技能

  • Calendar - For single date selection
  • CalendarDatePicker - For single date picker with drop-down
  • Calendar - 用于单一日期选择
  • CalendarDatePicker - 用于带下拉面板的单一日期选择