syncfusion-blazor-calendars

实现 Syncfusion Blazor 日历

日历

Calendar 组件是一款轻量且功能丰富的日期选择组件，支持灵活选择日期、多种视图（月／年／十年）、日期范围限制、本地化和无障碍合规。需要实现日期选择、日历显示或基于日期的 UI 交互时，请使用此技能。

何时使用此技能

适用场景：

• 构建日期选择器、日历小组件或日期选择界面
• 添加日期范围限制（最小／最大日期）
• 实现多月或逐级深入的日期选择（年／十年视图）
• 处理日期值更改和事件
• 设置日历样式或自定义外观
• 支持国际日期格式和 RTL 布局
• 创建支持键盘导航的无障碍日历界面

相关组件：

• DatePicker（带日历下拉菜单的日期输入）
• DateRangePicker（日期范围选择）
• DateTimePicker（日期和时间选择）
• Scheduler（复杂的基于日期的日程安排）

组件概览

功能	详情
视图	月（默认）、年、十年 - 分层逐级深入导航
选择	单个日期、日期范围（最小／最大）、多选
数据类型	DateTime、DateTime?、DateOnly（.NET 6+）
绑定	单向、双向（@bind-Value）、动态
事件	ValueChange、OnRenderDayCell、Created、Destroyed、Navigated
本地化	多语言、支持 RTL、区域设置自定义
无障碍	WCAG 2.2 AA、键盘导航、屏幕阅读器支持
样式	CSS 自定义、主题集成、特殊日期高亮

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

• 安装和 NuGet 包
• Web 和 Server 应用设置
• Blazor 命名空间和服务注册
• 基本日历实现
• 最小／最大日期限制

日历视图与导航

📄 阅读： references/calendar-views.md

• 月、年、十年视图
• Start 和 Depth 属性
• 视图限制和逐级深入导航
• 限制日期选择深度

日期选择与数据绑定

📄 阅读： references/date-selection-binding.md

• Value 属性和日期绑定
• 单向绑定与双向绑定（@bind-Value）
• 支持 DateOnly（.NET 6+）
• 动态值更改
• 日期范围限制

事件与交互

📄 阅读： references/events-handling.md

• ValueChange 事件（日期选择）
• Selected／DeSelected 事件（多选）
• OnRenderDayCell 事件（自定义渲染）
• Created 和 Destroyed 生命周期事件
• Navigated 事件（视图更改）
• 事件参数和响应式模式
• 使用 CalendarEvents 子组件

样式与自定义

📄 阅读： references/styling-appearance.md

• CSS 自定义模式
• 背景颜色、边框、悬停状态
• 日期单元格样式
• 标题和标题栏自定义
• 今天按钮和选中日期样式
• 特殊日期高亮

本地化与全球化

📄 阅读： references/localization-globalization.md

• 区域设置支持和语言文件
• 从右向左（RTL）布局
• 伊斯兰历和自定义日历
• 星期自定义（每周的第一天）
• 日期格式本地化

无障碍与键盘导航

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 AA 标准
• 屏幕阅读器支持（WAI-ARIA）
• 键盘导航快捷键
• 焦点管理和 ARIA 属性

高级功能与模式

📄 阅读：references/advanced-features.md

• 显示/隐藏其他月份的日期
• 自定义单元格渲染模式
• 多日期选择
• 显示周数
• 性能优化
• 常见集成模式

快速入门示例

@using Syncfusion.Blazor.Calendars


<SfCalendar TValue="DateTime?" Value="@SelectedDate"></SfCalendar>


<SfCalendar TValue="DateTime?" 
    Value="@SelectedDate" 
    Min="@MinDate" 
    Max="@MaxDate">
</SfCalendar>


<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate">
    <CalendarEvents TValue="DateTime?" ValueChange="@OnDateChanged"></CalendarEvents>
</SfCalendar>


<SfCalendar TValue="DateTime?" 
    IsMultiSelection="true"
    @bind-Values="@SelectedDates">
    <CalendarEvents TValue="DateTime?" 
        Selected="@OnDateSelected"
        DeSelected="@OnDateDeselected">
    </CalendarEvents>
</SfCalendar>

@code {
    public DateTime? SelectedDate { get; set; } = DateTime.Now;
    public DateTime[] SelectedDates { get; set; } = new DateTime[] { };

    private void OnDateChanged(ChangedEventArgs<DateTime?> args)
    {
        SelectedDate = args.Value;
        // Handle date change
    }
    
    private void OnDateSelected(SelectedEventArgs<DateTime?> args)
    {
        // Handle date added to selection
    }
    
    private void OnDateDeselected(DeSelectedEventArgs<DateTime?> args)
    {
        // Handle date removed from selection
    }
}

常见模式

模式 1：日期范围选择

定义最小和最大边界，以限制用户的选择：

<SfCalendar TValue="DateTime?" Value="@SelectedDate" 
    Min="@MinDate" Max="@MaxDate"></SfCalendar>

模式 2：双向数据绑定

使 Calendar 与组件状态保持同步：

<p>Selected: @SelectedDate</p>
<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate"></SfCalendar>

模式 3：自定义单元格渲染

在渲染期间突出显示或自定义特定日期单元格：

<SfCalendar TValue="DateTime?">
    <CalendarEvents TValue="DateTime?" OnRenderDayCell="@CustomizeCell"></CalendarEvents>
</SfCalendar>

模式 4：视图限制

将导航限制在特定视图层级（例如，仅限“年 → 月”）：

<SfCalendar TValue="DateTime?" 
    Start="CalendarView.Year" 
    Depth="CalendarView.Month"></SfCalendar>

模式 5：本地化

以特定语言/区域设置渲染日历：

<SfCalendar TValue="DateTime?" EnableRtl="false"></SfCalendar>

主要属性及其适用场景

属性	类型	用途	示例
Value	TValue	选定日期（单向绑定）	Value="@SelectedDate"
@bind-Value	TValue	双向数据绑定	@bind-Value="@SelectedDate"
Values	DateTime[]	多个选定日期（多选模式）	Values="@SelectedDates"
@bind-Values	DateTime[]	多选的双向绑定	@bind-Values="@SelectedDates"
IsMultiSelection	bool	启用多日期选择	IsMultiSelection="true"
Min	DateTime	最早可选日期（含）	Min="@minSelectableDate"
Max	DateTime	最晚可选日期（含）	Max="@maxSelectableDate"
Start	CalendarView	初始视图（Month/Year/Decade）	Start="CalendarView.Year"
Depth	CalendarView	深入查看时可到达的最深视图层级	Depth="CalendarView.Month"
ShowTodayButton	bool	在页脚显示“今天”按钮	ShowTodayButton="true"
CalendarMode	CalendarType	日历系统（Gregorian/Islamic）	CalendarMode="CalendarType.Islamic"
WeekRule	CalendarWeekRule	周编号计算规则	WeekRule="CalendarWeekRule.FirstDay"
DayHeaderFormat	DayHeaderFormats	星期标题显示格式	DayHeaderFormat="DayHeaderFormats.Short"
EnableRtl	bool	从右到左布局	EnableRtl="true"
WeekNumber	bool	在日历中显示周数	WeekNumber="true"
FirstDayOfWeek	int	每周的第一天（0=星期日，1=星期一）	FirstDayOfWeek="1"
CssClass	string	用于设置样式的自定义 CSS 类	CssClass="custom-calendar"
Enabled	bool	启用/禁用组件	Enabled="false"

常见用例

1. 预约预订：包含日期范围（可用日期）并处理事件的日历
2. 日期筛选器：用于逐层选择特定日期的多视图日历
3. 截止日期选择：通过 Min/Max 限制有效日期范围
4. 报告查看：用于选择时段的年/月视图
5. 国际化应用：支持 RTL 和区域设置的多语言 UI
6. 无障碍表单：支持键盘导航和屏幕阅读器的日期输入

处理事件

所有日历组件都使用子事件组件来声明事件处理程序。这种方式可以确保类型安全，并清晰地划分职责。

事件子组件

• Calendar：使用 <CalendarEvents> 子组件
• DatePicker：使用 <DatePickerEvents> 子组件
• DateRangePicker：使用 <DateRangePickerEvents> 子组件
• DateTimePicker：使用 <DateTimePickerEvents> 子组件
• TimePicker：使用 <TimePickerEvents> 子组件

示例：带事件的 Calendar

<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate">
    <CalendarEvents TValue="DateTime?" 
        ValueChange="@OnValueChanged"
        OnRenderDayCell="@OnDayCellRender"
        Navigated="@OnNavigated">
    </CalendarEvents>
</SfCalendar>

@code {
    private DateTime? SelectedDate { get; set; }
    
    private void OnValueChanged(ChangedEventArgs<DateTime?> args)
    {
        Console.WriteLine($"Date changed: {args.Value}");
    }
    
    private void OnDayCellRender(RenderDayCellEventArgs args)
    {
        // Disable weekends
        if (args.Date.DayOfWeek == DayOfWeek.Saturday || args.Date.DayOfWeek == DayOfWeek.Sunday)
        {
            args.IsDisabled = true;
        }
    }
    
    private void OnNavigated(NavigatedEventArgs args)
    {
        Console.WriteLine($"Navigated to: {args.View}");
    }
}

常见事件模式

模式 1：值更改时进行验证

<SfDatePicker TValue="DateTime?" @bind-Value="@OrderDate">
    <DatePickerEvents TValue="DateTime?" ValueChange="@ValidateAndUpdate"></DatePickerEvents>
</SfDatePicker>

@code {
    private DateTime? OrderDate { get; set; }
    
    private void ValidateAndUpdate(ChangedEventArgs<DateTime?> args)
    {
        if (args.Value.HasValue && args.Value.Value > DateTime.Now.AddMonths(6))
        {
            // Show error - date too far in future
            OrderDate = DateTime.Now;
        }
        else
        {
            OrderDate = args.Value;
        }
    }
}

模式 2：弹出窗口生命周期管理

<SfDateTimePicker TValue="DateTime?" @bind-Value="@AppointmentTime">
    <DateTimePickerEvents TValue="DateTime?" 
        OnOpen="@HandlePopupOpen"
        OnClose="@HandlePopupClose">
    </DateTimePickerEvents>
</SfDateTimePicker>

@code {
    private DateTime? AppointmentTime { get; set; }
    
    private void HandlePopupOpen(PopupObjectArgs args)
    {
        Console.WriteLine("Popup opened");
        // Can cancel opening: args.Cancel = true;
    }
    
    private void HandlePopupClose(PopupObjectArgs args)
    {
        Console.WriteLine("Popup closed");
    }
}

模式 3：自定义单元格渲染

<SfCalendar TValue="DateTime?" @bind-Value="@EventDate">
    <CalendarEvents TValue="DateTime?" OnRenderDayCell="@CustomizeCells"></CalendarEvents>
</SfCalendar>

@code {
    private DateTime? EventDate { get; set; }
    private List<DateTime> EventDates = new List<DateTime> 
    { 
        DateTime.Now.AddDays(5),
        DateTime.Now.AddDays(10)
    };
    
    private void CustomizeCells(RenderDayCellEventArgs args)
    {
        // Highlight event dates
        if (EventDates.Any(d => d.Date == args.Date.Date))
        {
            args.CellData.ClassList = "e-special-date";
        }
    }
}

事件参数类型参考

重要： 不同组件的 ValueChange 事件使用不同的事件参数类型：

组件	ValueChange 事件参数类型	备注
Calendar	ChangedEventArgs<TValue>	用于单日期和多日期选择
DatePicker	ChangedEventArgs<TValue>	包含 Value、IsInteracted、Event 属性
DateTimePicker	ChangedEventArgs<TValue>	与 DatePicker 相同
TimePicker	ChangeEventArgs<TValue>	注意：类名不同（没有字母“d”）
DateRangePicker	RangePickerEventArgs<TValue>	包含 StartDate 和 EndDate 属性

主要区别：

• ChangedEventArgs<TValue>（带字母“d”）- 由 Calendar、DatePicker、DateTimePicker 使用
  • 属性：Value、Values（用于多选）、IsInteracted、Event、Element、Name
• ChangeEventArgs<TValue>（不带字母“d”）- 仅由 TimePicker 使用
  • 属性：Value、Text、IsInteracted、Event、Element
• RangePickerEventArgs<TValue> - 仅由 DateRangePicker 使用
  • 属性：StartDate、EndDate、Text、Value、IsInteracted、Event、Element

---

DatePicker

全面介绍如何实现和自定义 DatePicker 组件。本指南将帮助你在 Blazor Server、Blazor WebAssembly 和 Blazor Web App 项目中安装、配置和集成 DatePicker。

适用场景

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

• 在任何类型的 Blazor 项目中安装和设置 Syncfusion DatePicker
• 实现带输入验证的基本日期选择
• 配置单向和双向数据绑定
• 设置自定义日期格式和输入格式
• 应用日期范围限制（最小/最大日期）
• 突出显示或禁用特殊日期
• 处理 DatePicker 事件（ValueChange、OnClose、Focus、Blur）
• 对组件进行全球化和本地化（不同语言/日历）
• 在 DatePicker 中使用 DateOnly（.NET 6+）
• 设置样式并自定义外观（只读、禁用状态、主题）
• 实现键盘导航和无障碍访问
• 排查数据绑定、格式或事件问题
• 优化 Blazor Server 与 WebAssembly 中的性能
• 将日期选择与表单和 API 集成

组件概览

DatePicker 组件提供直观的日历 UI，供用户选择单个日期。它支持：

• 多种输入方式： 直接输入、使用日历选择器，或两者兼用
• 日期限制： 最小/最大日期范围、禁用日期、特殊日期高亮
• 灵活的格式设置： 自定义显示格式和输入格式
• 全球化支持： 多种语言、日历（公历、伊斯兰历）、RTL
• 无障碍访问： 符合 WCAG 标准、键盘导航、屏幕阅读器支持
• 事件系统： 值更改、弹出窗口打开/关闭、焦点/失焦事件
• 主题支持： Bootstrap、Material、Fluent、Tailwind CSS

快速安装指南

1. 安装 NuGet 包

dotnet add package Syncfusion.Blazor.Calendars
dotnet add package Syncfusion.Blazor.Themes

2. 在 _Imports.razor 中导入

@using Syncfusion.Blazor
@using Syncfusion.Blazor.Calendars

3. 在 Program.cs 中注册

builder.Services.AddSyncfusionBlazor();

4. 在 App.razor 或布局中添加主题

<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>

5. 在组件中使用

<SfDatePicker TValue="DateTime?" @bind-Value="@selectedDate">
    <DatePickerEvents TValue="DateTime?" ValueChange="@OnDateChange"></DatePickerEvents>
</SfDatePicker>

@code {
    DateTime? selectedDate = new DateTime(2026, 3, 18);
    
    void OnDateChange(ChangedEventArgs<DateTime?> args)
    {
        selectedDate = args.Value;
    }
}

文档导航指南

根据你的任务选择参考文档：

入门

📄 阅读： references/getting-started.md

• 在 Blazor Server、WebAssembly 和 Web App 中安装
• NuGet 包设置
• 主题配置
• 服务注册
• DatePicker 基本示例

数据绑定

📄 阅读： references/data-binding.md

• 使用 Value 属性进行单向绑定
• 使用 @bind-Value 进行双向绑定
• 动态值更新和 null 处理
• 绑定到 DateTime 与 DateTime?

日期格式与输入

📄 阅读： references/date-formats-and-input.md

• 自定义显示格式（d/M/yyyy、dd/MM/yyyy 等）
• 输入格式模式
• 占位文本配置
• 格式解析与验证
• 自定义格式示例

日期范围与限制

📄 阅读： references/date-range-and-constraints.md

• 最小/最大日期限制
• 禁用指定日期
• 特殊日期高亮
• 日期验证逻辑
• 防止无效选择

事件与交互

📄 阅读： references/events.md

• ValueChange 事件处理
• OnOpen/OnClose 事件（弹出窗口生命周期）
• Selected 事件（日历中的日期选择）
• Focus/Blur 事件
• Cleared 事件（点击清除按钮）
• Created/Destroyed 生命周期事件
• Navigated 事件（日历视图导航）
• OnRenderDayCell 事件（自定义日期单元格渲染）
• 使用 DatePickerEvents 子组件

高级功能

📄 阅读： references/advanced-features.md

• 支持伊斯兰历
• 支持 DateOnly（.NET 6+）
• 全球化与本地化
• 显示周数
• 不同视图模式
• 掩码支持与输入掩码

样式与外观

📄 阅读： references/styling-and-appearance.md

• CSS 自定义与主题
• 只读状态样式
• 禁用状态样式
• RTL（从右向左）支持
• 主题切换（Bootstrap、Material、Fluent、Tailwind）
• 自定义样式示例

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 标准
• 键盘导航（方向键、Enter、Escape）
• ARIA 属性与角色
• 屏幕阅读器支持
• 色彩对比度与视觉指示器
• 焦点管理

服务端与 WebAssembly

📄 阅读： references/server-vs-webassembly.md

• Blazor Server 与 WebAssembly 的差异
• Blazor Web App（.NET 8+）设置
• 渲染模式（InteractiveServer、InteractiveWebAssembly）
• 性能考量
• 事件交互性

故障排除

📄 阅读： references/troubleshooting.md

• 数据绑定问题
• 日期格式问题
• 事件处理问题
• 样式与布局问题
• 性能优化
• 常见错误消息与解决方案

常见模式

模式 1：基本日期选择

<SfDatePicker TValue="DateTime?" Value="@selectedDate" 
              Placeholder="Select a date"></SfDatePicker>

适用场景：用户需要用于表单输入的简单标准日期选择器。

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

<SfDatePicker TValue="DateTime?" Value="@selectedDate"
              Min="@minDate" Max="@maxDate"></SfDatePicker>

适用场景：日期必须处于特定范围内（例如，仅限未来日期、活动日期）。

模式 3：双向绑定

<SfDatePicker TValue="DateTime?" @bind-Value="@formData.BirthDate"></SfDatePicker>

适用场景：DatePicker 必须自动更新父组件状态或表单数据。

模式 4：事件驱动逻辑

<SfDatePicker TValue="DateTime?">
    <DatePickerEvents TValue="DateTime?" ValueChange="@OnDateSelected"></DatePickerEvents>
</SfDatePicker>

@code {
    void OnDateSelected(ChangedEventArgs<DateTime?> args)
    {
        // Trigger calculations, API calls, or validation
    }
}

适用场景：选择日期后应触发工作流、计算或依赖项更新。

模式 5：自定义输入的格式化显示

<SfDatePicker TValue="DateTime?" Value="@selectedDate"
              Format="dd/MM/yyyy" Placeholder="DD/MM/YYYY"></SfDatePicker>

适用场景：日期显示必须符合地区或业务要求。

关键属性

属性	类型	用途
Value	TValue	选定的日期（单向绑定）
@bind-Value	TValue	双向数据绑定
Min	DateTime	可选日期的最早值
Max	DateTime	可选日期的最晚值
Format	string	显示格式模式（例如，“dd/MM/yyyy”）
Placeholder	string	输入框占位文本
AllowEdit	bool	允许手动编辑文本输入
StrictMode	bool	仅允许有效日期
EnableMask	bool	启用日期输入掩码
OpenOnFocus	bool	输入框获得焦点时打开日历弹出框
FloatLabelType	FloatLabelType	浮动标签行为（自动/始终/从不）
InputFormats	string[]	可接受的输入格式数组
Enabled	bool	启用/禁用组件
Readonly	bool	只读模式（不允许用户输入）
ShowClearButton	bool	显示清除按钮以重置值
WeekNumber	bool	在日历中显示周数
Start	CalendarView	初始日历视图（月/年/十年）
Depth	CalendarView	允许的最深视图级别
ZIndex	int	弹出框定位的 Z-index
Width	string	组件宽度（例如，“300px”）
CssClass	string	用于设置样式的自定义 CSS 类

性能提示

1. 对可选日期字段使用 DateTime?（可空类型）——避免默认日期造成混淆
2. 在模态框或可展开区域中延迟加载 DatePicker——降低初始渲染开销
3. 尽量减少事件处理程序中的格式转换——尽可能缓存格式化字符串
4. 对日期密集型 UI 使用 InteractiveWebAssembly——将处理工作转移到客户端
5. 在循环中批量更新值——避免多次 ValueChange 触发导致频繁重新渲染

---

DateRangePicker

用于实现和自定义 DateRangePicker 组件的综合技能。此组件支持用户通过日历选择器选择日期范围，并提供范围限制、自定义、无障碍和全球化功能。

何时使用此技能

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

• 在 Blazor 应用程序中安装和设置 DateRangePicker 组件
• 创建日期范围选择界面
• 设置最小和最大日期限制
• 将组件值绑定到数据模型
• 自定义占位文本、一周的首日和视觉外观
• 实现键盘导航和无障碍功能
• 处理组件事件（更改、失焦、聚焦等）
• 为不同区域性配置全球化和本地化
• 在 .NET 6+ 项目中支持 DateOnly 类型
• 在输入框点击时或以编程方式打开弹出框
• 在日历中显示周数
• 应用自定义 CSS 样式和主题
• 使用 RTL（从右向左）语言
• 调试常见的 DateRangePicker 问题

组件概述

SfDateRangePicker 是一种基于日历的输入组件，允许用户选择连续的日期范围。主要特点：

• 双日历视图：显示两个月份的日历，方便选择日期范围
• 范围限制：Min/Max 属性可限制日期范围
• 灵活的数据绑定：适用于 DateTime、DateTime? 和 DateOnly 类型
• 可自定义：一周的首日、占位文本、弹出行为和样式
• 无障碍：完全符合 WCAG 2.2 AA 标准，并支持键盘导航
• 全球化：支持多种区域性、RTL 和日期格式
• 事件驱动：提供全面的用户交互事件系统
• 适合移动设备：针对触控优化的日历界面

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 通过 NuGet 包安装
• 导入命名空间并注册服务
• 基本组件设置（WebAssembly 和 Server 应用）
• 添加主题样式表
• 设置 Min/Max 日期限制
• 呈现你的第一个 DateRangePicker

范围选择与数据绑定

📄 阅读： references/range-selection.md

• 单日期与日期范围选择模式
• 使用 @bind 进行双向数据绑定
• 以编程方式更新范围
• 清除日期选择
• 在 .NET 6+ 中使用 DateOnly 类型
• 处理值更改

自定义与样式

📄 阅读： references/customization-and-styling.md

• 配置一周的第一天
• 设置占位文本
• 应用自定义 CSS 类
• 点击输入框时打开弹出窗口
• 显示周数
• 外观和视觉自定义
• 主题集成

数据与全球化

📄 阅读： references/data-and-globalization.md

• 数据绑定模式和最佳实践
• DateOnly 类型支持与用法
• 全球化配置
• 特定区域性的日期格式
• 从右向左（RTL）语言支持
• 面向国际受众的本地化

事件与交互

📄 阅读： references/events-and-interactions.md

• ValueChange 事件（范围选择完成）
• RangeSelected 事件（单个日期选择）
• OnOpen/OnClose 事件（弹出窗口生命周期）
• Focus/Blur 事件
• Cleared 事件（点击清除按钮）
• Created/Destroyed 生命周期事件
• Navigated 事件（日历视图导航）
• OnRenderDayCell 事件（自定义日期单元格渲染）
• 使用 DateRangePickerEvents 子组件
• 事件参数类型（RangePickerEventArgs）

无障碍

📄 阅读： references/accessibility.md

• WCAG 2.2 AA 合规性概述
• 键盘导航快捷键
• 日历月份导航按键
• ARIA 属性和屏幕阅读器支持
• 移动设备无障碍功能
• 无障碍测试与验证

快速开始

基本 DateRangePicker

@using Syncfusion.Blazor.Calendars

<SfDateRangePicker TValue="DateTime?" Placeholder="Select a date range"></SfDateRangePicker>

带日期限制

<SfDateRangePicker TValue="DateTime?" 
    Placeholder="Choose a range" 
    Min="@MinDate" 
    Max="@MaxDate">
</SfDateRangePicker>

@code {
    public DateTime MinDate { get; set; } = new DateTime(2024, 1, 1);
    public DateTime MaxDate { get; set; } = new DateTime(2024, 12, 31);
}

带数据绑定（StartDate/EndDate）

<SfDateRangePicker TValue="DateTime?" 
    @bind-StartDate="StartDate" 
    @bind-EndDate="EndDate">
</SfDateRangePicker>

@code {
    private DateTime? StartDate { get; set; }
    private DateTime? EndDate { get; set; }
}

带范围限制

<SfDateRangePicker TValue="DateTime?" 
    MinDays="3" 
    MaxDays="30"
    @bind-StartDate="StartDate" 
    @bind-EndDate="EndDate">
</SfDateRangePicker>

@code {
    // User must select range between 3 and 30 days
    private DateTime? StartDate { get; set; }
    private DateTime? EndDate { get; set; }
}

带预设范围

<SfDateRangePicker TValue="DateTime?">
    <DateRangePickerPresets>
        <DateRangePickerPreset Label="Last 7 Days" Start="@last7DaysStart" End="@currentDate"></DateRangePickerPreset>
        <DateRangePickerPreset Label="Last 30 Days" Start="@last30DaysStart" End="@currentDate"></DateRangePickerPreset>
        <DateRangePickerPreset Label="This Month" Start="@currentMonthStart" End="@currentDate"></DateRangePickerPreset>
    </DateRangePickerPresets>
</SfDateRangePicker>

@code {
    private DateTime currentDate = DateTime.Now;
    private DateTime last7DaysStart = DateTime.Now.AddDays(-7);
    private DateTime last30DaysStart = DateTime.Now.AddDays(-30);
    private DateTime currentMonthStart = new DateTime(DateTime.Now.Year, DateTime.Now.Month, 1);
}

关键属性

属性	类型	用途
StartDate	TValue	范围的开始日期（单向绑定）
@bind-StartDate	TValue	开始日期的双向绑定
EndDate	TValue	范围的结束日期（单向绑定）
@bind-EndDate	TValue	结束日期的双向绑定
Value	Object	组合范围值（旧版）
Min	DateTime	可选的最早日期
Max	DateTime	可选的最晚日期
MinDays	int?	范围内要求的最少天数
MaxDays	int?	范围内允许的最多天数
Presets	List<Presets>	预定义日期范围选项
Separator	string	开始日期与结束日期之间的分隔符（默认值："-"）
Format	string	显示格式模式
Placeholder	string	输入框占位文本
AllowEdit	bool	允许手动编辑文本输入
StrictMode	bool	仅限有效日期
OpenOnFocus	bool	输入框获得焦点时打开弹出窗口
FloatLabelType	FloatLabelType	浮动标签行为
Enabled	bool	启用/禁用组件
Readonly	bool	只读模式
ShowClearButton	bool	显示清除按钮
WeekNumber	bool	显示周数
FirstDayOfWeek	int	一周的第一天（0=星期日，1=星期一）
ZIndex	int	弹出窗口的 Z-index
Width	string	组件宽度
CssClass	string	自定义 CSS 类

常见模式

模式 1：带验证的范围选择

<SfDateRangePicker TValue="DateTime?" 
    @bind-Value="BookingRange" 
    Min="@minBookingDate"
    Placeholder="Select booking dates">
</SfDateRangePicker>

@code {
    private DateTime? BookingRange { get; set; }
    private DateTime minBookingDate = DateTime.Today;
}

模式 2：事件处理

<SfDateRangePicker TValue="DateTime?" 
    @bind-StartDate="@StartDate"
    @bind-EndDate="@EndDate">
    <DateRangePickerEvents TValue="DateTime?" ValueChange="@OnDateRangeChange"></DateRangePickerEvents>
</SfDateRangePicker>

@code {
    private DateTime? StartDate { get; set; }
    private DateTime? EndDate { get; set; }
    
    private void OnDateRangeChange(RangePickerEventArgs<DateTime?> args)
    {
        // Handle date range selection
        Console.WriteLine($"Start: {args.StartDate}, End: {args.EndDate}");
    }
}

模式 3：具有不同限制的多个实例

<div>
    <h4>Q1 Reporting Period (Jan-Mar)</h4>
    <SfDateRangePicker TValue="DateTime?" 
        Min="@new DateTime(2024, 1, 1)" 
        Max="@new DateTime(2024, 3, 31)"
        Placeholder="Select dates">
    </SfDateRangePicker>
</div>

<div>
    <h4>Q2 Reporting Period (Apr-Jun)</h4>
    <SfDateRangePicker TValue="DateTime?" 
        Min="@new DateTime(2024, 4, 1)" 
        Max="@new DateTime(2024, 6, 30)"
        Placeholder="Select dates">
    </SfDateRangePicker>
</div>

---

日期时间选择器

本指南全面介绍 DateTimePicker 组件的实现与自定义。DateTimePicker 支持多种格式、掩码、全球化和丰富的自定义选项，让用户能够同时选择日期和时间值。

何时使用此技能

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

• 在 Blazor 应用程序中安装和设置 DateTimePicker 组件
• 实现日期和时间选择功能
• 使用自定义格式字符串设置日期/时间值的格式
• 应用输入掩码并验证用户输入
• 处理 DateTimePicker 事件（ValueChange、OnOpen、OnClose 等）
• 将组件绑定到数据模型
• 设置日期/时间的最小值和最大值限制
• 突出显示特殊日期或禁用指定日期
• 实现全球化（RTL、多种区域设置）
• 支持伊斯兰历或其他日历系统
• 自定义组件外观和样式
• 配置占位文本和输入验证
• 启用严格模式以验证输入
• 在日历中显示周数

文档

入门指南

📄 阅读： references/getting-started.md

• 安装和设置 NuGet 包
• 在 Blazor Server/Web App 中初始化基本组件
• 最简可运行示例
• 必需的导入和配置

日期和时间格式

📄 阅读： references/date-time-formatting.md

• 格式字符串模式和标准格式
• 自定义日期/时间格式配置
• 区域设置专用格式
• 解析和显示格式的处理

数据绑定和事件

📄 阅读： references/data-binding-and-events.md

• 日期/时间值的双向绑定
• ValueChange 事件（完成日期/时间选择）
• OnOpen/OnClose 事件（弹出窗口生命周期）
• Selected 事件（日历中的日期选择）
• OnItemRender 事件（自定义时间列表项渲染）
• Focus/Blur 事件
• Cleared 事件（点击清除按钮）
• Created/Destroyed 生命周期事件
• Navigated 事件（日历视图导航）
• OnRenderDayCell 事件（自定义日期单元格渲染）
• 使用 DateTimePickerEvents 子组件
• 状态管理和数据流模式

日期范围和特殊日期

📄 阅读： references/date-ranges-and-special-dates.md

• 设置日期最小值和最大值限制
• 限制日期范围选择
• 突出显示特殊日期
• 禁用指定日期或日期范围
• 周数配置

掩码和输入验证

📄 阅读： references/masking-and-input-validation.md

• 日期/时间输入的输入掩码模式
• 占位文本配置
• 输入验证规则
• 严格模式约束和输入行为
• 验证边缘情况

自定义和样式

📄 阅读： references/customization-and-styling.md

• CSS 自定义和类覆盖
• 主题集成（Bootstrap、Material、Fluent、Tailwind）
• 组件外观和样式选项
• 自定义 CSS 属性和样式模式
• 视觉自定义示例

全球化和无障碍功能

📄 阅读： references/globalization-and-accessibility.md

• 全球化支持（RTL、多种区域设置）
• 伊斯兰历的实现和配置
• 无障碍功能（符合 WCAG 标准、键盘导航）
• ARIA 属性和屏幕阅读器支持
• 国际化最佳实践

快速入门

以下是一个最简可运行示例，帮助你开始使用 DateTimePicker：

@page "/datetimepicker-demo"
@using Syncfusion.Blazor.Calendars

<div>
    <label>Select Date and Time:</label>
    <SfDateTimePicker TValue="DateTime?" 
                      @bind-Value="@selectedDateTime"
                      Placeholder="Choose date and time">
        <DateTimePickerEvents TValue="DateTime?" ValueChange="@OnValueChanged"></DateTimePickerEvents>
    </SfDateTimePicker>
    
    @if (selectedDateTime.HasValue)
    {
        <p>Selected: @selectedDateTime.Value.ToString("g")</p>
    }
</div>

@code {
    private DateTime? selectedDateTime;
    
    private void OnValueChanged(ChangedEventArgs<DateTime?> args)
    {
        selectedDateTime = args.Value;
        Console.WriteLine($"Date changed to: {selectedDateTime}");
    }
}

常见模式

模式 1：使用日期范围限制

<SfDateTimePicker TValue="DateTime?" 
                  Min="@minDate" 
                  Max="@maxDate"
                  Value="selectedDateTime">
</SfDateTimePicker>

@code {
    private DateTime minDate = new DateTime(2024, 1, 1);
    private DateTime maxDate = new DateTime(2024, 12, 31);
    private DateTime? selectedDateTime;
}

模式 2：自定义格式

<SfDateTimePicker TValue="DateTime?" 
                  Format="dd/MM/yyyy HH:mm"
                  Value="selectedDateTime">
</SfDateTimePicker>

模式 3：使用输入掩码

<SfDateTimePicker TValue="DateTime?" 
                  EnableMask="true"
                  Format="dd/MM/yyyy HH:mm"
                  Value="selectedDateTime">
    <DateTimePickerMaskPlaceholder Day="dd" Month="MM" Year="yyyy" Hour="HH" Minute="mm"></DateTimePickerMaskPlaceholder>
</SfDateTimePicker>

模式 4：使用数据绑定

<SfDateTimePicker TValue="DateTime?" 
                  @bind-Value="model.CreatedDate">
    <DateTimePickerEvents TValue="DateTime?" ValueChange="@OnDateChanged"></DateTimePickerEvents>
</SfDateTimePicker>

关键属性

属性	类型	用途
Value	TValue	获取或设置选定的日期时间值
@bind-Value	TValue	双向数据绑定
Format	string	显示格式（例如，“dd/MM/yyyy HH:mm”）
TimeFormat	string	仅用于时间部分的格式（例如，“HH:mm”）
Placeholder	string	输入字段的占位文本
Min	DateTime	可选日期的最小值（日期部分）
Max	DateTime	可选日期的最大值（日期部分）
MinTime	DateTime	可选时间的最小值
MaxTime	DateTime	可选时间的最大值
Step	int	时间间隔步长（分钟，默认值：30）
ScrollTo	DateTime?	时间列表中的初始滚动位置
AllowEdit	bool	允许手动输入文本
StrictMode	bool	强制严格输入验证
EnableMask	bool	启用日期/时间输入掩码
OpenOnFocus	bool	输入框获得焦点时打开弹出窗口
FloatLabelType	FloatLabelType	浮动标签行为
Enabled	bool	启用/禁用组件
Readonly	bool	将组件设为只读
ShowClearButton	bool	显示清除按钮
ShowTodayButton	bool	在日历中显示“今天”按钮
WeekNumber	bool	显示周数
FirstDayOfWeek	int	一周的第一天（0=星期日，1=星期一）
Start	CalendarView	初始日历视图
Depth	CalendarView	最深视图级别
ZIndex	int	弹出窗口的 Z-index
Width	string	组件宽度
CssClass	string	自定义 CSS 类

---

TimePicker

用于实现和自定义 TimePicker 组件的综合指南。本指南涵盖安装、配置、数据绑定、事件、样式、无障碍功能、国际化，以及输入掩码等高级功能。

何时使用本指南

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

• 在 Blazor 应用程序中安装和设置 TimePicker 组件
• 创建基础和高级 TimePicker 实现
• 配置时间格式（12 小时制、24 小时制、自定义格式）
• 设置数据绑定（单向、双向、动态）
• 处理 TimePicker 事件（ValueChange、OnOpen、OnClose、Blur、Focus 等）
• 使用 CSS 自定义外观和样式
• 实现输入掩码和验证
• 配置无障碍功能（键盘导航、ARIA 属性、屏幕阅读器）
• 添加全球化支持（本地化、阿拉伯语/希伯来语的 RTL 支持）
• 设置时间间隔和步长值
• 在移动设备上实现全屏模式

组件概述

SfTimePicker 是用于选择时间的 Blazor 输入组件。它提供：

• 带可滚动时间列表的弹出式时间选择器界面
• 可配置的时间格式和间隔
• 支持双向数据绑定
• 内置验证和掩码
• 完全符合无障碍标准（WCAG 2.2、Section 508）
• 面向国际用户的 RTL 支持
• 适配移动设备，支持全屏模式
• 键盘导航快捷键

快速入门示例

基础 TimePicker

@using Syncfusion.Blazor.Calendars

<SfTimePicker TValue="DateTime?" Placeholder="Select a time"></SfTimePicker>

带值绑定的 TimePicker

@using Syncfusion.Blazor.Calendars

<p>Selected Time: @SelectedTime</p>

<SfTimePicker TValue="DateTime?" @bind-Value="@SelectedTime"></SfTimePicker>

@code {
    public DateTime? SelectedTime { get; set; } = DateTime.Now;
}

带格式和步长的 TimePicker

@using Syncfusion.Blazor.Calendars

<SfTimePicker TValue="DateTime?" 
    Value="@TimeValue" 
    Format="HH:mm"
    Step=60
    Placeholder="Select time (24-hour)">
</SfTimePicker>

@code {
    public DateTime TimeValue { get; set; } = DateTime.Now;
}

关键属性参考

关键属性

属性	类型	描述	默认值
Value	TValue	当前时间值（单向绑定）	null
@bind-Value	TValue	双向数据绑定	-
Placeholder	string	输入框中的占位文本	"Select a time"
Format	string	显示格式字符串（HH:mm、hh:mm tt）	基于区域性
InputFormats	string[]	可接受的输入格式模式	基于区域性
Step	int	时间间隔（分钟）	30
ScrollTo	DateTime?	时间列表中的初始滚动位置	null
Min	DateTime	可选择的最早时间	00:00
Max	DateTime	可选择的最晚时间	23:59
AllowEdit	bool	允许手动输入文本	true
StrictMode	bool	强制严格输入验证	false
EnableMask	bool	启用输入掩码	false
OpenOnFocus	bool	输入框获得焦点时打开弹出窗口	false
FloatLabelType	FloatLabelType	浮动标签行为	Never
Enabled	bool	启用/禁用组件	true
Readonly	bool	只读模式	false
ShowClearButton	bool	显示清除按钮	false
EnableRtl	bool	启用从右到左（RTL）方向	false
FullScreen	bool	移动设备上的全屏模式	false
ZIndex	int	弹出窗口的 Z-index	1000
Width	string	组件宽度	"100%"
CssClass	string	自定义 CSS 类	null
TabIndex	int	Tab 顺序索引	0

文档导航

入门指南

📄 阅读： references/getting-started.md

• 安装 NuGet 包
• 导入命名空间
• 在 Program.cs 中注册服务
• 设置并引入主题
• 基本组件实现
• Step 属性和时间间隔

时间格式

📄 阅读： references/time-formats.md

• 自定义显示格式
• 配置输入格式
• 标准与自定义格式字符串
• 基于区域性的默认格式
• 12 小时和 24 小时格式示例
• 何时使用各格式选项

数据绑定

📄 阅读： references/data-binding.md

• 单向绑定模式
• 使用 @bind-Value 进行双向绑定
• 动态更新值
• DateTime 和 DateTime? 类型处理
• 集成值更改事件

事件和处理程序

📄 阅读： references/events-and-handlers.md

• ValueChange 事件（EventCallback<ChangeEventArgs>）
• OnOpen/OnClose 弹出窗口事件
• Selected 事件（列表中的时间选择）
• OnItemRender 事件（自定义时间列表项渲染）
• Focus/Blur 输入事件
• Cleared 事件（点击清除按钮）
• Created/Destroyed 生命周期事件
• 使用 TimePickerEvents 子组件
• 事件处理程序实现模式

样式和外观

📄 阅读： references/styling-and-appearance.md

• 用于自定义的 CSS 类
• 容器元素样式
• 图标元素样式
• 弹出窗口和列表项样式
• 移动设备全屏模式
• 主题集成（Bootstrap、Material、Fluent）

无障碍功能和全球化

📄 阅读： references/accessibility-and-globalization.md

• 符合 WCAG 2.2 和相关标准
• 键盘导航快捷键（方向键、Enter、Esc）
• WAI-ARIA 属性和角色
• RTL（从右到左）支持
• 本地化和区域性配置
• 屏幕阅读器支持

掩码支持

📄 阅读： references/mask-support.md

• 用于输入掩码的 EnableMask 属性
• TimePickerMaskPlaceholder 指令
• 自定义占位字符（Hour、Minute、Second）
• 特定格式的掩码模式
• 使用掩码进行输入验证

常见模式

模式 1：简单时间选择

当用户需要基本的时间选择器且没有复杂要求时：

<SfTimePicker TValue="DateTime?" 
    @bind-Value="@AppointmentTime"
    Placeholder="Select appointment time">
</SfTimePicker>

模式 2：仅限营业时间

当时间选择应限制在特定时段内时：

<SfTimePicker TValue="DateTime?" 
    @bind-Value="@BusinessTime"
    Min="@new DateTime(2026, 1, 1, 09, 0, 0)"
    Max="@new DateTime(2026, 1, 1, 17, 0, 0)"
    Step=30
    Format="HH:mm">
</SfTimePicker>

@code {
    public DateTime? BusinessTime { get; set; }
}

模式 3：12 小时制与 AM/PM

当以 12 小时制显示时间时：

<SfTimePicker TValue="DateTime?" 
    @bind-Value="@UserTime"
    Format="hh:mm tt"
    Placeholder="Select time (12-hour)">
</SfTimePicker>

@code {
    public DateTime? UserTime { get; set; } = DateTime.Now;
}

模式 4：处理事件

当需要跟踪时间选择的变化时：

<SfTimePicker TValue="DateTime?">
    <TimePickerEvents TValue="DateTime?" ValueChange="@OnTimeChanged"></TimePickerEvents>
</SfTimePicker>

@code {
    private void OnTimeChanged(ChangeEventArgs<DateTime?> args)
    {
        Console.WriteLine($"Time selected: {args.Value}");
    }
}

常见用例

1. 预约：选择时间来安排预约，并验证是否在营业时间内
2. 时间跟踪：记录工时表或活动日志的开始/结束时间
3. 班次管理：在 HR/劳动力应用程序中选择班次时间
4. 旅行预订：选择航班、列车的出发/到达时间
5. 配送时段：在电商平台中设置首选配送时间段
6. 广播排期：在媒体应用程序中选择广播时间
7. 会议安排：为支持时区的虚拟会议选择时间
8. 健身房预订：在健身管理应用中选择课程时间

先决条件

• Blazor WebAssembly 或 Blazor Server 项目（.NET 7 或更高版本）
• NuGet 包：Syncfusion.Blazor.Calendars
• NuGet 包：Syncfusion.Blazor.Themes
• 在 Program.cs 中注册 Syncfusion 服务

---

准备好实现 Calendar 组件了吗？ 从上面的入门指南开始进行设置，然后根据具体需求查看其他参考资料。

---

后续步骤： 从所选组件的入门指南开始，然后根据具体任务查看其他参考资料。

如需详细的实现模式、完整代码示例和故障排除指南，请根据具体需求阅读相应的参考文件。