syncfusion-blazor-calendars

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing 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

组件概览

FeatureDetails
ViewsMonth (default), Year, Decade - hierarchical drill-down navigation
SelectionSingle date, date ranges (Min/Max), multi-select
Data Types
DateTime
,
DateTime?
,
DateOnly
(.NET 6+)
BindingOne-way, two-way (
@bind-Value
), dynamic
Events
ValueChange
,
OnRenderDayCell
,
Created
,
Destroyed
,
Navigated
LocalizationMulti-language, RTL support, locale customization
AccessibilityWCAG 2.2 AA, keyboard navigation, screen reader support
StylingCSS customization, theme integration, special date highlights
特性详情
视图月(默认)、年、十年 - 层级下钻导航
选择模式单选日期、日期范围(最小/最大)、多选
支持数据类型
DateTime
DateTime?
DateOnly
(.NET 6+)
绑定方式单向、双向(
@bind-Value
)、动态绑定
事件
ValueChange
OnRenderDayCell
Created
Destroyed
Navigated
本地化多语言、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

核心属性及使用场景

PropertyTypePurposeExample
Value
TValue
Selected date (one-way binding)
Value="@SelectedDate"
@bind-Value
TValue
Two-way data binding
@bind-Value="@SelectedDate"
Values
DateTime[]
Multiple selected dates (multi-select mode)
Values="@SelectedDates"
@bind-Values
DateTime[]
Two-way binding for multi-selection
@bind-Values="@SelectedDates"
IsMultiSelection
bool
Enable multiple date selection
IsMultiSelection="true"
Min
DateTime
Earliest selectable date (inclusive)
Min="@minSelectableDate"
Max
DateTime
Latest selectable date (inclusive)
Max="@maxSelectableDate"
Start
CalendarView
Initial view (Month/Year/Decade)
Start="CalendarView.Year"
Depth
CalendarView
Deepest view level for drilling
Depth="CalendarView.Month"
ShowTodayButton
bool
Display "Today" button in footer
ShowTodayButton="true"
CalendarMode
CalendarType
Calendar system (Gregorian/Islamic)
CalendarMode="CalendarType.Islamic"
WeekRule
CalendarWeekRule
Week numbering calculation rule
WeekRule="CalendarWeekRule.FirstDay"
DayHeaderFormat
DayHeaderFormats
Day header display format
DayHeaderFormat="DayHeaderFormats.Short"
EnableRtl
bool
Right-to-left layout
EnableRtl="true"
WeekNumber
bool
Display week numbers in calendar
WeekNumber="true"
FirstDayOfWeek
int
First day (0=Sunday, 1=Monday)
FirstDayOfWeek="1"
CssClass
string
Custom CSS class for styling
CssClass="custom-calendar"
Enabled
bool
Enable/disable component
Enabled="false"
属性类型用途示例
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
初始视图(月/年/十年)
Start="CalendarView.Year"
Depth
CalendarView
允许下钻的最深视图层级
Depth="CalendarView.Month"
ShowTodayButton
bool
在页脚显示「今天」按钮
ShowTodayButton="true"
CalendarMode
CalendarType
日历系统(公历/伊斯兰历)
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"

Common Use Cases

常见使用场景

  1. Appointment Booking: Calendar with date range (available days) + event handling
  2. Date Filter: Multi-view calendar for drilling down to specific date
  3. Deadline Selection: Min/Max constraints to valid date ranges
  4. Report Viewing: Year/Month view for period selection
  5. International App: RTL + locale support for multi-language UIs
  6. Accessible Forms: Keyboard-navigable date input with screen reader support
  1. 预约预订:带日期范围(可用日期)+事件处理的日历
  2. 日期筛选:支持下钻到指定日期的多视图日历
  3. 截止日期选择:通过最小/最大约束限制有效日期范围
  4. 报表查看:用于时段选择的年/月视图
  5. 国际化应用:支持RTL+区域适配的多语言UI
  6. 无障碍表单:支持键盘导航、屏幕阅读器的日期输入组件

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
    <CalendarEvents>
    child component
  • DatePicker: Use
    <DatePickerEvents>
    child component
  • DateRangePicker: Use
    <DateRangePickerEvents>
    child component
  • DateTimePicker: Use
    <DateTimePickerEvents>
    child component
  • TimePicker: Use
    <TimePickerEvents>
    child component
  • 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
ValueChange
event:
ComponentValueChange Event Argument TypeNotes
Calendar
ChangedEventArgs<TValue>
For single and multi-date selection
DatePicker
ChangedEventArgs<TValue>
Includes
Value
,
IsInteracted
,
Event
properties
DateTimePicker
ChangedEventArgs<TValue>
Same as DatePicker
TimePicker
ChangeEventArgs<TValue>
Note: Different class name (no 'd')
DateRangePicker
RangePickerEventArgs<TValue>
Includes
StartDate
and
EndDate
properties
Key Differences:
  • ChangedEventArgs<TValue>
    (with 'd') - Used by Calendar, DatePicker, DateTimePicker
    • Properties:
      Value
      ,
      Values
      (for multi-selection),
      IsInteracted
      ,
      Event
      ,
      Element
      ,
      Name
  • ChangeEventArgs<TValue>
    (no 'd') - Used by TimePicker only
    • Properties:
      Value
      ,
      Text
      ,
      IsInteracted
      ,
      Event
      ,
      Element
  • RangePickerEventArgs<TValue>
    - Used by DateRangePicker only
    • Properties:
      StartDate
      ,
      EndDate
      ,
      Text
      ,
      Value
      ,
      IsInteracted
      ,
      Event
      ,
      Element

重要提示: 不同组件的
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

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.Themes
bash
dotnet add package Syncfusion.Blazor.Calendars
dotnet add package Syncfusion.Blazor.Themes

2. Import in
_Imports.razor

2. 在
_Imports.razor
中导入

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

3. Register in
Program.cs

3. 在
Program.cs
中注册服务

csharp
builder.Services.AddSyncfusionBlazor();
csharp
builder.Services.AddSyncfusionBlazor();

4. Add Theme in
App.razor
or Layout

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

html
<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
    Value
    property
  • 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

核心属性

PropertyTypePurpose
Value
TValue
The selected date (one-way binding)
@bind-Value
TValue
Two-way data binding
Min
DateTime
Earliest selectable date
Max
DateTime
Latest selectable date
Format
string
Display format pattern (e.g., "dd/MM/yyyy")
Placeholder
string
Input placeholder text
AllowEdit
bool
Allow manual text input editing
StrictMode
bool
Restrict to valid dates only
EnableMask
bool
Enable input masking for date entry
OpenOnFocus
bool
Open calendar popup when input is focused
FloatLabelType
FloatLabelType
Float label behavior (Auto/Always/Never)
InputFormats
string[]
Array of acceptable input formats
Enabled
bool
Enable/disable component
Readonly
bool
Read-only mode (no user input)
ShowClearButton
bool
Show clear button to reset value
WeekNumber
bool
Display week numbers in calendar
Start
CalendarView
Initial calendar view (Month/Year/Decade)
Depth
CalendarView
Deepest view level allowed
ZIndex
int
Z-index for popup positioning
Width
string
Component width (e.g., "300px")
CssClass
string
Custom CSS class for styling
属性类型用途
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轴层级
Width
string
组件宽度(例如"300px")
CssClass
string
用于自定义样式的CSS类

Performance Tips

性能优化建议

  1. Use DateTime? (nullable) for optional date fields—avoids default date confusion
  2. Lazy-load DatePicker in modals or expandable sections—reduces initial render cost
  3. Minimize format conversions in event handlers—cache formatted strings when possible
  4. Use InteractiveWebAssembly for date-heavy UIs—offloads processing to client
  5. Batch value updates in loops—avoid rapid re-renders with multiple ValueChange triggers

  1. 可选日期字段使用
    DateTime?
    (可空类型),避免默认日期混淆
  2. 在模态框或可展开区域中延迟加载DatePicker,降低初始渲染成本
  3. 尽量减少事件处理程序中的格式转换,必要时缓存格式化后的字符串
  4. 日期密集型UI使用InteractiveWebAssembly渲染模式,将计算转移到客户端
  5. 循环中批量更新值,避免频繁触发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

核心属性

PropertyTypePurpose
StartDate
TValue
Start date of the range (one-way binding)
@bind-StartDate
TValue
Two-way binding for start date
EndDate
TValue
End date of the range (one-way binding)
@bind-EndDate
TValue
Two-way binding for end date
Value
Object
Combined range value (legacy)
Min
DateTime
Earliest selectable date
Max
DateTime
Latest selectable date
MinDays
int?
Minimum required days in range
MaxDays
int?
Maximum allowed days in range
Presets
List<Presets>
Predefined date range presets
Separator
string
Separator between start and end dates (default: "-")
Format
string
Display format pattern
Placeholder
string
Input placeholder text
AllowEdit
bool
Allow manual text input editing
StrictMode
bool
Restrict to valid dates only
OpenOnFocus
bool
Open popup when input is focused
FloatLabelType
FloatLabelType
Float label behavior
Enabled
bool
Enable/disable component
Readonly
bool
Read-only mode
ShowClearButton
bool
Show clear button
WeekNumber
bool
Display week numbers
FirstDayOfWeek
int
First day (0=Sunday, 1=Monday)
ZIndex
int
Z-index for popup
Width
string
Component width
CssClass
string
Custom CSS class
属性类型用途
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轴层级
Width
string
组件宽度
CssClass
string
自定义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

核心属性

PropertyTypePurpose
Value
TValue
Gets or sets the selected date-time value
@bind-Value
TValue
Two-way data binding
Format
string
Display format (e.g., "dd/MM/yyyy HH:mm")
TimeFormat
string
Format for time portion only (e.g., "HH:mm")
Placeholder
string
Placeholder text for the input field
Min
DateTime
Minimum selectable date (date portion)
Max
DateTime
Maximum selectable date (date portion)
MinTime
DateTime
Minimum selectable time
MaxTime
DateTime
Maximum selectable time
Step
int
Time interval step in minutes (default: 30)
ScrollTo
DateTime?
Initial scroll position in time list
AllowEdit
bool
Allows manual text input
StrictMode
bool
Enforces strict input validation
EnableMask
bool
Enable input masking for date/time entry
OpenOnFocus
bool
Opens popup on input focus
FloatLabelType
FloatLabelType
Float label behavior
Enabled
bool
Enables/disables the component
Readonly
bool
Makes the component read-only
ShowClearButton
bool
Show clear button
ShowTodayButton
bool
Displays today button in calendar
WeekNumber
bool
Display week numbers
FirstDayOfWeek
int
First day (0=Sunday, 1=Monday)
Start
CalendarView
Initial calendar view
Depth
CalendarView
Deepest view level
ZIndex
int
Z-index for popup
Width
string
Component width
CssClass
string
Custom CSS class

属性类型用途
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轴层级
Width
string
组件宽度
CssClass
string
自定义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

核心属性

PropertyTypeDescriptionDefault
Value
TValue
Current time value (one-way binding)null
@bind-Value
TValue
Two-way data binding-
Placeholder
string
Placeholder text in input"Select a time"
Format
string
Display format string (HH:mm, hh:mm tt)Culture-based
InputFormats
string[]
Accepted input format patternsCulture-based
Step
int
Time interval in minutes30
ScrollTo
DateTime?
Initial scroll position in time listnull
Min
DateTime
Minimum selectable time00:00
Max
DateTime
Maximum selectable time23:59
AllowEdit
bool
Allow manual text inputtrue
StrictMode
bool
Enforce strict input validationfalse
EnableMask
bool
Enable input maskingfalse
OpenOnFocus
bool
Open popup when input is focusedfalse
FloatLabelType
FloatLabelType
Float label behaviorNever
Enabled
bool
Enable/disable componenttrue
Readonly
bool
Read-only modefalse
ShowClearButton
bool
Show clear buttonfalse
EnableRtl
bool
Enable right-to-left (RTL) directionfalse
FullScreen
bool
Full-screen mode on mobilefalse
ZIndex
int
Z-index for popup1000
Width
string
Component width"100%"
CssClass
string
Custom CSS classnull
TabIndex
int
Tab order index0
属性类型描述默认值
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轴层级1000
Width
string
组件宽度"100%"
CssClass
string
自定义CSS类null
TabIndex
int
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

常见使用场景

  1. Appointment Booking: Time selection for scheduling appointments with business hours validation
  2. Time Tracking: Recording start/end times for timesheets or activity logs
  3. Shift Management: Selecting shift times in HR/workforce applications
  4. Travel Booking: Departure/arrival time selection for flights, trains
  5. Delivery Windows: Setting preferred delivery time slots in e-commerce
  6. Broadcast Scheduling: Selecting broadcast times for media applications
  7. Meeting Scheduler: Time selection for virtual meetings with timezone support
  8. Gym Booking: Class time selection in fitness management apps
  1. 预约预订:用于日程预约的时间选择,带营业时间校验
  2. 时间追踪:为工时表或活动日志记录开始/结束时间
  3. 排班管理:在HR/人力应用中选择班次时间
  4. 旅行预订:航班、火车的出发/到达时间选择
  5. 配送窗口:电商应用中设置偏好配送时段
  6. 广播排期:媒体应用中选择广播时间
  7. 会议调度:带时区支持的虚拟会议时间选择
  8. 健身预约:健身管理应用中的课程时间选择

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
  • Program.cs
    中注册Syncfusion服务

准备好实现日历组件了吗? 从上面的入门指南开始配置,然后根据你的具体需求查看其他参考文档。

下一步: 先查看你所选组件的入门指南,然后根据具体任务查看其他参考文档。
如需详细的实现模式、完整代码示例和问题排查指导,请根据你的具体需求阅读对应的参考文件。