syncfusion-react-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Calendar (React)

实现日历组件（React）

Overview

概述

This skill provides: a short React Quick Start, recommended patterns (single-date, range selection, controlled components), and two reference files: a React-specific getting-started and a concise API reference derived from the Syncfusion React Calendar docs.

Target package:

@syncfusion/ej2-react-calendars

(CalendarComponent)

本技能资料包含：精简的React快速上手教程、推荐实践（单日期选择、范围选择、受控组件），以及两份参考文件：React专属入门指南和源自Syncfusion React Calendar官方文档的精简API参考。

目标包：

@syncfusion/ej2-react-calendars

（CalendarComponent）

Quick Start (React)

快速上手（React）

Install

安装

bash

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

bash

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

Basic Example (App.jsx)

基础示例（App.jsx）

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

Notes:

Use the
```
change
```
event to sync selected date to React state.
Import theme CSS once (global or component-level) to style the control.

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 state中。
全局或组件级别引入一次主题CSS即可为控件添加样式。

Guidance & Patterns

指导与最佳实践

Controlled component: keep source-of-truth in React state and update
```
value
```
via
```
change
```
event.

Multi-selection: use

isMultiSelection={true}

with

values

prop and

addDate()

removeDate()

methods.

Programmatic navigation: use a
```
ref
```
to call
```
navigateTo(view, date)
```
— both arguments are required (see references/getting-started-react.md).
Date ranges: for range selection, use DateRangePicker (separate component). The Calendar itself does not have a built-in range highlight mode.
Accessibility: use wrapper elements with
```
role="region"
```
and a separate
```
aria-live
```
region for announcements — these are not direct Calendar props.
Week numbers: enable with
```
weekNumber={true}
```
(the correct prop name).

受控组件： 将数据源保存在React state中，通过
```
change
```
事件更新
```
value
```
。

多选： 搭配

values

属性和

addDate()

removeDate()

方法使用

isMultiSelection={true}

。

程序化导航： 使用
```
ref
```
调用
```
navigateTo(view, date)
```
——两个参数都是必填项（参见参考资料/getting-started-react.md）。
日期范围： 如需范围选择，请使用DateRangePicker（独立组件）。Calendar组件本身没有内置的范围高亮模式。
无障碍： 使用带
```
role="region"
```
的外层元素和独立的
```
aria-live
```
区域做播报——这些不是Calendar的直接属性。
周数： 通过
```
weekNumber={true}
```
开启（正确的属性名）。

References

参考资料

Navigate to the reference that matches your current task:

跳转到匹配你当前任务的参考资料：

Getting Started

入门指南

📄 Read: references/getting-started-react.md

Installation and npm setup
React component examples
CSS/theme imports
Using refs and methods

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

安装与npm配置
React组件示例
CSS/主题引入
refs与方法的使用

Date Selection

日期选择

📄 Read: references/date-selection.md

Single date selection
Multiple dates and ranges
Min/max constraints
Disabling specific dates

📄 阅读： references/date-selection.md

单日期选择
多日期与范围选择
最小/最大日期约束
禁用指定日期

Calendar Views

日历视图

📄 Read: references/calendar-views.md

Month, Year, Decade views
Navigating between views
Initial and depth controls
Programmatic navigation

📄 阅读： references/calendar-views.md

月、年、十年视图
视图间切换导航
初始视图与层级深度控制
程序化导航

Styling & Customization

样式与自定义

📄 Read: references/styling-customization.md

Theme selection and switching
CSS class customization
Custom day cell rendering
RTL and responsive design

📄 阅读： references/styling-customization.md

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

Events & Methods

事件与方法

📄 Read: references/events-methods.md

Event handlers (change, created, renderDayCell)
Using refs and imperative methods
Advanced renderDayCell hook
Event tracking patterns

📄 阅读： references/events-methods.md

事件处理（change、created、renderDayCell）
refs与命令式方法的使用
高级renderDayCell钩子
事件跟踪实践

Accessibility & Globalization

无障碍与全球化

📄 Read: references/accessibility-globalization.md

WCAG 2.1 compliance
Keyboard navigation
ARIA attributes
Locale support and RTL
Testing for accessibility

📄 阅读： references/accessibility-globalization.md

WCAG 2.1合规
键盘导航
ARIA属性
多语言支持与RTL
无障碍测试

API Reference (Quick Lookup)

API参考（快速查询）

📄 Read: references/api-reference.md

Props, events, methods at a glance
Common enums and types
Link to upstream docs

📄 阅读： references/api-reference.md

快速查看属性、事件、方法
常用枚举与类型
官方文档链接

Troubleshooting & Tips

故障排查与技巧

Styles not applied: confirm CSS imports point to
```
node_modules/@syncfusion/ej2-calendars/styles/
```
and are loaded before component styles.
React state mismatch: use the
```
value
```
prop and
```
change
```
event to keep React state in sync — do not rely on framework-specific bindings.
Multiple date selection not working: ensure
```
isMultiSelection={true}
```
and use
```
values
```
(not
```
value
```
) for the initial array.

navigateTo
not working: the method requires two arguments —

navigateTo(view: CalendarView, date: Date)

"Cannot find module": run

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

and confirm

package.json

Week numbers not showing: use
```
weekNumber={true}
```
(not
```
showWeekNumber
```
).

样式未生效： 确认CSS引入路径指向
```
node_modules/@syncfusion/ej2-calendars/styles/
```
，且加载顺序早于组件样式。
React state不匹配： 使用
```
value
```
属性和
```
change
```
事件保持React state同步——不要依赖框架专属绑定。
多日期选择不生效： 确保设置了
```
isMultiSelection={true}
```
，且使用
```
values
```
（而非
```
value
```
）传入初始数组。

navigateTo
不生效：该方法需要两个参数——

navigateTo(view: CalendarView, date: Date)

。

"找不到模块"： 执行

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

，并检查

package.json

配置。

周数不显示： 使用
```
weekNumber={true}
```
（而非
```
showWeekNumber
```
）。