syncfusion-react-calendar

实现日历（React）

目录

• 何时使用此技能
• 概述
• 快速开始（React）
• 指南与模式
• 参考资料
• 故障排除与提示

概述

此技能提供：简短的 React 快速入门、推荐模式（单日期、范围选择、受控组件），以及两个参考文件：React 专用的入门指南和根据 Syncfusion React Calendar 文档整理的简明 API 参考。

目标包：@syncfusion/ej2-react-calendars（CalendarComponent）

快速开始（React）

安装

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

基本示例（App.jsx）

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

export default function App() {
  const [value, setValue] = useState(new Date());
  const onChange = (args) => setValue(args.value || args);

  return (
    <div style={{ padding: 20 }}>
      <h3>Select a date</h3>
      <CalendarComponent value={value} change={onChange} />
      <p>Selected: {value.toDateString()}</p>
    </div>
  );
}

说明：

• 使用 change 事件将所选日期同步到 React 状态。
• 导入一次主题 CSS（全局导入或在组件级别导入），为控件添加样式。

指南与模式

• 受控组件： 将真实数据源保存在 React 状态中，并通过 change 事件更新 value。
• 多选： 使用 isMultiSelection={true} 和 values 属性，以及 addDate()/removeDate() 方法。
• 以编程方式导航： 使用 ref 调用 navigateTo(view, date)——两个参数都是必需的（请参阅 references/getting-started-react.md）。
• 日期范围： 如需选择范围，请使用 DateRangePicker（单独的组件）。Calendar 本身没有内置的范围高亮模式。
• 无障碍： 使用带有 role="region" 的包装元素，并设置单独的 aria-live 区域用于播报——这些不是 Calendar 的直接属性。
• 周数： 使用 weekNumber={true} 启用（正确的属性名）。

参考资料

请前往与当前任务对应的参考资料：

入门指南

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

• 安装和 npm 设置
• React 组件示例
• CSS/主题导入
• 使用 refs 和方法

日期选择

📄 阅读： references/date-selection.md

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

日历视图

📄 阅读： references/calendar-views.md

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

样式与自定义

📄 阅读： references/styling-customization.md

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

事件与方法

📄 阅读： references/events-methods.md

• 事件处理程序（change、created、renderDayCell）
• 使用 refs 和命令式方法
• 高级 renderDayCell 钩子
• 事件跟踪模式

无障碍与全球化

📄 阅读： references/accessibility-globalization.md

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

API 参考（快速查阅）

📄 阅读： references/api-reference.md

• 快速了解属性、事件和方法
• 常见枚举和类型
• 上游文档链接

故障排查与提示

• 样式未应用： 确认 CSS 导入指向 node_modules/@syncfusion/ej2-calendars/styles/，并且在组件样式之前加载。
• React 状态不匹配： 使用 value 属性和 change 事件来保持 React 状态同步——不要依赖特定框架的绑定。
• 无法多选日期： 确保 isMultiSelection={true}，并使用 values（而非 value）设置初始数组。
• navigateTo 无法使用： 该方法需要两个参数——navigateTo(view: CalendarView, date: Date)。
• “Cannot find module”： 运行 npm install @syncfusion/ej2-react-calendars @syncfusion/ej2-base，并确认 package.json。
• 未显示周数： 使用 weekNumber={true}（而非 showWeekNumber）。

---