syncfusion-blazor-calendars
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion Blazor Calendars
实现 Syncfusion Blazor 日历组件
Calendar
Calendar
The Calendar component is a lightweight, feature-rich date selection component that provides flexible date picking, multiple views (month/year/decade), date range constraints, localization, and accessibility compliance. Use this skill whenever you need to implement date selection, calendar display, or date-based UI interactions.
Calendar 组件是一款轻量、功能丰富的日期选择组件,提供灵活的日期拾取、多视图(月/年/十年)、日期范围约束、本地化和无障碍合规支持。当你需要实现日期选择、日历展示或基于日期的UI交互时可使用本技能。
When to Use This Skill
何时使用本技能
Use this skill when:
- Building date pickers, calendar widgets, or date selection interfaces
- Adding date range constraints (Min/Max dates)
- Implementing multi-month or drill-down date selection (Year/Decade views)
- Handling date value changes and events
- Styling calendars or customizing appearance
- Supporting international date formats and RTL layouts
- Creating accessible calendar interfaces with keyboard navigation
Related components:
- DatePicker (date input with calendar dropdown)
- DateRangePicker (date range selection)
- DateTimePicker (date + time selection)
- Scheduler (complex date-based scheduling)
以下场景可使用本技能:
- 构建日期选择器、日历组件或日期选择界面
- 添加日期范围约束(最小/最大日期)
- 实现多月或层级下钻日期选择(年/十年视图)
- 处理日期值变更和相关事件
- 日历样式定制或外观自定义
- 支持国际化日期格式和RTL布局
- 创建支持键盘导航的无障碍日历界面
相关组件:
- DatePicker(带日历下拉框的日期输入组件)
- DateRangePicker(日期范围选择组件)
- DateTimePicker(日期+时间选择组件)
- Scheduler(复杂的基于日期的日程调度组件)
Component Overview
组件概览
| Feature | Details |
|---|---|
| Views | Month (default), Year, Decade - hierarchical drill-down navigation |
| Selection | Single date, date ranges (Min/Max), multi-select |
| Data Types | |
| Binding | One-way, two-way ( |
| Events | |
| Localization | Multi-language, RTL support, locale customization |
| Accessibility | WCAG 2.2 AA, keyboard navigation, screen reader support |
| Styling | CSS customization, theme integration, special date highlights |
| 特性 | 详情 |
|---|---|
| 视图 | 月(默认)、年、十年 - 层级下钻导航 |
| 选择模式 | 单选日期、日期范围(最小/最大)、多选 |
| 支持数据类型 | |
| 绑定方式 | 单向、双向( |
| 事件 | |
| 本地化 | 多语言、RTL支持、区域自定义 |
| 无障碍 | WCAG 2.2 AA 合规、键盘导航、屏幕阅读器支持 |
| 样式 | CSS自定义、主题集成、特殊日期高亮 |
Documentation & Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Installation & NuGet packages
- Web & Server app setup
- Blazor namespaces & service registration
- Basic calendar implementation
- Min/Max date constraints
📄 阅读: references/getting-started.md
- 安装与NuGet包配置
- Web与Server应用搭建
- Blazor命名空间与服务注册
- 基础日历实现
- 最小/最大日期约束
Calendar Views & Navigation
日历视图与导航
📄 Read: references/calendar-views.md
- Month, Year, Decade views
- Start & Depth properties
- View restrictions & drill-down navigation
- Restricting date selection depth
📄 阅读: references/calendar-views.md
- 月、年、十年视图
- 起始与深度属性配置
- 视图限制与下钻导航
- 日期选择深度限制
Date Selection & Data Binding
日期选择与数据绑定
📄 Read: references/date-selection-binding.md
- Value property & date binding
- One-way vs two-way binding ()
@bind-Value - DateOnly support (.NET 6+)
- Dynamic value changes
- Date range constraints
📄 阅读: references/date-selection-binding.md
- Value属性与日期绑定
- 单向绑定 vs 双向绑定()
@bind-Value - DateOnly支持(.NET 6+)
- 动态值变更
- 日期范围约束
Events & Interactions
事件与交互
📄 Read: references/events-handling.md
- ValueChange event (date selection)
- Selected/DeSelected events (multi-selection)
- OnRenderDayCell event (custom rendering)
- Created & Destroyed lifecycle events
- Navigated event (view changes)
- Event args & reactive patterns
- Using CalendarEvents child component
📄 阅读: references/events-handling.md
- ValueChange事件(日期选择)
- Selected/DeSelected事件(多选)
- OnRenderDayCell事件(自定义渲染)
- Created与Destroyed生命周期事件
- Navigated事件(视图变更)
- 事件参数与响应式模式
- 使用CalendarEvents子组件
Styling & Customization
样式与自定义
📄 Read: references/styling-appearance.md
- CSS customization patterns
- Background colors, borders, hover states
- Day cell styling
- Header & title customization
- Today button & selected date styling
- Special date highlighting
📄 阅读: references/styling-appearance.md
- CSS自定义模式
- 背景色、边框、悬停状态
- 日期单元格样式
- 头部与标题自定义
- 今天按钮与选中日期样式
- 特殊日期高亮
Localization & Globalization
本地化与全球化
📄 Read: references/localization-globalization.md
- Locale support & language files
- Right-to-Left (RTL) layouts
- Islamic calendar & custom calendars
- Week customization (first day of week)
- Date format localization
📄 阅读: references/localization-globalization.md
- 区域支持与语言包
- 从右到左(RTL)布局
- 伊斯兰历与自定义日历
- 周数自定义(一周起始日)
- 日期格式本地化
Accessibility & Keyboard Navigation
无障碍与键盘导航
📄 Read: references/accessibility.md
- WCAG 2.2 AA compliance
- Screen reader support (WAI-ARIA)
- Keyboard navigation shortcuts
- Focus management & ARIA attributes
📄 阅读: references/accessibility.md
- WCAG 2.2 AA 合规
- 屏幕阅读器支持(WAI-ARIA)
- 键盘导航快捷键
- 焦点管理与ARIA属性
Advanced Features & Patterns
高级特性与模式
📄 Read: references/advanced-features.md
- Show/hide other month dates
- Custom cell rendering patterns
- Multiple date selection
- Week number display
- Performance optimization
- Common integration patterns
📄 阅读: references/advanced-features.md
- 显示/隐藏其他月份日期
- 自定义单元格渲染模式
- 多日期选择
- 周数展示
- 性能优化
- 常见集成模式
Quick Start Example
快速入门示例
razor
@using Syncfusion.Blazor.Calendars
<!-- Basic Calendar -->
<SfCalendar TValue="DateTime?" Value="@SelectedDate"></SfCalendar>
<!-- Calendar with Date Range -->
<SfCalendar TValue="DateTime?"
Value="@SelectedDate"
Min="@MinDate"
Max="@MaxDate">
</SfCalendar>
<!-- Calendar with Value Change Event -->
<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate">
<CalendarEvents TValue="DateTime?" ValueChange="@OnDateChanged"></CalendarEvents>
</SfCalendar>
<!-- Multi-Selection Calendar -->
<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
}
}razor
@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;
// 处理日期变更逻辑
}
private void OnDateSelected(SelectedEventArgs<DateTime?> args)
{
// 处理日期被选中逻辑
}
private void OnDateDeselected(DeSelectedEventArgs<DateTime?> args)
{
// 处理日期取消选中逻辑
}
}Common Patterns
常用模式
Pattern 1: Date Range Selection
模式1:日期范围选择
Define Min and Max boundaries to constrain user selection:
razor
<SfCalendar TValue="DateTime?" Value="@SelectedDate"
Min="@MinDate" Max="@MaxDate"></SfCalendar>定义最小和最大边界来约束用户选择:
razor
<SfCalendar TValue="DateTime?" Value="@SelectedDate"
Min="@MinDate" Max="@MaxDate"></SfCalendar>Pattern 2: Two-Way Data Binding
模式2:双向数据绑定
Keep Calendar in sync with component state:
razor
<p>Selected: @SelectedDate</p>
<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate"></SfCalendar>让日历与组件状态保持同步:
razor
<p>选中日期: @SelectedDate</p>
<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate"></SfCalendar>Pattern 3: Custom Cell Rendering
模式3:自定义单元格渲染
Highlight or customize specific date cells during render:
razor
<SfCalendar TValue="DateTime?">
<CalendarEvents TValue="DateTime?" OnRenderDayCell="@CustomizeCell"></CalendarEvents>
</SfCalendar>在渲染阶段高亮或自定义指定日期单元格:
razor
<SfCalendar TValue="DateTime?">
<CalendarEvents TValue="DateTime?" OnRenderDayCell="@CustomizeCell"></CalendarEvents>
</SfCalendar>Pattern 4: View Restrictions
模式4:视图限制
Limit navigation to specific view levels (e.g., Year → Month only):
razor
<SfCalendar TValue="DateTime?"
Start="CalendarView.Year"
Depth="CalendarView.Month"></SfCalendar>限制导航到指定视图层级(例如仅支持年→月层级):
razor
<SfCalendar TValue="DateTime?"
Start="CalendarView.Year"
Depth="CalendarView.Month"></SfCalendar>Pattern 5: Localization
模式5:本地化
Render calendar in specific language/culture:
razor
<SfCalendar TValue="DateTime?" EnableRtl="false"></SfCalendar>按指定语言/文化渲染日历:
razor
<SfCalendar TValue="DateTime?" EnableRtl="false"></SfCalendar>Key Props & When to Use
核心属性及使用场景
| Property | Type | Purpose | Example |
|---|---|---|---|
| | Selected date (one-way binding) | |
| | Two-way data binding | |
| | Multiple selected dates (multi-select mode) | |
| | Two-way binding for multi-selection | |
| | Enable multiple date selection | |
| | Earliest selectable date (inclusive) | |
| | Latest selectable date (inclusive) | |
| | Initial view (Month/Year/Decade) | |
| | Deepest view level for drilling | |
| | Display "Today" button in footer | |
| | Calendar system (Gregorian/Islamic) | |
| | Week numbering calculation rule | |
| | Day header display format | |
| | Right-to-left layout | |
| | Display week numbers in calendar | |
| | First day (0=Sunday, 1=Monday) | |
| | Custom CSS class for styling | |
| | Enable/disable component | |
| 属性 | 类型 | 用途 | 示例 |
|---|---|---|---|
| | 选中日期(单向绑定) | |
| | 双向数据绑定 | |
| | 多个选中日期(多选模式) | |
| | 多选模式的双向绑定 | |
| | 开启多日期选择 | |
| | 最早可选择日期(包含) | |
| | 最晚可选择日期(包含) | |
| | 初始视图(月/年/十年) | |
| | 允许下钻的最深视图层级 | |
| | 在页脚显示「今天」按钮 | |
| | 日历系统(公历/伊斯兰历) | |
| | 周数计算规则 | |
| | 日期头部展示格式 | |
| | 从右到左布局 | |
| | 在日历中显示周数 | |
| | 一周起始日(0=周日, 1=周一) | |
| | 用于自定义样式的CSS类 | |
| | 启用/禁用组件 | |
Common Use Cases
常见使用场景
- Appointment Booking: Calendar with date range (available days) + event handling
- Date Filter: Multi-view calendar for drilling down to specific date
- Deadline Selection: Min/Max constraints to valid date ranges
- Report Viewing: Year/Month view for period selection
- International App: RTL + locale support for multi-language UIs
- Accessible Forms: Keyboard-navigable date input with screen reader support
- 预约预订:带日期范围(可用日期)+事件处理的日历
- 日期筛选:支持下钻到指定日期的多视图日历
- 截止日期选择:通过最小/最大约束限制有效日期范围
- 报表查看:用于时段选择的年/月视图
- 国际化应用:支持RTL+区域适配的多语言UI
- 无障碍表单:支持键盘导航、屏幕阅读器的日期输入组件
Working with Events
事件处理说明
All calendar components use child event components to declare event handlers. This approach provides type safety and clear separation of concerns.
所有日历组件都使用子事件组件来声明事件处理函数,这种方式提供了类型安全和清晰的关注点分离。
Event Child Components
事件子组件对应关系
- Calendar: Use child component
<CalendarEvents> - DatePicker: Use child component
<DatePickerEvents> - DateRangePicker: Use child component
<DateRangePickerEvents> - DateTimePicker: Use child component
<DateTimePickerEvents> - TimePicker: Use child component
<TimePickerEvents>
- Calendar:使用 子组件
<CalendarEvents> - DatePicker:使用 子组件
<DatePickerEvents> - DateRangePicker:使用 子组件
<DateRangePickerEvents> - DateTimePicker:使用 子组件
<DateTimePickerEvents> - TimePicker:使用 子组件
<TimePickerEvents>
Example: Calendar with Events
示例:带事件的日历
razor
<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}");
}
}razor
<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($"日期变更为: {args.Value}");
}
private void OnDayCellRender(RenderDayCellEventArgs args)
{
// 禁用周末
if (args.Date.DayOfWeek == DayOfWeek.Saturday || args.Date.DayOfWeek == DayOfWeek.Sunday)
{
args.IsDisabled = true;
}
}
private void OnNavigated(NavigatedEventArgs args)
{
Console.WriteLine($"导航到视图: {args.View}");
}
}Common Event Patterns
常用事件模式
Pattern 1: Value Change with Validation
razor
<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;
}
}
}Pattern 2: Popup Lifecycle Management
razor
<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");
}
}Pattern 3: Custom Cell Rendering
razor
<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";
}
}
}模式1:带校验的值变更
razor
<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))
{
// 展示错误:日期超过未来6个月
OrderDate = DateTime.Now;
}
else
{
OrderDate = args.Value;
}
}
}模式2:弹窗生命周期管理
razor
<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("弹窗已打开");
// 可取消打开:args.Cancel = true;
}
private void HandlePopupClose(PopupObjectArgs args)
{
Console.WriteLine("弹窗已关闭");
}
}模式3:自定义单元格渲染
razor
<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)
{
// 高亮活动日期
if (EventDates.Any(d => d.Date == args.Date.Date))
{
args.CellData.ClassList = "e-special-date";
}
}
}Event Argument Types Reference
事件参数类型参考
IMPORTANT: Different components use different event argument types for the event:
ValueChange| Component | ValueChange Event Argument Type | Notes |
|---|---|---|
| Calendar | | For single and multi-date selection |
| DatePicker | | Includes |
| DateTimePicker | | Same as DatePicker |
| TimePicker | | Note: Different class name (no 'd') |
| DateRangePicker | | Includes |
Key Differences:
- (with 'd') - Used by Calendar, DatePicker, DateTimePicker
ChangedEventArgs<TValue>- Properties: ,
Value(for multi-selection),Values,IsInteracted,Event,ElementName
- Properties:
- (no 'd') - Used by TimePicker only
ChangeEventArgs<TValue>- Properties: ,
Value,Text,IsInteracted,EventElement
- Properties:
- - Used by DateRangePicker only
RangePickerEventArgs<TValue>- Properties: ,
StartDate,EndDate,Text,Value,IsInteracted,EventElement
- Properties:
重要提示: 不同组件的事件使用不同的事件参数类型:
ValueChange| 组件 | ValueChange事件参数类型 | 说明 |
|---|---|---|
| Calendar | | 适用于单选和多选日期 |
| DatePicker | | 包含 |
| DateTimePicker | | 与DatePicker一致 |
| TimePicker | | 注意:类名不带'd' |
| DateRangePicker | | 包含 |
核心差异:
- (带'd')- 用于Calendar、DatePicker、DateTimePicker
ChangedEventArgs<TValue>- 属性:、
Value(多选模式)、Values、IsInteracted、Event、ElementName
- 属性:
- (不带'd')- 仅用于TimePicker
ChangeEventArgs<TValue>- 属性:、
Value、Text、IsInteracted、EventElement
- 属性:
- - 仅用于DateRangePicker
RangePickerEventArgs<TValue>- 属性:、
StartDate、EndDate、Text、Value、IsInteracted、EventElement
- 属性:
DatePicker
DatePicker
A comprehensive skill for implementing and customizing the DatePicker component. This skill helps you install, configure, and integrate DatePicker across Blazor Server, Blazor WebAssembly, and Blazor Web App projects.
本指南用于实现和自定义DatePicker组件,可帮助你在Blazor Server、Blazor WebAssembly和Blazor Web App项目中安装、配置和集成DatePicker组件。
When to Use This Skill
何时使用本技能
Use this skill when you need to:
- Install and set up Syncfusion DatePicker in any Blazor project type
- Implement basic date selection with input validation
- Configure one-way and two-way data binding
- Set custom date formats and input formats
- Apply date range constraints (min/max dates)
- Highlight or disable special dates
- Handle DatePicker events (ValueChange, OnClose, Focus, Blur)
- Globalize and localize the component (different languages/calendars)
- Support Islamic Calendar or other calendar systems
- Use DateOnly (.NET 6+) with DatePicker
- Style and customize appearance (readonly, disabled states, themes)
- Implement keyboard navigation and accessibility
- Troubleshoot data binding, formatting, or event issues
- Optimize performance in Blazor Server vs WebAssembly
- Integrate date selection with forms and APIs
以下场景可使用本技能:
- 在任意Blazor项目类型中安装和配置Syncfusion DatePicker
- 实现带输入校验的基础日期选择功能
- 配置单向和双向数据绑定
- 设置自定义日期格式和输入格式
- 应用日期范围约束(最小/最大日期)
- 高亮或禁用特殊日期
- 处理DatePicker事件(ValueChange、OnClose、Focus、Blur等)
- 组件全球化和本地化(不同语言/日历体系)
- 支持伊斯兰历或其他日历系统
- 在DatePicker中使用DateOnly(.NET 6+)类型
- 样式和外观自定义(只读、禁用状态、主题)
- 实现键盘导航和无障碍功能
- 排查数据绑定、格式化或事件相关问题
- 优化Blazor Server和WebAssembly场景下的性能
- 将日期选择功能与表单和API集成
Component Overview
组件概览
The DatePicker component provides an intuitive calendar UI for users to select single dates. It supports:
- Multiple Input Methods: Direct typing, calendar picker, or both
- Date Constraints: Min/max date ranges, disabled dates, special highlights
- Flexible Formatting: Custom display formats and input formats
- Global Support: Multiple languages, calendars (Gregorian, Islamic), RTL
- Accessibility: WCAG compliance, keyboard navigation, screen reader support
- Event System: Value changes, popup open/close, focus/blur events
- Theme Support: Bootstrap, Material, Fluent, Tailwind CSS
DatePicker组件为用户提供直观的日历UI来选择单个日期,支持:
- 多种输入方式:直接输入、日历选择、同时支持两种方式
- 日期约束:最小/最大日期范围、禁用日期、特殊高亮
- 灵活格式化:自定义展示格式和输入格式
- 全球化支持:多语言、多日历(公历、伊斯兰历)、RTL
- 无障碍:WCAG合规、键盘导航、屏幕阅读器支持
- 事件系统:值变更、弹窗打开/关闭、焦点/失焦事件
- 主题支持:Bootstrap、Material、Fluent、Tailwind CSS
Installation Quick Start
快速安装指南
1. Install NuGet Package
1. 安装NuGet包
bash
dotnet add package Syncfusion.Blazor.Calendars
dotnet add package Syncfusion.Blazor.Themesbash
dotnet add package Syncfusion.Blazor.Calendars
dotnet add package Syncfusion.Blazor.Themes2. Import in _Imports.razor
_Imports.razor2. 在_Imports.razor
中导入
_Imports.razorcsharp
@using Syncfusion.Blazor
@using Syncfusion.Blazor.Calendarscsharp
@using Syncfusion.Blazor
@using Syncfusion.Blazor.Calendars3. Register in Program.cs
Program.cs3. 在Program.cs
中注册服务
Program.cscsharp
builder.Services.AddSyncfusionBlazor();csharp
builder.Services.AddSyncfusionBlazor();4. Add Theme in App.razor
or Layout
App.razor4. 在App.razor
或布局文件中添加主题
App.razorhtml
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>html
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />
<script src="_content/Syncfusion.Blazor.Core/scripts/syncfusion-blazor.min.js"></script>5. Use in Component
5. 在组件中使用
razor
<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;
}
}razor
<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;
}
}Documentation Navigation Guide
文档导航指南
Choose a reference based on your task:
根据你的任务选择对应参考文档:
Getting Started
入门指南
📄 Read: references/getting-started.md
- Installation in Blazor Server, WebAssembly, and Web App
- NuGet package setup
- Theme configuration
- Service registration
- Basic DatePicker example
📄 阅读: references/getting-started.md
- 在Blazor Server、WebAssembly和Web App中安装
- NuGet包配置
- 主题配置
- 服务注册
- 基础DatePicker示例
Data Binding
数据绑定
📄 Read: references/data-binding.md
- One-way binding with property
Value - Two-way binding with
@bind-Value - Dynamic value updates and null handling
- Binding to DateTime vs DateTime?
📄 阅读: references/data-binding.md
- 基于属性的单向绑定
Value - 基于的双向绑定
@bind-Value - 动态值更新和空值处理
- 绑定到DateTime与DateTime?类型
Date Formats & Input
日期格式与输入
📄 Read: references/date-formats-and-input.md
- Display format customization (d/M/yyyy, dd/MM/yyyy, etc.)
- Input format patterns
- Placeholder text configuration
- Format parsing and validation
- Custom format examples
📄 阅读: references/date-formats-and-input.md
- 展示格式自定义(d/M/yyyy、dd/MM/yyyy等)
- 输入格式规则
- 占位符文本配置
- 格式解析与校验
- 自定义格式示例
Date Range & Constraints
日期范围与约束
📄 Read: references/date-range-and-constraints.md
- Min/Max date restrictions
- Disabled specific dates
- Special date highlighting
- Date validation logic
- Preventing invalid selections
📄 阅读: references/date-range-and-constraints.md
- 最小/最大日期限制
- 禁用指定日期
- 特殊日期高亮
- 日期校验逻辑
- 阻止无效选择
Events & Interaction
事件与交互
📄 Read: references/events.md
- ValueChange event handling
- OnOpen/OnClose events (popup lifecycle)
- Selected event (date selection in calendar)
- Focus/Blur events
- Cleared event (clear button clicked)
- Created/Destroyed lifecycle events
- Navigated event (calendar view navigation)
- OnRenderDayCell event (custom day cell rendering)
- Using DatePickerEvents child component
📄 阅读: references/events.md
- ValueChange事件处理
- OnOpen/OnClose事件(弹窗生命周期)
- Selected事件(日历中选中日期)
- Focus/Blur事件
- Cleared事件(点击清除按钮)
- Created/Destroyed生命周期事件
- Navigated事件(日历视图导航)
- OnRenderDayCell事件(自定义日期单元格渲染)
- 使用DatePickerEvents子组件
Advanced Features
高级特性
📄 Read: references/advanced-features.md
- Islamic Calendar support
- DateOnly (.NET 6+) support
- Globalization and localization
- Week number display
- Different view modes
- Mask support and input masking
📄 阅读: references/advanced-features.md
- 伊斯兰历支持
- DateOnly(.NET 6+)支持
- 全球化与本地化
- 周数展示
- 不同视图模式
- 掩码支持与输入掩码
Styling & Appearance
样式与外观
📄 Read: references/styling-and-appearance.md
- CSS customization and themes
- Readonly state styling
- Disabled state styling
- RTL (right-to-left) support
- Theme switching (Bootstrap, Material, Fluent, Tailwind)
- Custom styling examples
📄 阅读: references/styling-and-appearance.md
- CSS自定义与主题
- 只读状态样式
- 禁用状态样式
- RTL(从右到左)支持
- 主题切换(Bootstrap、Material、Fluent、Tailwind)
- 自定义样式示例
Accessibility
无障碍
📄 Read: references/accessibility.md
- WCAG 2.1 compliance
- Keyboard navigation (arrow keys, Enter, Escape)
- ARIA attributes and roles
- Screen reader support
- Color contrast and visual indicators
- Focus management
📄 阅读: references/accessibility.md
- WCAG 2.1合规
- 键盘导航(方向键、Enter、Escape)
- ARIA属性与角色
- 屏幕阅读器支持
- 色彩对比度与视觉提示
- 焦点管理
Server vs WebAssembly
Server与WebAssembly差异
📄 Read: references/server-vs-webassembly.md
- Blazor Server vs WebAssembly differences
- Blazor Web App (.NET 8+) setup
- Render modes (InteractiveServer, InteractiveWebAssembly)
- Performance considerations
- Event interactivity
📄 阅读: references/server-vs-webassembly.md
- Blazor Server与WebAssembly差异
- Blazor Web App(.NET 8+)配置
- 渲染模式(InteractiveServer、InteractiveWebAssembly)
- 性能注意事项
- 事件交互性
Troubleshooting
问题排查
📄 Read: references/troubleshooting.md
- Data binding issues
- Date format problems
- Event handling problems
- Styling and layout issues
- Performance optimization
- Common error messages and solutions
📄 阅读: references/troubleshooting.md
- 数据绑定问题
- 日期格式问题
- 事件处理问题
- 样式与布局问题
- 性能优化
- 常见错误信息与解决方案
Common Patterns
常用模式
Pattern 1: Basic Date Selection
模式1:基础日期选择
razor
<SfDatePicker TValue="DateTime?" Value="@selectedDate"
Placeholder="Select a date"></SfDatePicker>Use when: User needs a simple, standard date picker for form input.
razor
<SfDatePicker TValue="DateTime?" Value="@selectedDate"
Placeholder="选择日期"></SfDatePicker>适用场景:用户需要简单标准的日期选择器用于表单输入。
Pattern 2: Date Range with Constraints
模式2:带约束的日期范围
razor
<SfDatePicker TValue="DateTime?" Value="@selectedDate"
Min="@minDate" Max="@maxDate"></SfDatePicker>Use when: Date must fall within a specific range (e.g., future dates only, event dates).
razor
<SfDatePicker TValue="DateTime?" Value="@selectedDate"
Min="@minDate" Max="@maxDate"></SfDatePicker>适用场景:日期必须落在指定范围内(例如仅可选未来日期、活动日期)。
Pattern 3: Two-Way Binding
模式3:双向绑定
razor
<SfDatePicker TValue="DateTime?" @bind-Value="@formData.BirthDate"></SfDatePicker>Use when: DatePicker must automatically update parent component state or form data.
razor
<SfDatePicker TValue="DateTime?" @bind-Value="@formData.BirthDate"></SfDatePicker>适用场景:DatePicker需要自动同步父组件状态或表单数据。
Pattern 4: Event-Driven Logic
模式4:事件驱动逻辑
razor
<SfDatePicker TValue="DateTime?">
<DatePickerEvents TValue="DateTime?" ValueChange="@OnDateSelected"></DatePickerEvents>
</SfDatePicker>
@code {
void OnDateSelected(ChangedEventArgs<DateTime?> args)
{
// Trigger calculations, API calls, or validation
}
}Use when: Selection should trigger workflows, calculations, or dependent updates.
razor
<SfDatePicker TValue="DateTime?">
<DatePickerEvents TValue="DateTime?" ValueChange="@OnDateSelected"></DatePickerEvents>
</SfDatePicker>
@code {
void OnDateSelected(ChangedEventArgs<DateTime?> args)
{
// 触发计算、API调用或校验
}
}适用场景:选择日期后需要触发工作流、计算或关联更新。
Pattern 5: Formatted Display with Custom Input
模式5:带自定义输入的格式化展示
razor
<SfDatePicker TValue="DateTime?" Value="@selectedDate"
Format="dd/MM/yyyy" Placeholder="DD/MM/YYYY"></SfDatePicker>Use when: Date display must match regional or business requirements.
razor
<SfDatePicker TValue="DateTime?" Value="@selectedDate"
Format="dd/MM/yyyy" Placeholder="DD/MM/YYYY"></SfDatePicker>适用场景:日期展示需要符合区域或业务要求。
Key Properties
核心属性
| Property | Type | Purpose |
|---|---|---|
| | The selected date (one-way binding) |
| | Two-way data binding |
| | Earliest selectable date |
| | Latest selectable date |
| | Display format pattern (e.g., "dd/MM/yyyy") |
| | Input placeholder text |
| | Allow manual text input editing |
| | Restrict to valid dates only |
| | Enable input masking for date entry |
| | Open calendar popup when input is focused |
| | Float label behavior (Auto/Always/Never) |
| | Array of acceptable input formats |
| | Enable/disable component |
| | Read-only mode (no user input) |
| | Show clear button to reset value |
| | Display week numbers in calendar |
| | Initial calendar view (Month/Year/Decade) |
| | Deepest view level allowed |
| | Z-index for popup positioning |
| | Component width (e.g., "300px") |
| | Custom CSS class for styling |
| 属性 | 类型 | 用途 |
|---|---|---|
| | 选中日期(单向绑定) |
| | 双向数据绑定 |
| | 最早可选择日期 |
| | 最晚可选择日期 |
| | 展示格式规则(例如"dd/MM/yyyy") |
| | 输入框占位文本 |
| | 允许手动输入文本 |
| | 仅允许输入有效日期 |
| | 开启日期输入掩码 |
| | 输入框获得焦点时打开日历弹窗 |
| | 浮动标签行为(自动/始终显示/从不显示) |
| | 可接受的输入格式数组 |
| | 启用/禁用组件 |
| | 只读模式(禁止用户输入) |
| | 显示重置值的清除按钮 |
| | 在日历中显示周数 |
| | 初始日历视图(月/年/十年) |
| | 允许的最深视图层级 |
| | 弹窗定位的Z轴层级 |
| | 组件宽度(例如"300px") |
| | 用于自定义样式的CSS类 |
Performance Tips
性能优化建议
- Use DateTime? (nullable) for optional date fields—avoids default date confusion
- Lazy-load DatePicker in modals or expandable sections—reduces initial render cost
- Minimize format conversions in event handlers—cache formatted strings when possible
- Use InteractiveWebAssembly for date-heavy UIs—offloads processing to client
- Batch value updates in loops—avoid rapid re-renders with multiple ValueChange triggers
- 可选日期字段使用(可空类型),避免默认日期混淆
DateTime? - 在模态框或可展开区域中延迟加载DatePicker,降低初始渲染成本
- 尽量减少事件处理程序中的格式转换,必要时缓存格式化后的字符串
- 日期密集型UI使用InteractiveWebAssembly渲染模式,将计算转移到客户端
- 循环中批量更新值,避免频繁触发ValueChange导致重渲染
DateRangePicker
DateRangePicker
A comprehensive skill for implementing and customizing the DateRangePicker component. This component enables users to select date ranges with calendar pickers, providing features for range constraints, customization, accessibility, and globalization.
本指南用于实现和自定义DateRangePicker组件,该组件支持用户通过日历选择器选择日期范围,提供范围约束、自定义、无障碍和全球化等特性。
When to Use This Skill
何时使用本技能
Use this skill when you need to:
- Install and set up the DateRangePicker component in Blazor applications
- Create date range selection interfaces
- Set minimum and maximum date constraints
- Bind component values to data models
- Customize placeholder text, first day of week, and visual appearance
- Implement keyboard navigation and accessibility features
- Handle component events (change, blur, focus, etc.)
- Configure globalization and localization for different cultures
- Support DateOnly type for .NET 6+ projects
- Open popups on input click or programmatically
- Display week numbers in the calendar
- Apply custom CSS styling and theming
- Work with RTL (right-to-left) languages
- Debug common DateRangePicker issues
以下场景可使用本技能:
- 在Blazor应用中安装和配置DateRangePicker组件
- 创建日期范围选择界面
- 设置最小和最大日期约束
- 将组件值绑定到数据模型
- 自定义占位文本、一周起始日和视觉外观
- 实现键盘导航和无障碍功能
- 处理组件事件(变更、失焦、聚焦等)
- 为不同文化配置全球化和本地化
- 为.NET 6+项目支持DateOnly类型
- 点击输入框或通过代码打开弹窗
- 在日历中显示周数
- 应用自定义CSS样式和主题
- 适配RTL(从右到左)语言
- 排查DateRangePicker常见问题
Component Overview
组件概览
SfDateRangePicker is a calendar-based input component that allows users to select a continuous date range. Key characteristics:
- Dual Calendar View: Shows two calendar months for easy range selection
- Range Constraints: Min/Max properties enforce date restrictions
- Flexible Data Binding: Works with DateTime, DateTime?, and DateOnly types
- Customizable: First day of week, placeholder, popup behavior, styling
- Accessible: Full WCAG 2.2 AA compliance with keyboard navigation
- Globalized: Supports multiple cultures, RTL, and date formatting
- Event-Driven: Comprehensive event system for user interactions
- Mobile-Friendly: Touch-optimized calendar interface
SfDateRangePicker是基于日历的输入组件,允许用户选择连续的日期范围,核心特性:
- 双日历视图:展示两个日历月份,方便范围选择
- 范围约束:通过最小/最大属性限制可选日期
- 灵活数据绑定:支持DateTime、DateTime?和DateOnly类型
- 可自定义:一周起始日、占位符、弹窗行为、样式
- 无障碍:完全符合WCAG 2.2 AA标准,支持键盘导航
- 全球化:支持多文化、RTL和日期格式化
- 事件驱动:完善的用户交互事件系统
- 移动端友好:触摸优化的日历界面
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Installation via NuGet packages
- Namespace imports and service registration
- Basic component setup (WebAssembly and Server apps)
- Adding theme stylesheet
- Setting Min/Max date constraints
- Rendering your first DateRangePicker
📄 阅读: references/getting-started.md
- 通过NuGet包安装
- 命名空间导入与服务注册
- 基础组件配置(WebAssembly和Server应用)
- 添加主题样式表
- 设置最小/最大日期约束
- 渲染你的第一个DateRangePicker
Range Selection & Data Binding
范围选择与数据绑定
📄 Read: references/range-selection.md
- Single vs range date selection modes
- Two-way data binding with @bind
- Programmatic range updates
- Clearing date selections
- Using DateOnly type for .NET 6+
- Value change handling
📄 阅读: references/range-selection.md
- 单选与范围日期选择模式
- 基于@bind的双向数据绑定
- 代码式更新范围
- 清除日期选择
- .NET 6+的DateOnly类型使用
- 值变更处理
Customization & Styling
自定义与样式
📄 Read: references/customization-and-styling.md
- Configuring first day of week
- Setting placeholder text
- Custom CSS class application
- Opening popup on input click
- Displaying week numbers
- Appearance and visual customization
- Theme integration
📄 阅读: references/customization-and-styling.md
- 配置一周起始日
- 设置占位文本
- 应用自定义CSS类
- 点击输入框打开弹窗
- 显示周数
- 外观与视觉自定义
- 主题集成
Data & Globalization
数据与全球化
📄 Read: references/data-and-globalization.md
- Data binding patterns and best practices
- DateOnly type support and usage
- Globalization configuration
- Culture-specific date formatting
- Right-to-left (RTL) language support
- Localization for international audiences
📄 阅读: references/data-and-globalization.md
- 数据绑定模式与最佳实践
- DateOnly类型支持与使用
- 全球化配置
- 文化特定的日期格式化
- RTL(从右到左)语言支持
- 面向国际用户的本地化
Events & Interactions
事件与交互
📄 Read: references/events-and-interactions.md
- ValueChange event (range selection complete)
- RangeSelected event (individual date selections)
- OnOpen/OnClose events (popup lifecycle)
- Focus/Blur events
- Cleared event (clear button clicked)
- Created/Destroyed lifecycle events
- Navigated event (calendar view navigation)
- OnRenderDayCell event (custom day cell rendering)
- Using DateRangePickerEvents child component
- Event argument types (RangePickerEventArgs<TValue>)
📄 阅读: references/events-and-interactions.md
- ValueChange事件(范围选择完成)
- RangeSelected事件(单个日期选择)
- OnOpen/OnClose事件(弹窗生命周期)
- Focus/Blur事件
- Cleared事件(点击清除按钮)
- Created/Destroyed生命周期事件
- Navigated事件(日历视图导航)
- OnRenderDayCell事件(自定义日期单元格渲染)
- 使用DateRangePickerEvents子组件
- 事件参数类型(RangePickerEventArgs<TValue>)
Accessibility
无障碍
📄 Read: references/accessibility.md
- WCAG 2.2 AA compliance overview
- Keyboard navigation shortcuts
- Calendar month navigation keys
- ARIA attributes and screen reader support
- Mobile device accessibility features
- Testing and validating accessibility
📄 阅读: references/accessibility.md
- WCAG 2.2 AA合规概览
- 键盘导航快捷键
- 日历月份导航按键
- ARIA属性与屏幕阅读器支持
- 移动设备无障碍特性
- 无障碍测试与验证
Quick Start
快速入门
Basic DateRangePicker
基础DateRangePicker
razor
@using Syncfusion.Blazor.Calendars
<SfDateRangePicker TValue="DateTime?" Placeholder="Select a date range"></SfDateRangePicker>razor
@using Syncfusion.Blazor.Calendars
<SfDateRangePicker TValue="DateTime?" Placeholder="选择日期范围"></SfDateRangePicker>With Date Constraints
带日期约束
razor
<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);
}razor
<SfDateRangePicker TValue="DateTime?"
Placeholder="选择范围"
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);
}With Data Binding (StartDate/EndDate)
数据绑定(开始日期/结束日期)
razor
<SfDateRangePicker TValue="DateTime?"
@bind-StartDate="StartDate"
@bind-EndDate="EndDate">
</SfDateRangePicker>
@code {
private DateTime? StartDate { get; set; }
private DateTime? EndDate { get; set; }
}razor
<SfDateRangePicker TValue="DateTime?"
@bind-StartDate="StartDate"
@bind-EndDate="EndDate">
</SfDateRangePicker>
@code {
private DateTime? StartDate { get; set; }
private DateTime? EndDate { get; set; }
}With Range Constraints
带范围长度约束
razor
<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; }
}razor
<SfDateRangePicker TValue="DateTime?"
MinDays="3"
MaxDays="30"
@bind-StartDate="StartDate"
@bind-EndDate="EndDate">
</SfDateRangePicker>
@code {
// 用户必须选择3到30天的范围
private DateTime? StartDate { get; set; }
private DateTime? EndDate { get; set; }
}With Preset Ranges
带预设范围
razor
<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);
}razor
<SfDateRangePicker TValue="DateTime?">
<DateRangePickerPresets>
<DateRangePickerPreset Label="过去7天" Start="@last7DaysStart" End="@currentDate"></DateRangePickerPreset>
<DateRangePickerPreset Label="过去30天" Start="@last30DaysStart" End="@currentDate"></DateRangePickerPreset>
<DateRangePickerPreset Label="本月" 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);
}Key Properties
核心属性
| Property | Type | Purpose |
|---|---|---|
| | Start date of the range (one-way binding) |
| | Two-way binding for start date |
| | End date of the range (one-way binding) |
| | Two-way binding for end date |
| | Combined range value (legacy) |
| | Earliest selectable date |
| | Latest selectable date |
| | Minimum required days in range |
| | Maximum allowed days in range |
| | Predefined date range presets |
| | Separator between start and end dates (default: "-") |
| | Display format pattern |
| | Input placeholder text |
| | Allow manual text input editing |
| | Restrict to valid dates only |
| | Open popup when input is focused |
| | Float label behavior |
| | Enable/disable component |
| | Read-only mode |
| | Show clear button |
| | Display week numbers |
| | First day (0=Sunday, 1=Monday) |
| | Z-index for popup |
| | Component width |
| | Custom CSS class |
| 属性 | 类型 | 用途 |
|---|---|---|
| | 范围起始日期(单向绑定) |
| | 起始日期的双向绑定 |
| | 范围结束日期(单向绑定) |
| | 结束日期的双向绑定 |
| | 合并的范围值(遗留属性) |
| | 最早可选择日期 |
| | 最晚可选择日期 |
| | 范围最小天数要求 |
| | 范围最大天数限制 |
| | 预定义的日期范围预设 |
| | 起始与结束日期之间的分隔符(默认:"-") |
| | 展示格式规则 |
| | 输入占位文本 |
| | 允许手动输入文本 |
| | 仅允许输入有效日期 |
| | 输入框获得焦点时打开弹窗 |
| | 浮动标签行为 |
| | 启用/禁用组件 |
| | 只读模式 |
| | 显示清除按钮 |
| | 显示周数 |
| | 一周起始日(0=周日, 1=周一) |
| | 弹窗Z轴层级 |
| | 组件宽度 |
| | 自定义CSS类 |
Common Patterns
常用模式
Pattern 1: Range Selection with Validation
模式1:带校验的范围选择
razor
<SfDateRangePicker TValue="DateTime?"
@bind-Value="BookingRange"
Min="@minBookingDate"
Placeholder="Select booking dates">
</SfDateRangePicker>
@code {
private DateTime? BookingRange { get; set; }
private DateTime minBookingDate = DateTime.Today;
}razor
<SfDateRangePicker TValue="DateTime?"
@bind-Value="BookingRange"
Min="@minBookingDate"
Placeholder="选择预订日期">
</SfDateRangePicker>
@code {
private DateTime? BookingRange { get; set; }
private DateTime minBookingDate = DateTime.Today;
}Pattern 2: Event Handling
模式2:事件处理
razor
<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}");
}
}razor
<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)
{
// 处理日期范围选择
Console.WriteLine($"开始日期: {args.StartDate}, 结束日期: {args.EndDate}");
}
}Pattern 3: Multiple Instances with Different Constraints
模式3:多实例不同约束
razor
<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>razor
<div>
<h4>第一季度报告期(1月-3月)</h4>
<SfDateRangePicker TValue="DateTime?"
Min="@new DateTime(2024, 1, 1)"
Max="@new DateTime(2024, 3, 31)"
Placeholder="选择日期">
</SfDateRangePicker>
</div>
<div>
<h4>第二季度报告期(4月-6月)</h4>
<SfDateRangePicker TValue="DateTime?"
Min="@new DateTime(2024, 4, 1)"
Max="@new DateTime(2024, 6, 30)"
Placeholder="选择日期">
</SfDateRangePicker>
</div>DateTimePicker
DateTimePicker
A comprehensive guide for implementing and customizing the DateTimePicker component. The DateTimePicker enables users to select both date and time values with support for multiple formats, masks, globalization, and extensive customization options.
本指南用于实现和自定义DateTimePicker组件,DateTimePicker支持用户同时选择日期和时间值,提供多格式、掩码、全球化和丰富的自定义选项。
When to Use This Skill
何时使用本技能
Use this skill when you need to:
- Install and set up the DateTimePicker component in a Blazor application
- Implement date and time selection functionality
- Format date/time values using custom format strings
- Apply input masks and validate user input
- Handle DateTimePicker events (ValueChange, OnOpen, OnClose, etc.)
- Bind the component to data models
- Set minimum and maximum date/time constraints
- Highlight special dates or disable specific dates
- Implement globalization (RTL, multiple locales)
- Support Islamic calendar or other calendar systems
- Customize component appearance and styling
- Configure placeholder text and input validation
- Enable strict mode for input validation
- Display week numbers in the calendar
以下场景可使用本技能:
- 在Blazor应用中安装和配置DateTimePicker组件
- 实现日期和时间选择功能
- 使用自定义格式字符串格式化日期/时间值
- 应用输入掩码并校验用户输入
- 处理DateTimePicker事件(ValueChange、OnOpen、OnClose等)
- 将组件绑定到数据模型
- 设置最小和最大日期/时间约束
- 高亮特殊日期或禁用指定日期
- 实现全球化(RTL、多区域)
- 支持伊斯兰历或其他日历系统
- 自定义组件外观和样式
- 配置占位文本和输入校验
- 开启严格模式用于输入校验
- 在日历中显示周数
Documentation
文档
Getting Started
入门指南
📄 Read: references/getting-started.md
- Installation and NuGet package setup
- Basic component initialization in Blazor Server/Web App
- Minimal working example
- Required imports and configurations
📄 阅读: references/getting-started.md
- 安装与NuGet包配置
- Blazor Server/Web App中的基础组件初始化
- 最小可用示例
- 必要的导入和配置
Date & Time Formatting
日期与时间格式化
📄 Read: references/date-time-formatting.md
- Format string patterns and standard formats
- Custom date/time format configurations
- Locale-specific formatting
- Parse and display format handling
📄 阅读: references/date-time-formatting.md
- 格式字符串规则与标准格式
- 自定义日期/时间格式配置
- 区域特定格式化
- 解析与展示格式处理
Data Binding & Events
数据绑定与事件
📄 Read: references/data-binding-and-events.md
- Two-way binding for date/time values
- ValueChange event (date/time selection complete)
- OnOpen/OnClose events (popup lifecycle)
- Selected event (date selection in calendar)
- OnItemRender event (custom time list item rendering)
- Focus/Blur events
- Cleared event (clear button clicked)
- Created/Destroyed lifecycle events
- Navigated event (calendar view navigation)
- OnRenderDayCell event (custom day cell rendering)
- Using DateTimePickerEvents child component
- State management and data flow patterns
📄 阅读: references/data-binding-and-events.md
- 日期/时间值的双向绑定
- ValueChange事件(日期/时间选择完成)
- OnOpen/OnClose事件(弹窗生命周期)
- Selected事件(日历中选择日期)
- OnItemRender事件(自定义时间列表项渲染)
- Focus/Blur事件
- Cleared事件(点击清除按钮)
- Created/Destroyed生命周期事件
- Navigated事件(日历视图导航)
- OnRenderDayCell事件(自定义日期单元格渲染)
- 使用DateTimePickerEvents子组件
- 状态管理与数据流模式
Date Ranges & Special Dates
日期范围与特殊日期
📄 Read: references/date-ranges-and-special-dates.md
- Setting minimum and maximum date constraints
- Restricting date range selection
- Highlighting special dates
- Disabling specific dates or date ranges
- Week number configuration
📄 阅读: references/date-ranges-and-special-dates.md
- 设置最小和最大日期约束
- 限制日期范围选择
- 高亮特殊日期
- 禁用指定日期或日期范围
- 周数配置
Masking & Input Validation
掩码与输入校验
📄 Read: references/masking-and-input-validation.md
- Input mask patterns for date/time entry
- Placeholder text configuration
- Input validation rules
- Strict mode enforcement and input behavior
- Validation edge cases
📄 阅读: references/masking-and-input-validation.md
- 日期/时间输入的掩码规则
- 占位文本配置
- 输入校验规则
- 严格模式执行与输入行为
- 校验边界场景
Customization & Styling
自定义与样式
📄 Read: references/customization-and-styling.md
- CSS customization and class overrides
- Theme integration (Bootstrap, Material, Fluent, Tailwind)
- Component appearance and styling options
- Custom CSS properties and styling patterns
- Visual customization examples
📄 阅读: references/customization-and-styling.md
- CSS自定义与类重写
- 主题集成(Bootstrap、Material、Fluent、Tailwind)
- 组件外观与样式选项
- 自定义CSS属性与样式模式
- 视觉自定义示例
Globalization & Accessibility
全球化与无障碍
📄 Read: references/globalization-and-accessibility.md
- Globalization support (RTL, multiple locales)
- Islamic calendar implementation and configuration
- Accessibility features (WCAG compliance, keyboard navigation)
- ARIA attributes and screen reader support
- Internationalization best practices
📄 阅读: references/globalization-and-accessibility.md
- 全球化支持(RTL、多区域)
- 伊斯兰历实现与配置
- 无障碍特性(WCAG合规、键盘导航)
- ARIA属性与屏幕阅读器支持
- 国际化最佳实践
Quick Start
快速入门
Here's a minimal working example to get started with the DateTimePicker:
blazor
@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}");
}
}以下是DateTimePicker的最小可用示例:
blazor
@page "/datetimepicker-demo"
@using Syncfusion.Blazor.Calendars
<div>
<label>选择日期和时间:</label>
<SfDateTimePicker TValue="DateTime?"
@bind-Value="@selectedDateTime"
Placeholder="选择日期和时间">
<DateTimePickerEvents TValue="DateTime?" ValueChange="@OnValueChanged"></DateTimePickerEvents>
</SfDateTimePicker>
@if (selectedDateTime.HasValue)
{
<p>选中值: @selectedDateTime.Value.ToString("g")</p>
}
</div>
@code {
private DateTime? selectedDateTime;
private void OnValueChanged(ChangedEventArgs<DateTime?> args)
{
selectedDateTime = args.Value;
Console.WriteLine($"日期变更为: {selectedDateTime}");
}
}Common Patterns
常用模式
Pattern 1: With Date Range Constraints
模式1:带日期范围约束
blazor
<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;
}blazor
<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;
}Pattern 2: With Format Customization
模式2:自定义格式
blazor
<SfDateTimePicker TValue="DateTime?"
Format="dd/MM/yyyy HH:mm"
Value="selectedDateTime">
</SfDateTimePicker>blazor
<SfDateTimePicker TValue="DateTime?"
Format="dd/MM/yyyy HH:mm"
Value="selectedDateTime">
</SfDateTimePicker>Pattern 3: With Input Mask
模式3:带输入掩码
blazor
<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>blazor
<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>Pattern 4: With Data Binding
模式4:数据绑定
blazor
<SfDateTimePicker TValue="DateTime?"
@bind-Value="model.CreatedDate">
<DateTimePickerEvents TValue="DateTime?" ValueChange="@OnDateChanged"></DateTimePickerEvents>
</SfDateTimePicker>blazor
<SfDateTimePicker TValue="DateTime?"
@bind-Value="model.CreatedDate">
<DateTimePickerEvents TValue="DateTime?" ValueChange="@OnDateChanged"></DateTimePickerEvents>
</SfDateTimePicker>Key Properties
核心属性
| Property | Type | Purpose |
|---|---|---|
| | Gets or sets the selected date-time value |
| | Two-way data binding |
| | Display format (e.g., "dd/MM/yyyy HH:mm") |
| | Format for time portion only (e.g., "HH:mm") |
| | Placeholder text for the input field |
| | Minimum selectable date (date portion) |
| | Maximum selectable date (date portion) |
| | Minimum selectable time |
| | Maximum selectable time |
| | Time interval step in minutes (default: 30) |
| | Initial scroll position in time list |
| | Allows manual text input |
| | Enforces strict input validation |
| | Enable input masking for date/time entry |
| | Opens popup on input focus |
| | Float label behavior |
| | Enables/disables the component |
| | Makes the component read-only |
| | Show clear button |
| | Displays today button in calendar |
| | Display week numbers |
| | First day (0=Sunday, 1=Monday) |
| | Initial calendar view |
| | Deepest view level |
| | Z-index for popup |
| | Component width |
| | Custom CSS class |
| 属性 | 类型 | 用途 |
|---|---|---|
| | 获取或设置选中的日期时间值 |
| | 双向数据绑定 |
| | 展示格式(例如"dd/MM/yyyy HH:mm") |
| | 仅时间部分的格式(例如"HH:mm") |
| | 输入框的占位文本 |
| | 最小可选日期(日期部分) |
| | 最大可选日期(日期部分) |
| | 最小可选时间 |
| | 最大可选时间 |
| | 时间间隔步长(单位:分钟,默认30) |
| | 时间列表的初始滚动位置 |
| | 允许手动输入文本 |
| | 执行严格输入校验 |
| | 开启日期/时间输入掩码 |
| | 输入框获得焦点时打开弹窗 |
| | 浮动标签行为 |
| | 启用/禁用组件 |
| | 设为只读模式 |
| | 显示清除按钮 |
| | 在日历中显示今天按钮 |
| | 显示周数 |
| | 一周起始日(0=周日, 1=周一) |
| | 初始日历视图 |
| | 最深视图层级 |
| | 弹窗Z轴层级 |
| | 组件宽度 |
| | 自定义CSS类 |
TimePicker
TimePicker
A comprehensive skill for implementing and customizing the TimePicker component. This skill covers installation, configuration, data binding, events, styling, accessibility, internationalization, and advanced features like input masking.
本指南用于实现和自定义TimePicker组件,覆盖安装、配置、数据绑定、事件、样式、无障碍、国际化以及输入掩码等高级特性。
When to Use This Skill
何时使用本技能
Use this skill when you need to:
- Install and set up the TimePicker component in Blazor applications
- Create basic and advanced TimePicker implementations
- Configure time formats (12-hour, 24-hour, custom formats)
- Set up data binding (one-way, two-way, dynamic)
- Handle TimePicker events (ValueChange, OnOpen, OnClose, Blur, Focus, etc.)
- Customize appearance and styling with CSS
- Implement input masking and validation
- Configure accessibility (keyboard navigation, ARIA attributes, screen readers)
- Add globalization support (localization, RTL for Arabic/Hebrew)
- Set time intervals and step values
- Implement full-screen mode on mobile devices
以下场景可使用本技能:
- 在Blazor应用中安装和配置TimePicker组件
- 实现基础和高级的TimePicker功能
- 配置时间格式(12小时制、24小时制、自定义格式)
- 设置数据绑定(单向、双向、动态)
- 处理TimePicker事件(ValueChange、OnOpen、OnClose、Blur、Focus等)
- 通过CSS自定义外观和样式
- 实现输入掩码和校验
- 配置无障碍功能(键盘导航、ARIA属性、屏幕阅读器)
- 添加全球化支持(本地化、阿拉伯语/希伯来语RTL)
- 设置时间间隔和步长值
- 在移动设备上实现全屏模式
Component Overview
组件概览
The SfTimePicker is a Blazor input component for time selection. It provides:
- Popup time picker interface with scrollable time list
- Configurable time formats and intervals
- Two-way data binding support
- Built-in validation and masking
- Full accessibility compliance (WCAG 2.2, Section 508)
- RTL support for international audiences
- Mobile-responsive with full-screen mode
- Keyboard navigation shortcuts
SfTimePicker是用于时间选择的Blazor输入组件,提供:
- 带可滚动时间列表的弹窗时间选择界面
- 可配置的时间格式和间隔
- 双向数据绑定支持
- 内置校验和掩码
- 完全符合无障碍标准(WCAG 2.2、第508条款)
- 面向国际用户的RTL支持
- 移动端响应式,支持全屏模式
- 键盘导航快捷键
Quick Start Example
快速入门示例
Basic TimePicker
基础TimePicker
razor
@using Syncfusion.Blazor.Calendars
<SfTimePicker TValue="DateTime?" Placeholder="Select a time"></SfTimePicker>razor
@using Syncfusion.Blazor.Calendars
<SfTimePicker TValue="DateTime?" Placeholder="选择时间"></SfTimePicker>TimePicker with Value Binding
带值绑定的TimePicker
razor
@using Syncfusion.Blazor.Calendars
<p>Selected Time: @SelectedTime</p>
<SfTimePicker TValue="DateTime?" @bind-Value="@SelectedTime"></SfTimePicker>
@code {
public DateTime? SelectedTime { get; set; } = DateTime.Now;
}razor
@using Syncfusion.Blazor.Calendars
<p>选中时间: @SelectedTime</p>
<SfTimePicker TValue="DateTime?" @bind-Value="@SelectedTime"></SfTimePicker>
@code {
public DateTime? SelectedTime { get; set; } = DateTime.Now;
}TimePicker with Format and Step
带格式和步长的TimePicker
razor
@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;
}razor
@using Syncfusion.Blazor.Calendars
<SfTimePicker TValue="DateTime?"
Value="@TimeValue"
Format="HH:mm"
Step=60
Placeholder="选择时间(24小时制)">
</SfTimePicker>
@code {
public DateTime TimeValue { get; set; } = DateTime.Now;
}Key Props Reference
核心属性参考
Key Properties
核心属性
| Property | Type | Description | Default |
|---|---|---|---|
| | Current time value (one-way binding) | null |
| | Two-way data binding | - |
| | Placeholder text in input | "Select a time" |
| | Display format string (HH:mm, hh:mm tt) | Culture-based |
| | Accepted input format patterns | Culture-based |
| | Time interval in minutes | 30 |
| | Initial scroll position in time list | null |
| | Minimum selectable time | 00:00 |
| | Maximum selectable time | 23:59 |
| | Allow manual text input | true |
| | Enforce strict input validation | false |
| | Enable input masking | false |
| | Open popup when input is focused | false |
| | Float label behavior | Never |
| | Enable/disable component | true |
| | Read-only mode | false |
| | Show clear button | false |
| | Enable right-to-left (RTL) direction | false |
| | Full-screen mode on mobile | false |
| | Z-index for popup | 1000 |
| | Component width | "100%" |
| | Custom CSS class | null |
| | Tab order index | 0 |
| 属性 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| | 当前时间值(单向绑定) | null |
| | 双向数据绑定 | - |
| | 输入框占位文本 | "Select a time" |
| | 展示格式字符串(HH:mm、hh:mm tt) | 基于区域文化 |
| | 可接受的输入格式规则 | 基于区域文化 |
| | 时间间隔(单位:分钟) | 30 |
| | 时间列表的初始滚动位置 | null |
| | 最小可选时间 | 00:00 |
| | 最大可选时间 | 23:59 |
| | 允许手动输入文本 | true |
| | 执行严格输入校验 | false |
| | 开启输入掩码 | false |
| | 输入框获得焦点时打开弹窗 | false |
| | 浮动标签行为 | Never |
| | 启用/禁用组件 | true |
| | 只读模式 | false |
| | 显示清除按钮 | false |
| | 开启从右到左(RTL)方向 | false |
| | 移动端全屏模式 | false |
| | 弹窗Z轴层级 | 1000 |
| | 组件宽度 | "100%" |
| | 自定义CSS类 | null |
| | Tab顺序索引 | 0 |
Documentation Navigation
文档导航
Getting Started
入门指南
📄 Read: references/getting-started.md
- NuGet package installation
- Namespace imports
- Service registration in Program.cs
- Theme setup and inclusion
- Basic component implementation
- Step property and time intervals
📄 阅读: references/getting-started.md
- NuGet包安装
- 命名空间导入
- Program.cs中的服务注册
- 主题配置与引入
- 基础组件实现
- Step属性与时间间隔
Time Formats
时间格式
📄 Read: references/time-formats.md
- Display format customization
- Input format configuration
- Standard vs custom format strings
- Culture-based default formats
- 12-hour and 24-hour format examples
- When to use each format option
📄 阅读: references/time-formats.md
- 展示格式自定义
- 输入格式配置
- 标准与自定义格式字符串
- 基于区域文化的默认格式
- 12小时制与24小时制格式示例
- 不同格式选项的适用场景
Data Binding
数据绑定
📄 Read: references/data-binding.md
- One-way binding patterns
- Two-way binding with @bind-Value
- Dynamic value updates
- DateTime and DateTime? type handling
- Value change event integration
📄 阅读: references/data-binding.md
- 单向绑定模式
- 基于@bind-Value的双向绑定
- 动态值更新
- DateTime与DateTime?类型处理
- 值变更事件集成
Events and Handlers
事件与处理函数
📄 Read: references/events-and-handlers.md
- ValueChange event (EventCallback<ChangeEventArgs<TValue>>)
- OnOpen/OnClose popup events
- Selected event (time selection in list)
- OnItemRender event (custom time list item rendering)
- Focus/Blur input events
- Cleared event (clear button clicked)
- Created/Destroyed lifecycle events
- Using TimePickerEvents child component
- Event handler implementation patterns
📄 阅读: references/events-and-handlers.md
- ValueChange事件(EventCallback<ChangeEventArgs<TValue>>)
- OnOpen/OnClose弹窗事件
- Selected事件(列表中选中时间)
- OnItemRender事件(自定义时间列表项渲染)
- Focus/Blur输入事件
- Cleared事件(点击清除按钮)
- Created/Destroyed生命周期事件
- 使用TimePickerEvents子组件
- 事件处理函数实现模式
Styling and Appearance
样式与外观
📄 Read: references/styling-and-appearance.md
- CSS classes for customization
- Container element styling
- Icon element styling
- Popup and list item styling
- Full-screen mode for mobile devices
- Theme integration (Bootstrap, Material, Fluent)
📄 阅读: references/styling-and-appearance.md
- 用于自定义的CSS类
- 容器元素样式
- 图标元素样式
- 弹窗与列表项样式
- 移动端全屏模式
- 主题集成(Bootstrap、Material、Fluent)
Accessibility and Globalization
无障碍与全球化
📄 Read: references/accessibility-and-globalization.md
- WCAG 2.2 compliance and standards
- Keyboard navigation shortcuts (arrow keys, Enter, Esc)
- WAI-ARIA attributes and roles
- RTL (right-to-left) support
- Localization and culture configuration
- Screen reader support
📄 阅读: references/accessibility-and-globalization.md
- WCAG 2.2合规与标准
- 键盘导航快捷键(方向键、Enter、Esc)
- WAI-ARIA属性与角色
- RTL(从右到左)支持
- 本地化与区域文化配置
- 屏幕阅读器支持
Mask Support
掩码支持
📄 Read: references/mask-support.md
- EnableMask property for input masking
- TimePickerMaskPlaceholder directive
- Custom placeholder characters (Hour, Minute, Second)
- Format-specific masking patterns
- Input validation with masks
📄 阅读: references/mask-support.md
- 用于输入掩码的EnableMask属性
- TimePickerMaskPlaceholder指令
- 自定义占位字符(时、分、秒)
- 格式特定的掩码规则
- 带掩码的输入校验
Common Patterns
常用模式
Pattern 1: Simple Time Selection
模式1:简单时间选择
When users need a basic time picker without complex requirements:
razor
<SfTimePicker TValue="DateTime?"
@bind-Value="@AppointmentTime"
Placeholder="Select appointment time">
</SfTimePicker>适用于用户需要基础时间选择器,无复杂需求的场景:
razor
<SfTimePicker TValue="DateTime?"
@bind-Value="@AppointmentTime"
Placeholder="选择预约时间">
</SfTimePicker>Pattern 2: Business Hours Only
模式2:仅营业时间可选
When time selection should be limited to specific hours:
razor
<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; }
}适用于时间选择需要限制在指定时段的场景:
razor
<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; }
}Pattern 3: 12-Hour Format with AM/PM
模式3:带AM/PM的12小时制格式
When displaying time in 12-hour format:
razor
<SfTimePicker TValue="DateTime?"
@bind-Value="@UserTime"
Format="hh:mm tt"
Placeholder="Select time (12-hour)">
</SfTimePicker>
@code {
public DateTime? UserTime { get; set; } = DateTime.Now;
}适用于需要展示12小时制时间的场景:
razor
<SfTimePicker TValue="DateTime?"
@bind-Value="@UserTime"
Format="hh:mm tt"
Placeholder="选择时间(12小时制)">
</SfTimePicker>
@code {
public DateTime? UserTime { get; set; } = DateTime.Now;
}Pattern 4: With Event Handling
模式4:带事件处理
When tracking time selection changes:
razor
<SfTimePicker TValue="DateTime?">
<TimePickerEvents TValue="DateTime?" ValueChange="@OnTimeChanged"></TimePickerEvents>
</SfTimePicker>
@code {
private void OnTimeChanged(ChangeEventArgs<DateTime?> args)
{
Console.WriteLine($"Time selected: {args.Value}");
}
}适用于需要跟踪时间选择变更的场景:
razor
<SfTimePicker TValue="DateTime?">
<TimePickerEvents TValue="DateTime?" ValueChange="@OnTimeChanged"></TimePickerEvents>
</SfTimePicker>
@code {
private void OnTimeChanged(ChangeEventArgs<DateTime?> args)
{
Console.WriteLine($"选中时间: {args.Value}");
}
}Common Use Cases
常见使用场景
- Appointment Booking: Time selection for scheduling appointments with business hours validation
- Time Tracking: Recording start/end times for timesheets or activity logs
- Shift Management: Selecting shift times in HR/workforce applications
- Travel Booking: Departure/arrival time selection for flights, trains
- Delivery Windows: Setting preferred delivery time slots in e-commerce
- Broadcast Scheduling: Selecting broadcast times for media applications
- Meeting Scheduler: Time selection for virtual meetings with timezone support
- Gym Booking: Class time selection in fitness management apps
- 预约预订:用于日程预约的时间选择,带营业时间校验
- 时间追踪:为工时表或活动日志记录开始/结束时间
- 排班管理:在HR/人力应用中选择班次时间
- 旅行预订:航班、火车的出发/到达时间选择
- 配送窗口:电商应用中设置偏好配送时段
- 广播排期:媒体应用中选择广播时间
- 会议调度:带时区支持的虚拟会议时间选择
- 健身预约:健身管理应用中的课程时间选择
Prerequisites
前置要求
- Blazor WebAssembly or Blazor Server project (.NET 7 or later)
- NuGet package:
Syncfusion.Blazor.Calendars - NuGet package:
Syncfusion.Blazor.Themes - Syncfusion service registered in
Program.cs
Ready to implement Calendar components? Start with Getting Started guides above for setup, then navigate to other references based on your specific needs.
Next Steps: Start with the Getting Started guide for your chosen component, then navigate to other references based on your specific task.
For detailed implementation patterns, complete code examples, and troubleshooting guidance, read the appropriate reference file based on your specific needs.
undefined- Blazor WebAssembly或Blazor Server项目(.NET 7及以上)
- NuGet包:
Syncfusion.Blazor.Calendars - NuGet包:
Syncfusion.Blazor.Themes - 在中注册Syncfusion服务
Program.cs
准备好实现日历组件了吗? 从上面的入门指南开始配置,然后根据你的具体需求查看其他参考文档。
下一步: 先查看你所选组件的入门指南,然后根据具体任务查看其他参考文档。
如需详细的实现模式、完整代码示例和问题排查指导,请根据你的具体需求阅读对应的参考文件。