syncfusion-react-timepicker

实现 Syncfusion React TimePicker 组件

Syncfusion React TimePicker 组件为应用程序提供了友好的时间值选择方式。它支持多种时间格式、时间范围限制、键盘导航、表单集成，以及针对移动设备优化的全屏模式。

文档导航指南

开始使用

📄 阅读： references/getting-started.md

• 通过 npm 安装（@syncfusion/ej2-react-calendars）
• 在 app.module.ts 中设置 CalendarModule
• 导入 CSS 并配置主题
• 基本 TimePicker 实现
• 使用 useRef 注册组件
• 运行开发服务器
• 常见问题排查

时间格式和显示

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

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

时间范围和选择

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

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

事件和方法

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

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

自定义和样式

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

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

API 参考

📄 阅读： references/api-reference.md

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

高级模式

📄 阅读： references/advanced-patterns.md

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

快速开始

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;

常见模式

模式 1：带最小值/最大值限制的 TimePicker

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;

模式 2：提交带有 TimePicker 的表单

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;

模式 3：带自定义格式的 TimePicker

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;

模式 4：事件处理和状态管理

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;

模式 5：掩码时间输入

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;

核心属性参考

属性	类型	默认值	用途
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/getting-started.md，安装并设置你的第一个 TimePicker
• 查看 references/time-format-and-display.md，了解格式选项
• 查看 references/time-range-and-selection.md，了解时间限制
• 查看 references/advanced-patterns.md，了解复杂场景