syncfusion-react-datepicker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing DatePicker

实现DatePicker

Component Overview

组件概述

The DatePicker is a Syncfusion React component for date selection with powerful features:

Calendar popup - Visual date selection with navigation
Flexible formatting - Display and input formats with pattern support
Masked input -
```
enableMask
```
for segment-by-segment date entry with
```
maskPlaceholder
```
Range validation - Min/max dates with
```
strictMode
```
automatic correction
Multiple views - Month, year, and decade views via
```
start
```
and
```
depth
```
properties
Day cell customization - Disable weekends, highlight special dates via
```
renderDayCell
```
event
Full globalization - 150+ cultures, RTL (
```
enableRtl
```
), locale-specific formatting,
```
firstDayOfWeek
```
WCAG 2.2 compliant - Full accessibility with keyboard navigation and ARIA attributes
Form ready - Controlled components, React hooks, form validation integration

Programmatic control -

show()

hide()

focusIn()

focusOut()

navigateTo()

currentView()

DatePicker 是Syncfusion推出的React日期选择组件，具备丰富强大的功能：

日历弹窗 - 支持可视化日期选择与导航
灵活格式化 - 支持自定义展示与输入格式规则
掩码输入 -
```
enableMask
```
用于实现分段日期输入，可配合
```
maskPlaceholder
```
使用
范围验证 - 支持设置最小/最大日期，
```
strictMode
```
可自动修正超出范围的日期
多视图切换 - 通过
```
start
```
和
```
depth
```
属性支持月、年、十年视图
日期单元格定制 - 通过
```
renderDayCell
```
事件可禁用周末、高亮特殊日期
全全球化支持 - 兼容150+文化、RTL（
```
enableRtl
```
）、本地化格式、自定义
```
firstDayOfWeek
```
符合WCAG 2.2标准 - 完整支持键盘导航与ARIA属性，具备优秀的无障碍访问能力
适配表单场景 - 支持受控组件、React hooks、表单验证集成

可编程控制 - 提供

show()

、

hide()

、

focusIn()

、

focusOut()

、

navigateTo()

、

currentView()

等方法

Complete API Summary

完整API摘要

Key Properties

核心属性

Property	Type	Default	Description
`value`	Date	null	Selected date
`min`	Date	1900-01-01	Minimum selectable date
`max`	Date	2099-12-31	Maximum selectable date
`format`	string \| FormatObject	null	Display format (e.g., `"dd/MM/yyyy"` )
`inputFormats`	string[] \| FormatObject[]	null	Accepted input formats array
`placeholder`	string	null	Placeholder text for the input
`enabled`	boolean	true	Enable or disable the component
`readonly`	boolean	false	Readonly state
`allowEdit`	boolean	true	Allow editing the input textbox
`strictMode`	boolean	false	Auto-correct out-of-range dates
`showClearButton`	boolean	true	Show/hide the clear button
`showTodayButton`	boolean	true	Show/hide today button
`start`	CalendarView	Month	Initial view: `"Month"` , `"Year"` , `"Decade"`
`depth`	CalendarView	Month	Deepest navigation level
`enableMask`	boolean	false	Enable masked date input
`maskPlaceholder`	MaskPlaceholderModel	{...}	Segment placeholders for masked input
`enableRtl`	boolean	false	Right-to-left rendering
`locale`	string	''	Culture/locale code
`firstDayOfWeek`	number	0	First day of week (0=Sunday)
`weekNumber`	boolean	false	Show week numbers
`weekRule`	WeekRule	FirstDay	Rule for first week of year
`calendarMode`	CalendarType	Gregorian	Calendar type (Gregorian or Islamic)
`dayHeaderFormat`	DayHeaderFormats	Short	Day name format in header
`floatLabelType`	FloatLabelType	Never	Floating label behavior
`fullScreenMode`	boolean	false	Full screen popup on mobile
`openOnFocus`	boolean	false	Open popup on input focus
`serverTimezoneOffset`	number	null	Server timezone offset
`cssClass`	string	null	Custom CSS class
`htmlAttributes`	{ [key: string]: string }	{}	Additional HTML attributes
`keyConfigs`	{ [key: string]: string }	null	Custom key action mappings
`width`	number \| string	null	Component width
`zIndex`	number	1000	Popup z-index
`enablePersistence`	boolean	false	Persist state between reloads

属性	类型	默认值	描述
`value`	Date	null	选中的日期
`min`	Date	1900-01-01	最小可选日期
`max`	Date	2099-12-31	最大可选日期
`format`	string \| FormatObject	null	展示格式（例如 `"dd/MM/yyyy"` ）
`inputFormats`	string[] \| FormatObject[]	null	可接受的输入格式数组
`placeholder`	string	null	输入框占位文本
`enabled`	boolean	true	启用或禁用组件
`readonly`	boolean	false	只读状态
`allowEdit`	boolean	true	允许编辑输入框文本
`strictMode`	boolean	false	自动修正超出范围的日期
`showClearButton`	boolean	true	显示/隐藏清空按钮
`showTodayButton`	boolean	true	显示/隐藏今天按钮
`start`	CalendarView	Month	初始视图： `"Month"` 、 `"Year"` 、 `"Decade"`
`depth`	CalendarView	Month	最深导航层级
`enableMask`	boolean	false	启用日期掩码输入
`maskPlaceholder`	MaskPlaceholderModel	{...}	掩码输入的分段占位符
`enableRtl`	boolean	false	从右到左渲染
`locale`	string	''	文化/区域代码
`firstDayOfWeek`	number	0	一周的第一天（0=周日）
`weekNumber`	boolean	false	显示周数
`weekRule`	WeekRule	FirstDay	年度第一周的计算规则
`calendarMode`	CalendarType	Gregorian	日历类型（公历或伊斯兰历）
`dayHeaderFormat`	DayHeaderFormats	Short	头部日期名称格式
`floatLabelType`	FloatLabelType	Never	浮动标签行为
`fullScreenMode`	boolean	false	移动端弹窗全屏展示
`openOnFocus`	boolean	false	输入框获得焦点时打开弹窗
`serverTimezoneOffset`	number	null	服务端时区偏移
`cssClass`	string	null	自定义CSS类
`htmlAttributes`	{ [key: string]: string }	{}	额外HTML属性
`keyConfigs`	{ [key: string]: string }	null	自定义按键映射
`width`	number \| string	null	组件宽度
`zIndex`	number	1000	弹窗层级
`enablePersistence`	boolean	false	页面重载后保留组件状态

Methods

方法

Method	Returns	Description
`show()`	void	Opens the calendar popup
`hide()`	void	Closes the calendar popup
`focusIn()`	void	Sets focus to the component
`focusOut()`	void	Removes focus from the component
`navigateTo(view, date)`	void	Navigates to a specific view and date
`currentView()`	string	Returns the current calendar view name
`getPersistData()`	string	Gets persisted state data
`removeDate(dates)`	void	Removes date(s) from the values
`destroy()`	void	Destroys the component

方法	返回值	描述
`show()`	void	打开日历弹窗
`hide()`	void	关闭日历弹窗
`focusIn()`	void	给组件设置焦点
`focusOut()`	void	移除组件焦点
`navigateTo(view, date)`	void	导航到指定视图和日期
`currentView()`	string	返回当前日历视图名称
`getPersistData()`	string	获取持久化状态数据
`removeDate(dates)`	void	从选中值中移除指定日期
`destroy()`	void	销毁组件

Events

事件

Event	Args Type	Description
`change`	ChangedEventArgs	Fires when the selected date changes
`focus`	FocusEventArgs	Fires when input gains focus
`blur`	BlurEventArgs	Fires when input loses focus
`open`	PreventableEventArgs \| PopupObjectArgs	Fires when the popup opens
`close`	PreventableEventArgs \| PopupObjectArgs	Fires when the popup closes
`cleared`	ClearedEventArgs	Fires when value is cleared
`created`	Object	Fires when component is created
`destroyed`	Object	Fires when component is destroyed
`navigated`	NavigatedEventArgs	Fires when calendar view is navigated
`renderDayCell`	RenderDayCellEventArgs	Fires when each day cell is rendered

事件	参数类型	描述
`change`	ChangedEventArgs	选中日期变更时触发
`focus`	FocusEventArgs	输入框获得焦点时触发
`blur`	BlurEventArgs	输入框失去焦点时触发
`open`	PreventableEventArgs \| PopupObjectArgs	弹窗打开时触发
`close`	PreventableEventArgs \| PopupObjectArgs	弹窗关闭时触发
`cleared`	ClearedEventArgs	值被清空时触发
`created`	Object	组件创建完成时触发
`destroyed`	Object	组件销毁时触发
`navigated`	NavigatedEventArgs	日历视图切换时触发
`renderDayCell`	RenderDayCellEventArgs	每个日期单元格渲染时触发

Documentation & Navigation Guide

文档与导航指南

When the user needs help with DatePicker, guide them to the appropriate reference:

当用户需要DatePicker相关帮助时，可引导他们查看对应的参考文档：

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation via npm (@syncfusion/ej2-react-calendars)
CSS theme imports (material3, bootstrap, fluent, tailwind)
Component imports and setup
Basic JSX implementation with DatePickerComponent
Functional vs class component examples
Running your first application

📄 阅读： references/getting-started.md

通过npm安装（@syncfusion/ej2-react-calendars）
CSS主题导入（material3、bootstrap、fluent、tailwind）
组件导入与配置
使用DatePickerComponent实现基础JSX
函数式组件与类组件示例
运行第一个应用

Date Formats & Input

日期格式与输入

📄 Read: references/date-formats-and-input.md

Display format property and patterns (yyyy-MM-dd, dd/MM/yyyy, etc.)
Custom format specifiers (# and 0 patterns)
Input formats for flexible date entry (accepting multiple formats)
Format examples with real-world scenarios
Parsing and converting user input automatically
Culture-based default formatting

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

展示格式属性与规则（yyyy-MM-dd、dd/MM/yyyy等）
自定义格式说明符（#和0规则）
支持多输入格式适配灵活的日期输入
真实场景下的格式示例
自动解析转换用户输入
基于文化的默认格式

Date Range & Validation

日期范围与验证

📄 Read: references/date-range-and-validation.md

Min and max date properties for range restriction
Range validation and error states
strictMode for automatic out-of-range correction
Out-of-range behavior and error handling
Disabling dates outside valid range
Edge cases and gotchas

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

通过最小/最大日期属性限制选择范围
范围验证与错误状态
strictMode自动修正超出范围的日期
超范围行为与错误处理
禁用合法范围外的日期
边界情况与注意事项

Date Views & Navigation

日期视图与导航

📄 Read: references/date-views-and-navigation.md

Start property (month, year, decade initial view)
Depth property for restricting view levels
Calendar navigation and user interactions
Month and year selection shortcuts
Navigating between different views
Default behavior and best practices

📄 阅读： references/date-views-and-navigation.md

start属性（月、年、十年初始视图）
depth属性限制视图层级
日历导航与用户交互
月/年选择快捷方式
不同视图间切换
默认行为与最佳实践

Customization & Styling

定制与样式

📄 Read: references/customization-and-styling.md

CSS classes for styling (e-datepicker, e-calendar, e-day, etc.)
renderDayCell event for day customization
Disabling specific dates and weekends
Placeholder, disabled, and readonly states
Custom CSS and theme customization
Day cell appearance and behavior

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

样式相关CSS类（e-datepicker、e-calendar、e-day等）
用于日期定制的renderDayCell事件
禁用指定日期与周末
占位符、禁用、只读状态
自定义CSS与主题定制
日期单元格外观与行为

Globalization & Localization

全球化与本地化

📄 Read: references/globalization-and-localization.md

Culture and locale configuration (German, French, Arabic, etc.)
Loading CLDR data for internationalization
Date format by culture (different countries, different formats)
Locale text customization (today button, placeholder)
Right-to-Left (RTL) support for Arabic, Hebrew, Urdu
Week start day by culture
Number formatting and calendar adjustments

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

文化与区域配置（德语、法语、阿拉伯语等）
加载CLDR数据实现国际化
不同文化对应的日期格式（不同国家不同格式）
本地化文本定制（今天按钮、占位符）
支持阿拉伯语、希伯来语、乌尔都语的从右到左（RTL）展示
不同文化对应的周起始日
数字格式化与日历调整

Accessibility & Keyboard Navigation

无障碍与键盘导航

📄 Read: references/accessibility-and-keyboard.md

WCAG 2.2 compliance and accessibility standards
Keyboard navigation shortcuts (Alt+Down, arrow keys, Esc)
ARIA attributes (aria-expanded, aria-disabled, aria-activedescendant)
Screen reader support and announcements
Focus management and visible focus indicators
Color contrast and visual accessibility
Mobile device support

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

WCAG 2.2合规与无障碍标准
键盘导航快捷键（Alt+向下箭头、方向键、Esc）
ARIA属性（aria-expanded、aria-disabled、aria-activedescendant）
屏幕阅读器支持与播报
焦点管理与可见焦点指示器
色彩对比度与视觉无障碍
移动端支持

Date Masking & Advanced Validation

日期掩码与高级验证

📄 Read: references/date-masking-and-strict-mode.md

```
enableMask
```
property for structured segment-by-segment date input
```
maskPlaceholder
```
for custom segment placeholder text
Date masking patterns for input guidance
```
strictMode
```
property behavior and enforcement
Date parsing rules and validation logic
Input validation and format enforcement
Edge cases (leap years, month boundaries, etc.)
Troubleshooting common validation issues
Best practices for date input

📄 阅读： references/date-masking-and-strict-mode.md

```
enableMask
```
属性实现结构化分段日期输入
```
maskPlaceholder
```
自定义分段占位文本
日期掩码规则引导输入
```
strictMode
```
属性的行为与规则
日期解析规则与验证逻辑
输入验证与格式强制
边界情况（闰年、月份边界等）
常见验证问题排查
日期输入最佳实践

Quick Start Example

快速开始示例

Here's a minimal working example to get started:

jsx

import React, { useState } from 'react';
import { DatePickerComponent } from '@syncfusion/ej2-react-calendars';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';
import '@syncfusion/ej2-popups/styles/material3.css';
import '@syncfusion/ej2-react-calendars/styles/material3.css';

export default function App() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <div style={{ padding: '20px' }}>
      <h3>Select a Date</h3>
      <DatePickerComponent
        value={selectedDate}
        change={(e) => setSelectedDate(e.value)}
        placeholder="Enter date"
      />
      <p>Selected: {selectedDate?.toDateString()}</p>
    </div>
  );
}

Key points:

Import

DatePickerComponent

from

@syncfusion/ej2-react-calendars

Import all required CSS themes (base, buttons, inputs, popups, calendars)
Use
```
value
```
prop for the current date (can be null or Date object)
Use
```
change
```
event (not
```
onChange
```
) to update React state — this is the Syncfusion event name
DatePicker opens a calendar popup on click or Alt+Down arrow

以下是最小可用示例：

jsx

import React, { useState } from 'react';
import { DatePickerComponent } from '@syncfusion/ej2-react-calendars';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';
import '@syncfusion/ej2-popups/styles/material3.css';
import '@syncfusion/ej2-react-calendars/styles/material3.css';

export default function App() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <div style={{ padding: '20px' }}>
      <h3>Select a Date</h3>
      <DatePickerComponent
        value={selectedDate}
        change={(e) => setSelectedDate(e.value)}
        placeholder="Enter date"
      />
      <p>Selected: {selectedDate?.toDateString()}</p>
    </div>
  );
}

核心要点：

从

@syncfusion/ej2-react-calendars

导入

DatePickerComponent

导入所有必需的CSS主题（base、buttons、inputs、popups、calendars）
使用
```
value
```
属性传入当前日期（可为null或Date对象）
使用
```
change
```
事件（而非
```
onChange
```
）更新React状态——这是Syncfusion的事件命名规范
DatePicker点击或按Alt+向下箭头会打开日历弹窗

Common Patterns

常见使用模式

1. Date Range Picker (Min/Max Dates)

1. 日期范围选择器（最小/最大日期）

jsx

<DatePickerComponent
  value={new Date()}
  min={new Date(2026, 0, 1)}
  max={new Date(2026, 11, 31)}
  placeholder="Select a date in 2026"
/>

jsx

<DatePickerComponent
  value={new Date()}
  min={new Date(2026, 0, 1)}
  max={new Date(2026, 11, 31)}
  placeholder="Select a date in 2026"
/>

2. Custom Date Format

2. 自定义日期格式

jsx

<DatePickerComponent
  value={new Date()}
  format="dd/MM/yyyy"
  placeholder="DD/MM/YYYY"
/>

jsx

<DatePickerComponent
  value={new Date()}
  format="dd/MM/yyyy"
  placeholder="DD/MM/YYYY"
/>

3. Multiple Accepted Input Formats

3. 多输入格式支持

jsx

<DatePickerComponent
  value={new Date()}
  format="yyyy-MM-dd"
  inputFormats={['dd/MM/yyyy', 'yyyy-MM-dd', 'yyyyMMdd']}
  placeholder="Enter date (dd/MM/yyyy or yyyy-MM-dd)"
/>

jsx

<DatePickerComponent
  value={new Date()}
  format="yyyy-MM-dd"
  inputFormats={['dd/MM/yyyy', 'yyyy-MM-dd', 'yyyyMMdd']}
  placeholder="Enter date (dd/MM/yyyy or yyyy-MM-dd)"
/>

4. Year/Decade View for Birth Date Selection

4. 年/十年视图选择出生日期

jsx

<DatePickerComponent
  value={new Date()}
  start="Decade"
  depth="Year"
  placeholder="Select year"
/>

jsx

<DatePickerComponent
  value={new Date()}
  start="Decade"
  depth="Year"
  placeholder="Select year"
/>

5. Disable Weekends

5. 禁用周末

jsx

<DatePickerComponent
  value={new Date()}
  renderDayCell={(args) => {
    if ((args.date.getDay()) === 0 || (args.date.getDay()) === 6) {
      args.isDisabled = true;
    }
  }}
  placeholder="Weekdays only"
/>

jsx

<DatePickerComponent
  value={new Date()}
  renderDayCell={(args) => {
    if ((args.date.getDay()) === 0 || (args.date.getDay()) === 6) {
      args.isDisabled = true;
    }
  }}
  placeholder="Weekdays only"
/>

6. Controlled Component in React Form

6. React表单中的受控组件

jsx

const [date, setDate] = useState(null);

<DatePickerComponent
  value={date}
  change={(e) => setDate(e.value)}
  format="yyyy-MM-dd"
  strictMode={true}
  placeholder="Enter date"
/>

jsx

const [date, setDate] = useState(null);

<DatePickerComponent
  value={date}
  change={(e) => setDate(e.value)}
  format="yyyy-MM-dd"
  strictMode={true}
  placeholder="Enter date"
/>

7. German Culture with RTL Support

7. 德语文化支持

jsx

<DatePickerComponent
  locale="de"
  enableRtl={false}
  firstDayOfWeek={1}
  value={new Date()}
  placeholder="Datum eingeben"
/>

jsx

<DatePickerComponent
  locale="de"
  enableRtl={false}
  firstDayOfWeek={1}
  value={new Date()}
  placeholder="Datum eingeben"
/>

8. Masked Date Input

8. 掩码日期输入

jsx

<DatePickerComponent
  enableMask={true}
  format="MM/dd/yyyy"
  maskPlaceholder={{ day: 'DD', month: 'MM', year: 'YYYY' }}
  placeholder="Select a date"
/>

jsx

<DatePickerComponent
  enableMask={true}
  format="MM/dd/yyyy"
  maskPlaceholder={{ day: 'DD', month: 'MM', year: 'YYYY' }}
  placeholder="Select a date"
/>

9. Programmatic Control

9. 可编程控制

jsx

import { useRef } from 'react';

const datePickerRef = useRef(null);

// Open calendar
datePickerRef.current.show();

// Close calendar
datePickerRef.current.hide();

// Focus
datePickerRef.current.focusIn();

// Get current view
const view = datePickerRef.current.currentView(); // "Month" | "Year" | "Decade"

// Navigate to specific view
datePickerRef.current.navigateTo('Year', new Date(2026, 0, 1));

<DatePickerComponent ref={datePickerRef} value={new Date()} />

jsx

import { useRef } from 'react';

const datePickerRef = useRef(null);

// Open calendar
datePickerRef.current.show();

// Close calendar
datePickerRef.current.hide();

// Focus
datePickerRef.current.focusIn();

// Get current view
const view = datePickerRef.current.currentView(); // "Month" | "Year" | "Decade"

// Navigate to specific view
datePickerRef.current.navigateTo('Year', new Date(2026, 0, 1));

<DatePickerComponent ref={datePickerRef} value={new Date()} />

10. Handle All Key Events

10. 处理所有核心事件

jsx

<DatePickerComponent
  value={new Date()}
  change={(e) => console.log('Changed:', e.value)}
  focus={(e) => console.log('Focused')}
  blur={(e) => console.log('Blurred')}
  open={(e) => console.log('Opened')}
  close={(e) => console.log('Closed')}
  cleared={(e) => console.log('Cleared')}
  navigated={(e) => console.log('Navigated to view:', e.view)}
  renderDayCell={(args) => {
    // Disable weekends
    if (args.date.getDay() === 0 || args.date.getDay() === 6) {
      args.isDisabled = true;
    }
  }}
/>

jsx

<DatePickerComponent
  value={new Date()}
  change={(e) => console.log('Changed:', e.value)}
  focus={(e) => console.log('Focused')}
  blur={(e) => console.log('Blurred')}
  open={(e) => console.log('Opened')}
  close={(e) => console.log('Closed')}
  cleared={(e) => console.log('Cleared')}
  navigated={(e) => console.log('Navigated to view:', e.view)}
  renderDayCell={(args) => {
    // Disable weekends
    if (args.date.getDay() === 0 || args.date.getDay() === 6) {
      args.isDisabled = true;
    }
  }}
/>