syncfusion-javascript-calendars

实现 Syncfusion JavaScript (EJ2) 日历

Calendar

Syncfusion EJ2 Calendar 是一款高度可定制的日历 UI 控件，允许用户选择单个或多个日期。它支持多个视图（月、年、十年）、导航、周数、禁用日期、自定义日期单元格渲染、本地化、RTL 支持以及完整的无障碍功能（符合 WCAG 2.2）。

快速入门（TypeScript）

安装

npm install @syncfusion/ej2-calendars @syncfusion/ej2-base
npm audit

基本示例

<div id="calendar"></div>

import { Calendar } from '@syncfusion/ej2-calendars';

const calendar = new Calendar({
  value: new Date(),
  change: (args: any) => {
    console.log('Selected date:', args.value);
  }
});

calendar.appendTo('#calendar');

注意：

• 使用 change 事件响应所选日期的变化。
• 导入主题 CSS，为控件设置样式。
• 无需管理 React 状态 — EJ2 会处理内部状态。

指南与模式

• 受控组件： 通过 calendar.value 属性访问当前值，并监听 change 事件。
• 多选： 使用 isMultiSelection: true 和 values 属性，以及 addDate()/removeDate() 方法。
• 以编程方式导航： 调用 navigateTo(view, date) 方法 — 必须提供这两个参数。
• 日期范围： 如需选择日期范围，请使用 DateRangePicker（独立组件）。Calendar 没有内置的范围高亮模式。
• 无障碍功能： Calendar 会自动处理 ARIA 属性。如需提供额外上下文，可使用带有 role="region" 的包装元素。
• 周数： 使用 weekNumber: true 属性启用。

参考资料

根据当前任务查阅相应的参考资料：

入门指南

📄 阅读： references/calendar-getting-started.md

• 安装和 npm 设置
• TypeScript 组件示例
• CSS/主题导入
• 使用方法和事件处理

日期选择

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

• 单日期选择
• 多个日期和范围
• 最小值/最大值限制
• 禁用特定日期

日历视图

📄 阅读： references/calendar-calendar-views.md

• 月、年、十年视图
• 在不同视图间导航
• 初始视图和深度控制
• 以编程方式导航

样式与自定义

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

• 主题选择与切换
• CSS 类自定义
• 自定义日期单元格渲染
• RTL 和响应式设计

事件与方法

📄 阅读： references/calendar-events-and-methods.md

• 事件处理程序（change、created、renderDayCell）
• 使用方法（navigateTo、addDate、removeDate）
• 高级 renderDayCell 钩子
• 事件跟踪模式

无障碍功能与全球化

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

• 符合 WCAG 2.1 标准
• 键盘导航
• ARIA 属性
• 区域设置支持和 RTL

API 参考（快速查询）

📄 阅读： references/calendar-api-reference.md

• 快速查看属性、事件和方法
• 常用枚举和类型
• 上游文档链接

故障排除与提示

• 样式未应用： 确认 CSS 导入路径指向 node_modules/@syncfusion/ej2-calendars/styles/，并且在组件初始化前加载。
• 值未更新： 使用 change 事件更新组件状态 — EJ2 组件通过事件通知变化，而非自动绑定。
• 多日期选择无效： 确保设置了 isMultiSelection: true，并使用 values 数组属性设置初始值。
• navigateTo 无效： 此方法需要两个参数 — navigateTo(view: CalendarView, date: Date)。
• “Cannot find module”： 运行 npm install @syncfusion/ej2-calendars @syncfusion/ej2-base 并检查 package.json。
• 未显示周数： 使用 weekNumber: true（而不是 showWeekNumber）。

日期选择器

Syncfusion EJ2 DatePicker 提供直观的输入控件，并配有日历弹出窗口，可用于选择单个日期。它支持灵活的格式设置、掩码输入、最小/最大日期验证、严格模式、多种输入格式、自定义日期渲染、本地化，以及无缝集成表单。

组件概述

DatePicker 是 Syncfusion EJ2 的日期选择组件，具备强大的功能：

• 日历弹出窗口 - 通过导航进行可视化日期选择
• 灵活的格式设置 - 支持显示和输入格式，并支持格式模式
• 掩码输入 - 使用 enableMask 和 maskPlaceholder 逐段输入日期
• 范围验证 - 设置最小/最大日期，并通过 strictMode 自动更正
• 多种视图 - 通过 start 和 depth 属性提供月、年和十年视图
• 日期单元格自定义 - 禁用周末日期，并通过 renderDayCell 事件突出显示特殊日期
• 全面的国际化支持 - 支持 150 多种区域性、从右向左（RTL）显示（enableRtl）、特定区域的格式设置，以及 firstDayOfWeek
• 符合 WCAG 2.2 标准 - 全面支持无障碍访问，包括键盘导航和 ARIA 属性
• 适用于表单 - 直接绑定 DOM、事件驱动的更新，并集成表单验证
• 可通过编程控制 - show()、hide()、focusIn()、focusOut()、navigateTo()、currentView()

完整 API 摘要

关键属性

属性	类型	默认值	说明
value	Date	null	选定的日期
min	Date	1900-01-01	可选日期的最小值
max	Date	2099-12-31	可选日期的最大值
format	string	null	显示格式（例如，"dd/MM/yyyy"）
inputFormats	string[]	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	object	{...}	掩码输入的分段占位符
enableRtl	boolean	false	从右向左显示
locale	string	''	区域性/语言环境代码
firstDayOfWeek	number	0	每周的第一天（0=星期日）
weekNumber	boolean	false	显示周数
weekRule	WeekRule	FirstDay	年中第一周的规则
calendarMode	CalendarType	Gregorian	日历类型（Gregorian 或 Islamic）
dayHeaderFormat	DayHeaderFormats	Short	标题中的星期名称格式
floatLabelType	FloatLabelType	Never	浮动标签行为
fullScreenMode	boolean	false	在移动设备上以全屏方式弹出
openOnFocus	boolean	false	输入框获得焦点时打开弹出窗口
serverTimezoneOffset	number	null	服务端时区偏移量
cssClass	string	null	自定义 CSS 类
htmlAttributes	object	{}	附加 HTML 属性
keyConfigs	object	null	自定义按键操作映射
width	string | number	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	获取持久化状态数据
destroy()	void	销毁组件

事件

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

文档与导航指南

需要 DatePicker 帮助时，请参阅相应的参考文档：

入门指南

📄 阅读： references/datepicker-getting-started.md

• 通过 npm 安装（@syncfusion/ej2-calendars）
• 导入 CSS 主题（material3、bootstrap、fluent、tailwind）
• 导入并配置组件
• 基本 TypeScript 实现
• 运行你的第一个应用程序

日期格式与输入

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

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

日期范围与验证

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

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

日期视图与导航

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

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

自定义与样式

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

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

全球化与本地化

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

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

无障碍功能与键盘导航

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

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

日期掩码与高级验证

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

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

快速入门示例

以下是一个最简可用示例，助你快速上手：

<input id="datepicker" type="text" />

import { DatePicker } from '@syncfusion/ej2-calendars';

const datepicker = new DatePicker({
  value: new Date(),
  change: (e: any) => {
    console.log('Selected date:', e.value);
  },
  placeholder: 'Enter date'
});

datepicker.appendTo('#datepicker');

要点：

• 从 @syncfusion/ej2-calendars 导入 DatePicker
• 使用 new DatePicker({...}) 创建实例
• 使用 appendTo() 在目标 DOM 元素中渲染
• 使用 change 事件响应日期选择
• 单击或按 Alt+Down 箭头时，DatePicker 会打开日历弹窗

DateRangePicker

Syncfusion EJ2 DateRangePicker 支持用户选择开始和结束日期，并内置预设、验证、自定义格式、分隔符配置、移动设备全屏模式以及高级范围约束（minDays、maxDays、min、max）。

文档导航指南

入门指南

📄 阅读： references/daterangepicker-getting-started.md

• 通过 npm 安装（@syncfusion/ej2-calendars）
• CSS 导入和主题配置
• DateRangePicker 基本实现
• TypeScript 组件设置
• 运行开发服务器
• 常见故障排查

日期范围选择

📄 阅读： references/daterangepicker-date-range-selection.md

• 开始和结束日期属性
• 日期范围验证模式
• 最小和最大日期约束
• 禁用日期配置
• 日期范围预设（最近 7 天、最近 30 天等）
• 值绑定和双向更新
• 只读和禁用状态
• 占位文本和标签

日期范围格式设置

📄 阅读： references/daterangepicker-date-range-formatting.md

• 日期格式字符串选项（MM/dd/yyyy、dd-MMM-yyyy 等）
• 显示格式与输入格式
• 基于区域设置的日期格式
• 开始日期和结束日期之间的自定义分隔符
• 浮动标签类型（Never、Always、Auto）
• 自定义占位文本
• 用于设置 DOM 属性的 htmlAttributes

事件和方法

📄 阅读： references/daterangepicker-events-and-methods.md

• 事件处理程序（change、open、close、blur、focus、select）
• 事件参数结构
• 方法（show、hide、focusIn、focusOut、reset、destroy）
• 使用组件实例直接调用方法
• 生命周期事件（created、destroyed）
• 事件模式和最佳实践
• 清除值和重置状态
• DateRangeSelectingEvent 和 ChangedEventArgs

自定义和样式

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

• 使用 cssClass 自定义 CSS 类
• 主题选项（Material、Bootstrap、Fluent、Tailwind、Fabric）
• 移动设备全屏模式
• RTL（从右到左）语言支持
• 自定义预设范围
• Z-index 管理
• 宽度和高度配置
• 无障碍功能和 ARIA 属性

API 参考

📄 阅读： references/daterangepicker-api-reference.md

• 完整的属性列表（35 个以上属性）
• 所有方法及其签名（8 个方法）
• 所有事件及其事件参数（12 个事件）
• 类型定义和接口
• 默认值和约束
• 每个属性和方法的使用场景

高级模式

📄 阅读： references/daterangepicker-advanced-patterns.md

• 使用日期范围验证提交表单
• 键盘快捷键和按键导航
• 处理服务器时区偏移
• 持久化和 localStorage
• 多组件集成（开始/结束日期绑定）
• 使用延迟加载进行性能优化
• 错误处理和验证模式
• 复杂日期范围场景（财年、季度）

快速入门

<input id="daterangepicker" type="text" />

import { DateRangePicker } from '@syncfusion/ej2-calendars';

const drp = new DateRangePicker({
  placeholder: 'Select a range',
  change: (e: any) => {
    console.log('Start:', e.startDate, 'End:', e.endDate);
  }
});

drp.appendTo('#daterangepicker');

常见模式

模式 1：带最小/最大限制的日期范围

const drp = new DateRangePicker({
  placeholder: 'Select a range in 2026',
  min: new Date(2026, 0, 1),
  max: new Date(2026, 11, 31),
  change: (e: any) => {
    console.log('Range:', e.startDate, '-', e.endDate);
  }
});

drp.appendTo('#drp');

模式 2：带预设值的日期范围

const drp = new DateRangePicker({
  placeholder: 'Select reporting period',
  presets: [
    { label: 'Today', start: new Date(), end: new Date() },
    { label: 'Last 7 Days', start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), end: new Date() },
    { label: 'Last 30 Days', start: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), end: new Date() }
  ]
});

drp.appendTo('#drp');

DateTimePicker

Syncfusion EJ2 DateTimePicker 将日期和时间选择整合在一个控件中。它提供日历和时间列表弹出窗口、可自定义的时间步长、输入掩码、严格验证、时区处理、格式自定义以及完整的键盘无障碍支持。

文档（请按顺序阅读这些参考资料）

• 📄 阅读：references/datetimepicker-getting-started.md — 安装、模块设置、CSS 导入、基本用法
• 📄 阅读：references/datetimepicker-api-reference.md — 完整的属性、方法和事件
• 📄 阅读：references/datetimepicker-date-time-selection.md — 选择模式和约束
• 📄 阅读：references/datetimepicker-time-configuration.md — 步长、minTime/maxTime、滚动行为
• 📄 阅读：references/datetimepicker-events-and-methods.md — 事件处理程序和方法用法
• 📄 阅读：references/datetimepicker-styling-and-customization.md — 主题和 cssClass 用法
• 📄 阅读：references/datetimepicker-advanced-features.md — 输入掩码、严格模式、日历模式、时区处理
• 📄 阅读：references/datetimepicker-accessibility.md — 键盘和 ARIA 指南

快速入门（TypeScript）

1. 安装软件包：

npm install @syncfusion/ej2-calendars
npm audit

2. 导入样式（在 index.css 或组件 CSS 中）：

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-calendars/styles/material3.css';

3. 最小示例：

<input id="datetimepicker" type="text" />

import { DateTimePicker } from '@syncfusion/ej2-calendars';

const picker = new DateTimePicker({
  value: new Date(),
  format: 'dd/MM/yyyy hh:mm a',
  step: 15,
  placeholder: 'Select date and time',
  change: (args: any) => {
    console.log('Selected:', args.value);
  }
});

picker.appendTo('#datetimepicker');

常见模式

• 直接绑定值：设置 value 属性并监听 change 事件。
• 范围限制：使用 min、max 设置日期范围，使用 minTime/maxTime 设置时间范围。
• 输入掩码：启用 enableMask 并提供 maskPlaceholder。
• 本地化：设置 locale 属性以使用特定区域格式。
• 键盘优先：提供 keyConfigs 以配置自定义快捷键。

关键属性摘要（完整列表请参阅 API 参考）

• value、min、max、step、format、enableMask、placeholder、cssClass、locale、readonly、enabled。

关键事件

• change、open、close、created、destroyed、navigated、blur、focus、renderDayCell。

TimePicker

Syncfusion EJ2 TimePicker 是一款轻量且功能丰富的时间选择控件。它支持 12/24 小时制格式、时间步长、最小/最大限制、输入掩码、本地化、全屏模式，并可轻松集成到 HTML 表单中。

文档导航指南

入门指南

📄 阅读： references/timepicker-getting-started.md

• 通过 npm 安装（@syncfusion/ej2-calendars）
• CSS 导入和主题配置
• 基本的 TimePicker 实现
• 组件注册
• 运行开发服务器
• 常见问题排查

时间格式与显示

📄 阅读： references/timepicker-time-format-and-display.md

• 格式字符串选项（24 小时制、12 小时制）
• 带有 skeleton 属性的 TimeFormatObject
• 基于区域设置的时间格式化
• 自定义占位文本
• 浮动标签类型（Never、Always、Auto）
• 用于 DOM 属性的 htmlAttributes
• 使用 enableMask 的掩码输入
• 掩码占位符配置

时间范围与选择

📄 阅读： references/timepicker-time-range-and-selection.md

• 最小和最大时间限制
• 时间步长间隔（15、30、60 分钟）
• ScrollTo 默认位置
• 值绑定和双向更新
• 只读和禁用状态
• OpenOnFocus 行为
• 时间弹出列表填充
• 步进时间间隔

事件与方法

📄 阅读： references/timepicker-events-and-methods.md

• 事件处理程序（change、open、close、blur、focus）
• 事件参数结构
• 方法（show、hide、focusIn、focusOut）
• 直接调用组件实例上的方法
• 生命周期事件（created、destroyed）
• 事件模式和最佳实践
• 清除值和重置状态
• 使用 ItemRender 自定义格式

自定义与样式

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

• 使用 cssClass 自定义 CSS 类
• 主题选项（Material、Bootstrap、Fluent、Tailwind）
• 面向移动设备的全屏模式
• RTL（从右到左）语言支持
• 严格模式验证
• Z-index 管理
• 宽度和高度配置
• 无障碍功能
• Theme Studio 集成

API 参考

📄 阅读： references/timepicker-api-reference.md

• 完整的属性列表（26 个属性）
• 所有方法及其签名（5 个方法）
• 所有事件及其事件参数（9 个事件）
• 类型定义和接口
• 默认值和限制
• 各属性的使用场景

高级模式

📄 阅读： references/timepicker-advanced-patterns.md

• 带验证的表单提交
• 键盘快捷键和 keyConfigs
• 服务器时区偏移处理
• 持久化和 localStorage
• 多组件集成
• 性能优化
• 错误处理模式
• 复杂验证场景

快速入门

<input id="timepicker" type="text" />

import { TimePicker } from '@syncfusion/ej2-calendars';

const timepicker = new TimePicker({
  value: new Date('1/1/2018 9:00 AM'),
  change: (e: any) => {
    console.log('Selected time:', e.value);
  },
  placeholder: 'Select a time'
});

timepicker.appendTo('#timepicker');

常见模式

模式 1：带最小/最大限制的时间选择器

const timepicker = new TimePicker({
  value: new Date('1/1/2018 9:00 AM'),
  min: new Date('1/1/2018 8:00 AM'),
  max: new Date('1/1/2018 5:00 PM'),
  step: 30,
  change: (e: any) => {
    console.log('Appointment time:', e.value);
  },
  placeholder: 'Choose time (8 AM - 5 PM)'
});

timepicker.appendTo('#timepicker');

模式 2：12 小时制与 24 小时制格式

const timepicker12 = new TimePicker({
  format: 'hh:mm a',  // 12-hour with AM/PM
  placeholder: 'Select time'
});

const timepicker24 = new TimePicker({
  format: 'HH:mm',    // 24-hour
  placeholder: 'Select time'
});

timepicker12.appendTo('#timepicker12');
timepicker24.appendTo('#timepicker24');

模式 3：事件处理

const timepicker = new TimePicker({
  value: new Date(),
  change: (e: any) => {
    console.log('Changed to:', e.value?.toLocaleTimeString());
  },
  open: (e: any) => {
    console.log('Popup opened');
  },
  close: (e: any) => {
    console.log('Popup closed');
  }
});

timepicker.appendTo('#timepicker');

关键属性参考

属性	类型	默认值	用途
value	Date	null	当前选中的时间值
format	string	根据区域设置	时间显示格式（例如，“HH:mm”“hh:mm a”）
min	Date	00:00	可选时间的最小值
max	Date	00:00	可选时间的最大值
step	number	30	列表项之间的时间间隔（分钟）
enabled	boolean	true	启用/禁用组件
readonly	boolean	false	只读状态（不可编辑）
placeholder	string	-	输入框占位文本
openOnFocus	boolean	false	输入框获得焦点时打开弹出框
enableMask	boolean	false	启用掩码输入模式
enableRtl	boolean	false	启用从右到左的布局
strictMode	boolean	false	验证输入并限制为有效时间
showClearButton	boolean	true	显示/隐藏清除按钮
fullScreenMode	boolean	false	移动端全屏模式
cssClass	string	-	用于设置样式的自定义 CSS 类
floatLabelType	string	Never	浮动标签位置
allowEdit	boolean	true	允许手动编辑输入
locale	string	'en-US'	时间格式化所用的区域设置
scrollTo	Date	-	弹出框中的默认滚动位置
width	string/number	-	组件宽度
zIndex	number	1000	弹出框的 Z-index
serverTimezoneOffset	number	-	用于处理的服务器时区偏移量
htmlAttributes	object	{}	自定义 HTML 属性

---

后续步骤：

• 阅读 references/timepicker-getting-started.md，安装并设置你的第一个 TimePicker
• 查看 references/timepicker-time-format-and-display.md，了解格式选项
• 查看 references/timepicker-time-range-and-selection.md，了解时间限制
• 阅读 references/timepicker-advanced-patterns.md，了解复杂场景