syncfusion-react-timepicker

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing 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

核心属性参考

PropTypeDefaultPurpose
value
DatenullCurrent selected time value
format
stringBased on cultureTime display format (e.g., "HH:mm", "hh:mm a")
min
Date00:00Minimum selectable time
max
Date00:00Maximum selectable time
step
number30Time interval in minutes between list items
enabled
booleantrueEnable/disable the component
readonly
booleanfalseRead-only state (no editing)
placeholder
string-Input placeholder text
openOnFocus
booleanfalseOpen popup on input focus
enableMask
booleanfalseEnable masked input mode
enableRtl
booleanfalseEnable right-to-left layout
strictMode
booleanfalseValidate input and restrict to valid times
showClearButton
booleantrueShow/hide clear button
fullScreenMode
booleanfalseMobile full-screen mode
cssClass
string-Custom CSS class for styling
floatLabelType
stringNeverFloat label position
allowEdit
booleantrueAllow manual input editing
locale
string'en-US'Locale for time formatting
scrollTo
Date-Default scroll position in popup
width
string/number-Component width
zIndex
number1000Z-index of popup
serverTimezoneOffset
number-Server timezone offset for processing
htmlAttributes
object{}Custom HTML attributes
Prop类型默认值用途
value
Datenull当前选中的时间值
format
string基于区域设置时间展示格式(例如 "HH:mm", "hh:mm a")
min
Date00:00可选择的最小时间
max
Date00:00可选择的最大时间
step
number30列表项之间的时间间隔(单位:分钟)
enabled
booleantrue启用/禁用组件
readonly
booleanfalse只读状态(不可编辑)
placeholder
string-输入框占位文本
openOnFocus
booleanfalse输入框聚焦时打开弹窗
enableMask
booleanfalse开启掩码输入模式
enableRtl
booleanfalse启用从右到左布局
strictMode
booleanfalse验证输入并限制为有效时间
showClearButton
booleantrue显示/隐藏清除按钮
fullScreenMode
booleanfalse移动端全屏模式
cssClass
string-用于样式自定义的CSS类
floatLabelType
stringNever浮动标签位置
allowEdit
booleantrue允许手动输入编辑
locale
string'en-US'时间格式化的区域设置
scrollTo
Date-弹窗的默认滚动位置
width
string/number-组件宽度
zIndex
number1000弹窗的Z-index值
serverTimezoneOffset
number-用于处理的服务器时区偏移
htmlAttributes
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学习复杂场景实现