syncfusion-react-datepicker

实现 DatePicker

组件概述

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()

完整 API 摘要

关键属性

属性	类型	默认值	描述
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	弹出窗口的 z-index
enablePersistence	boolean	false	在重新加载期间保留状态

方法

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

事件

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

文档与导航指南

用户需要 DatePicker 方面的帮助时，请引导他们查看相应的参考文档：

入门

📄 阅读： references/getting-started.md

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

日期格式与输入

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

• 显示格式属性与格式模式（yyyy-MM-dd、dd/MM/yyyy 等）
• 自定义格式说明符（# 和 0 模式）
• 灵活的日期输入格式（接受多种格式）
• 实际场景中的格式示例
• 自动解析和转换用户输入
• 基于区域设置的默认格式

日期范围与验证

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

• 用于限制日期范围的最小和最大日期属性
• 范围验证与错误状态
• 使用 strictMode 自动修正超出范围的日期
• 超出范围时的行为与错误处理
• 禁用有效范围之外的日期
• 边界情况与注意事项

日期视图与导航

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

• Start 属性（初始视图：月份、年份、十年）
• 用于限制视图级别的 Depth 属性
• 日历导航与用户交互
• 月份与年份选择快捷方式
• 在不同视图间切换
• 默认行为与最佳实践

自定义与样式

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

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

全球化与本地化

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

• 区域设置与语言环境配置（德语、法语、阿拉伯语等）
• 加载 CLDR 数据以支持国际化
• 按语言环境设置日期格式（不同国家使用不同格式）
• 自定义本地化文本（今天按钮、占位符）
• 支持阿拉伯语、希伯来语、乌尔都语的从右到左（RTL）布局
• 按语言环境设置每周起始日
• 数字格式与日历调整

无障碍与键盘导航

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

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

日期掩码与高级验证

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

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

快速入门示例

以下是一个可运行的最简示例，帮助你快速上手：

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 主题（基础、按钮、输入框、弹出窗口、日历）
• 使用 value 属性设置当前日期（可以是 null 或 Date 对象）
• 使用 change 事件（而非 onChange）更新 React 状态——这是 Syncfusion 的事件名称
• 点击或按 Alt+Down 箭头键时，DatePicker 会打开日历弹出窗口

常见模式

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

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

2. 自定义日期格式

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

3. 多种可接受的输入格式

<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. 用于选择出生日期的年份／年代视图

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

5. 禁用周末

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

6. React 表单中的受控组件

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

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

7. 支持 RTL 的德语区域设置

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

8. 带掩码的日期输入

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

9. 编程式控制

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. 处理所有按键事件

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