syncfusion-react-timepicker
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion React TimePicker Component
实现Syncfusion React TimePicker组件
The Syncfusion React TimePicker component provides a user-friendly way to select time values in applications. It supports multiple time formats, time range constraints, keyboard navigation, form integration, and mobile-optimized full-screen mode.
Syncfusion React TimePicker组件为应用中选择时间值提供了用户友好的方式,支持多种时间格式、时间范围约束、键盘导航、表单集成以及移动端优化的全屏模式。
Documentation Navigation Guide
文档导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Installation via npm (@syncfusion/ej2-react-calendars)
- CalendarModule setup in app.module.ts
- CSS imports and theme configuration
- Basic TimePicker implementation
- Component registration with useRef
- Running development server
- Common troubleshooting
📄 阅读: references/getting-started.md
- 通过npm安装 (@syncfusion/ej2-react-calendars)
- 在app.module.ts中配置CalendarModule
- CSS导入与主题配置
- 基础TimePicker实现
- 使用useRef注册组件
- 运行开发服务器
- 常见问题排查
Time Format and Display
时间格式与展示
📄 Read: references/time-format-and-display.md
- Format string options (24-hour, 12-hour formats)
- TimeFormatObject with skeleton property
- Locale-based time formatting
- Placeholder text customization
- Float label types (Never, Always, Auto)
- htmlAttributes for DOM attributes
- Masked input with enableMask
- Mask placeholder configuration
📄 阅读: references/time-format-and-display.md
- 格式字符串选项(24小时制、12小时制格式)
- 带skeleton属性的TimeFormatObject
- 基于区域设置的时间格式化
- 占位符文本自定义
- 浮动标签类型(Never、Always、Auto)
- 用于DOM属性的htmlAttributes
- 开启enableMask的掩码输入
- 掩码占位符配置
Time Range and Selection
时间范围与选择
📄 Read: references/time-range-and-selection.md
- Minimum and maximum time constraints
- Time step intervals (15, 30, 60 minutes)
- ScrollTo default position
- Value binding and two-way updates
- Read-only and disabled states
- OpenOnFocus behavior
- Time popup list population
- Stepped time intervals
📄 阅读: references/time-range-and-selection.md
- 最小与最大时间约束
- 时间步长间隔(15、30、60分钟)
- ScrollTo默认位置
- 值绑定与双向更新
- 只读与禁用状态
- OpenOnFocus行为
- 时间弹窗列表填充
- 阶梯时间间隔
Events and Methods
事件与方法
📄 Read: references/events-and-methods.md
- Event handlers (change, open, close, blur, focus)
- Event argument structures
- Methods (show, hide, focusIn, focusOut)
- Imperative control with useRef
- Lifecycle events (created, destroyed)
- Event patterns and best practices
- Clearing values and state reset
- ItemRender for custom formatting
📄 阅读: references/events-and-methods.md
- 事件处理函数(change、open、close、blur、focus)
- 事件参数结构
- 方法(show、hide、focusIn、focusOut)
- 使用useRef的命令式控制
- 生命周期事件(created、destroyed)
- 事件模式与最佳实践
- 清除值与状态重置
- 用于自定义格式化的ItemRender
Customization and Styling
自定义与样式
📄 Read: references/customization-and-styling.md
- CSS class customization with cssClass
- Theme options (Material, Bootstrap, Fluent, Tailwind)
- Full-screen mode for mobile devices
- RTL (right-to-left) language support
- Strict mode validation
- Z-index management
- Width and height configuration
- Accessibility features
- Theme Studio integration
📄 阅读: references/customization-and-styling.md
- 通过cssClass自定义CSS类
- 主题选项(Material、Bootstrap、Fluent、Tailwind)
- 移动端全屏模式
- RTL(从右到左)语言支持
- 严格模式验证
- Z-index管理
- 宽度与高度配置
- 无障碍特性
- Theme Studio集成
API Reference
API参考
📄 Read: references/api-reference.md
- Complete properties list (26 properties)
- All methods with signatures (5 methods)
- All events with event arguments (9 events)
- Type definitions and interfaces
- Default values and constraints
- Use cases for each property
📄 阅读: references/api-reference.md
- 完整属性列表(26个属性)
- 所有带签名的方法(5个方法)
- 所有带参数的事件(9个事件)
- 类型定义与接口
- 默认值与约束
- 每个属性的使用场景
Advanced Patterns
高级模式
📄 Read: references/advanced-patterns.md
- Form submission with validation
- Keyboard shortcuts and keyConfigs
- Server timezone offset handling
- Persistence and localStorage
- Multi-component integration
- Performance optimization
- Error handling patterns
- Complex validation scenarios
📄 阅读: references/advanced-patterns.md
- 带验证的表单提交
- 键盘快捷键与keyConfigs
- 服务器时区偏移处理
- 持久化与localStorage
- 多组件集成
- 性能优化
- 错误处理模式
- 复杂验证场景
Quick Start
快速开始
tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-calendars/styles/material3.css';
function App() {
const [selectedTime, setSelectedTime] = React.useState(new Date('1/1/2018 9:00 AM'));
const handleChange = (e: any) => {
setSelectedTime(e.value);
};
return (
<div style={{ padding: '20px' }}>
<h2>Select Time</h2>
<TimePickerComponent
value={selectedTime}
change={handleChange}
placeholder="Select a time"
/>
<p>Selected: {selectedTime ? selectedTime.toLocaleTimeString() : 'None'}</p>
</div>
);
}
export default App;tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-calendars/styles/material3.css';
function App() {
const [selectedTime, setSelectedTime] = React.useState(new Date('1/1/2018 9:00 AM'));
const handleChange = (e: any) => {
setSelectedTime(e.value);
};
return (
<div style={{ padding: '20px' }}>
<h2>Select Time</h2>
<TimePickerComponent
value={selectedTime}
change={handleChange}
placeholder="Select a time"
/>
<p>Selected: {selectedTime ? selectedTime.toLocaleTimeString() : 'None'}</p>
</div>
);
}
export default App;Common Patterns
常用模式
Pattern 1: Time Picker with Min/Max Constraints
模式1:带最小/最大约束的时间选择器
tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function AppointmentScheduler() {
const [appointmentTime, setAppointmentTime] = React.useState(new Date('1/1/2018 9:00 AM'));
const minTime = new Date('1/1/2018 8:00 AM');
const maxTime = new Date('1/1/2018 5:00 PM');
return (
<div>
<h3>Select Appointment Time (8 AM - 5 PM)</h3>
<TimePickerComponent
value={appointmentTime}
min={minTime}
max={maxTime}
step={30}
change={(e: any) => setAppointmentTime(e.value)}
placeholder="Choose time"
/>
</div>
);
}
export default AppointmentScheduler;tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function AppointmentScheduler() {
const [appointmentTime, setAppointmentTime] = React.useState(new Date('1/1/2018 9:00 AM'));
const minTime = new Date('1/1/2018 8:00 AM');
const maxTime = new Date('1/1/2018 5:00 PM');
return (
<div>
<h3>Select Appointment Time (8 AM - 5 PM)</h3>
<TimePickerComponent
value={appointmentTime}
min={minTime}
max={maxTime}
step={30}
change={(e: any) => setAppointmentTime(e.value)}
placeholder="Choose time"
/>
</div>
);
}
export default AppointmentScheduler;Pattern 2: Form with Time Picker Submission
模式2:带时间选择器提交的表单
tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
function ScheduleForm() {
const [formData, setFormData] = React.useState({
startTime: new Date('1/1/2018 9:00 AM'),
endTime: new Date('1/1/2018 5:00 PM'),
});
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
console.log('Schedule data:', {
startTime: formData.startTime?.toLocaleTimeString(),
endTime: formData.endTime?.toLocaleTimeString(),
});
};
return (
<form onSubmit={handleSubmit}>
<h3>Schedule Meeting</h3>
<label>Start Time:</label>
<TimePickerComponent
value={formData.startTime}
change={(e: any) => setFormData(prev => ({ ...prev, startTime: e.value }))}
/>
<label style={{ marginTop: '10px' }}>End Time:</label>
<TimePickerComponent
value={formData.endTime}
min={formData.startTime}
change={(e: any) => setFormData(prev => ({ ...prev, endTime: e.value }))}
/>
<ButtonComponent type="submit" isPrimary={true} style={{ marginTop: '15px' }}>
Schedule
</ButtonComponent>
</form>
);
}
export default ScheduleForm;tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';
function ScheduleForm() {
const [formData, setFormData] = React.useState({
startTime: new Date('1/1/2018 9:00 AM'),
endTime: new Date('1/1/2018 5:00 PM'),
});
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
console.log('Schedule data:', {
startTime: formData.startTime?.toLocaleTimeString(),
endTime: formData.endTime?.toLocaleTimeString(),
});
};
return (
<form onSubmit={handleSubmit}>
<h3>Schedule Meeting</h3>
<label>Start Time:</label>
<TimePickerComponent
value={formData.startTime}
change={(e: any) => setFormData(prev => ({ ...prev, startTime: e.value }))}
/>
<label style={{ marginTop: '10px' }}>End Time:</label>
<TimePickerComponent
value={formData.endTime}
min={formData.startTime}
change={(e: any) => setFormData(prev => ({ ...prev, endTime: e.value }))}
/>
<ButtonComponent type="submit" isPrimary={true} style={{ marginTop: '15px' }}>
Schedule
</ButtonComponent>
</form>
);
}
export default ScheduleForm;Pattern 3: Time Picker with Custom Format
模式3:自定义格式的时间选择器
tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function TimeFormatDemo() {
const [time12hr, setTime12hr] = React.useState(new Date('1/1/2018 2:30 PM'));
const [time24hr, setTime24hr] = React.useState(new Date('1/1/2018 14:30'));
return (
<div style={{ padding: '20px' }}>
<div>
<h4>12-Hour Format (hh:mm a)</h4>
<TimePickerComponent
value={time12hr}
format="hh:mm a"
change={(e: any) => setTime12hr(e.value)}
/>
<p>Value: {time12hr?.toLocaleTimeString('en-US', { hour12: true })}</p>
</div>
<div style={{ marginTop: '20px' }}>
<h4>24-Hour Format (HH:mm)</h4>
<TimePickerComponent
value={time24hr}
format="HH:mm"
change={(e: any) => setTime24hr(e.value)}
/>
<p>Value: {time24hr?.toLocaleTimeString('en-US', { hour12: false })}</p>
</div>
</div>
);
}
export default TimeFormatDemo;tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function TimeFormatDemo() {
const [time12hr, setTime12hr] = React.useState(new Date('1/1/2018 2:30 PM'));
const [time24hr, setTime24hr] = React.useState(new Date('1/1/2018 14:30'));
return (
<div style={{ padding: '20px' }}>
<div>
<h4>12-Hour Format (hh:mm a)</h4>
<TimePickerComponent
value={time12hr}
format="hh:mm a"
change={(e: any) => setTime12hr(e.value)}
/>
<p>Value: {time12hr?.toLocaleTimeString('en-US', { hour12: true })}</p>
</div>
<div style={{ marginTop: '20px' }}>
<h4>24-Hour Format (HH:mm)</h4>
<TimePickerComponent
value={time24hr}
format="HH:mm"
change={(e: any) => setTime24hr(e.value)}
/>
<p>Value: {time24hr?.toLocaleTimeString('en-US', { hour12: false })}</p>
</div>
</div>
);
}
export default TimeFormatDemo;Pattern 4: Event Handling and State Management
模式4:事件处理与状态管理
tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function EventTrackingExample() {
const [selectedTime, setSelectedTime] = React.useState<Date | null>(null);
const [eventLog, setEventLog] = React.useState<string[]>([]);
const handleChange = (e: any) => {
setSelectedTime(e.value);
setEventLog(prev => [...prev, `Changed: ${e.value?.toLocaleTimeString()}`]);
};
const handleOpen = (e: any) => {
setEventLog(prev => [...prev, 'Popup opened']);
};
const handleClose = (e: any) => {
setEventLog(prev => [...prev, 'Popup closed']);
};
return (
<div style={{ padding: '20px' }}>
<h3>Time Picker with Event Tracking</h3>
<TimePickerComponent
value={selectedTime}
change={handleChange}
open={handleOpen}
close={handleClose}
placeholder="Select time to track events"
/>
<div style={{ marginTop: '20px', padding: '10px', border: '1px solid #ccc' }}>
<h4>Event Log:</h4>
<ul>
{eventLog.map((event, idx) => (
<li key={idx}>{event}</li>
))}
</ul>
</div>
</div>
);
}
export default EventTrackingExample;tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function EventTrackingExample() {
const [selectedTime, setSelectedTime] = React.useState<Date | null>(null);
const [eventLog, setEventLog] = React.useState<string[]>([]);
const handleChange = (e: any) => {
setSelectedTime(e.value);
setEventLog(prev => [...prev, `Changed: ${e.value?.toLocaleTimeString()}`]);
};
const handleOpen = (e: any) => {
setEventLog(prev => [...prev, 'Popup opened']);
};
const handleClose = (e: any) => {
setEventLog(prev => [...prev, 'Popup closed']);
};
return (
<div style={{ padding: '20px' }}>
<h3>Time Picker with Event Tracking</h3>
<TimePickerComponent
value={selectedTime}
change={handleChange}
open={handleOpen}
close={handleClose}
placeholder="Select time to track events"
/>
<div style={{ marginTop: '20px', padding: '10px', border: '1px solid #ccc' }}>
<h4>Event Log:</h4>
<ul>
{eventLog.map((event, idx) => (
<li key={idx}>{event}</li>
))}
</ul>
</div>
</div>
);
}
export default EventTrackingExample;Pattern 5: Masked Time Input
模式5:掩码时间输入
tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function MaskedTimePickerExample() {
const [maskedTime, setMaskedTime] = React.useState(new Date('1/1/2018 10:30 AM'));
return (
<div style={{ padding: '20px' }}>
<h3>Masked Time Input</h3>
<TimePickerComponent
value={maskedTime}
enableMask={true}
format="hh:mm a"
maskPlaceholder={{
hour: 'HH',
minute: 'MM',
second: 'SS',
}}
change={(e: any) => setMaskedTime(e.value)}
placeholder="Enter time (HH:MM AM/PM)"
/>
<p>Masked input helps users enter time in correct format</p>
</div>
);
}
export default MaskedTimePickerExample;tsx
import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
function MaskedTimePickerExample() {
const [maskedTime, setMaskedTime] = React.useState(new Date('1/1/2018 10:30 AM'));
return (
<div style={{ padding: '20px' }}>
<h3>Masked Time Input</h3>
<TimePickerComponent
value={maskedTime}
enableMask={true}
format="hh:mm a"
maskPlaceholder={{
hour: 'HH',
minute: 'MM',
second: 'SS',
}}
change={(e: any) => setMaskedTime(e.value)}
placeholder="Enter time (HH:MM AM/PM)"
/>
<p>Masked input helps users enter time in correct format</p>
</div>
);
}
export default MaskedTimePickerExample;Key Props Reference
核心属性参考
| Prop | Type | Default | Purpose |
|---|---|---|---|
| Date | null | Current selected time value |
| string | Based on culture | Time display format (e.g., "HH:mm", "hh:mm a") |
| Date | 00:00 | Minimum selectable time |
| Date | 00:00 | Maximum selectable time |
| number | 30 | Time interval in minutes between list items |
| boolean | true | Enable/disable the component |
| boolean | false | Read-only state (no editing) |
| string | - | Input placeholder text |
| boolean | false | Open popup on input focus |
| boolean | false | Enable masked input mode |
| boolean | false | Enable right-to-left layout |
| boolean | false | Validate input and restrict to valid times |
| boolean | true | Show/hide clear button |
| boolean | false | Mobile full-screen mode |
| string | - | Custom CSS class for styling |
| string | Never | Float label position |
| boolean | true | Allow manual input editing |
| string | 'en-US' | Locale for time formatting |
| Date | - | Default scroll position in popup |
| string/number | - | Component width |
| number | 1000 | Z-index of popup |
| number | - | Server timezone offset for processing |
| object | {} | Custom HTML attributes |
| Prop | 类型 | 默认值 | 用途 |
|---|---|---|---|
| Date | null | 当前选中的时间值 |
| string | 基于区域设置 | 时间展示格式(例如 "HH:mm", "hh:mm a") |
| Date | 00:00 | 可选择的最小时间 |
| Date | 00:00 | 可选择的最大时间 |
| number | 30 | 列表项之间的时间间隔(单位:分钟) |
| boolean | true | 启用/禁用组件 |
| boolean | false | 只读状态(不可编辑) |
| string | - | 输入框占位文本 |
| boolean | false | 输入框聚焦时打开弹窗 |
| boolean | false | 开启掩码输入模式 |
| boolean | false | 启用从右到左布局 |
| boolean | false | 验证输入并限制为有效时间 |
| boolean | true | 显示/隐藏清除按钮 |
| boolean | false | 移动端全屏模式 |
| string | - | 用于样式自定义的CSS类 |
| string | Never | 浮动标签位置 |
| boolean | true | 允许手动输入编辑 |
| string | 'en-US' | 时间格式化的区域设置 |
| Date | - | 弹窗的默认滚动位置 |
| string/number | - | 组件宽度 |
| number | 1000 | 弹窗的Z-index值 |
| number | - | 用于处理的服务器时区偏移 |
| object | {} | 自定义HTML属性 |
Related Skills
相关技能
- Implementing Checkbox - For multi-select time options
- Implementing DatePicker - For date and time selection
- Implementing Range Slider - For time range selection
Next Steps:
- Read references/getting-started.md to install and set up your first TimePicker
- Explore references/time-format-and-display.md for format options
- Check references/time-range-and-selection.md for time constraints
- See references/advanced-patterns.md for complex scenarios
- 实现Checkbox - 用于多选时间选项
- 实现DatePicker - 用于日期和时间选择
- 实现Range Slider - 用于时间范围选择
后续步骤:
- 阅读references/getting-started.md安装并搭建你的第一个TimePicker
- 查看references/time-format-and-display.md了解格式选项
- 查阅references/time-range-and-selection.md了解时间约束配置
- 参考references/advanced-patterns.md学习复杂场景实现