Time Clock 是 Material UI 框架中一个直观的时间选择组件，提供了图形化的时钟界面，方便用户通过点击选择小时和分钟，甚至可以在 12 小时制下选择 AM/PM。它在预定系统、任务调度、日历等需要用户输入时间的场景中非常实用。本文将详细介绍 Time Clock 组件的所有用法，涵盖其主要属性和方法，并展示结合其他 Material UI 组件的实际用例。

1. 基本使用

1.1 安装依赖

首先，确保项目已安装 Material UI 的核心库和日期选择组件包：

npm install @mui/material @mui/x-date-pickers date-fns

1.2 引入和使用 Time Clock 组件

一个简单的 Time Clock 组件如下所示：

import React, { useState } from 'react';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { TimeClock } from '@mui/x-date-pickers/TimeClock';
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';

export default function BasicTimeClock() {
  const [selectedTime, setSelectedTime] = useState(null);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <TimeClock
        value={selectedTime}
        onChange={(newValue) => setSelectedTime(newValue)}
      />
    </LocalizationProvider>
  );
}

在这个例子中，Time Clock 组件直接通过 value 属性设置初始时间，通过 onChange 事件更新选择的时间值。

2. 属性详解

2.1 value 和 onChange

• value：当前时间值。一般为 Date 对象，用于表示组件当前选中的时间。
• onChange：时间更改时的回调函数，当用户选择新的时间时触发。

<TimeClock
  value={selectedTime}
  onChange={(newValue) => setSelectedTime(newValue)}
/>

2.2 ampm

• ampm：设置时间显示的 12 小时制或 24 小时制。默认为 true（12 小时制），设置为 false 时采用 24 小时制。

<TimeClock
  value={selectedTime}
  onChange={(newValue) => setSelectedTime(newValue)}
  ampm={false} // 24小时制
/>

2.3 minTime 和 maxTime

• minTime：允许选择的最小时间。
• maxTime：允许选择的最大时间。

此属性非常适合用来限定时间选择范围，例如活动的开放和关闭时间。

<TimeClock
  value={selectedTime}
  onChange={(newValue) => setSelectedTime(newValue)}
  minTime={new Date(0, 0, 0, 9, 0)} // 最小时间 9:00
  maxTime={new Date(0, 0, 0, 18, 0)} // 最大时间 18:00
/>

2.4 autoFocus

• autoFocus：设置为 true 时，Time Clock 会在渲染时自动获得焦点。

<TimeClock
  value={selectedTime}
  onChange={(newValue) => setSelectedTime(newValue)}
  autoFocus
/>

2.5 disabled

• disabled：禁用组件，用户无法进行选择。

<TimeClock
  value={selectedTime}
  onChange={(newValue) => setSelectedTime(newValue)}
  disabled
/>

2.6 readOnly

• readOnly：将组件设为只读，用户可以查看当前时间但无法更改。

<TimeClock
  value={selectedTime}
  onChange={(newValue) => setSelectedTime(newValue)}
  readOnly
/>

3. 高级用法

3.1 错误处理

可以使用 error 属性为用户提供输入错误提示。在 Material UI 中，可以通过包裹组件的外部组件来实现这种交互，例如 TextField 或 FormHelperText：

import { TextField, FormHelperText } from '@mui/material';

export default function ErrorHandlingTimeClock() {
  const [selectedTime, setSelectedTime] = useState(null);
  const [error, setError] = useState(false);

  const handleChange = (newValue) => {
    setSelectedTime(newValue);
    setError(newValue.getHours() < 9 || newValue.getHours() > 18); // 时间应在 9:00 - 18:00 之间
  };

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <TimeClock
        value={selectedTime}
        onChange={handleChange}
      />
      {error && <FormHelperText error>时间必须在9:00到18:00之间</FormHelperText>}
    </LocalizationProvider>
  );
}

3.2 国际化支持

使用 LocalizationProvider 的 locale 属性支持多语言，例如切换到中文界面：

import { zhCN } from 'date-fns/locale';

export default function ChineseTimeClock() {
  const [selectedTime, setSelectedTime] = useState(null);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns} locale={zhCN}>
      <TimeClock
        value={selectedTime}
        onChange={(newValue) => setSelectedTime(newValue)}
      />
    </LocalizationProvider>
  );
}

3.3 结合表单组件使用

结合表单组件进行提交和验证的示例如下：

import { Button } from '@mui/material';

export default function TimeClockForm() {
  const [selectedTime, setSelectedTime] = useState(null);

  const handleSubmit = (event) => {
    event.preventDefault();
    alert(`选择的时间: ${selectedTime}`);
  };

  return (
    <form onSubmit={handleSubmit}>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <TimeClock
          value={selectedTime}
          onChange={(newValue) => setSelectedTime(newValue)}
        />
      </LocalizationProvider>
      <Button type="submit" variant="contained" color="primary">
        提交
      </Button>
    </form>
  );
}

3.4 与 Grid 布局结合

结合 Grid 布局可以让 Time Clock 更加整齐地排列在页面上。以下示例展示了开始时间和结束时间选择的布局。

import Grid from '@mui/material/Grid';

export default function TimeClockWithGrid() {
  const [startTime, setStartTime] = useState(null);
  const [endTime, setEndTime] = useState(null);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <Grid container spacing={2}>
        <Grid item xs={6}>
          <TimeClock
            value={startTime}
            onChange={(newValue) => setStartTime(newValue)}
            label="开始时间"
          />
        </Grid>
        <Grid item xs={6}>
          <TimeClock
            value={endTime}
            onChange={(newValue) => setEndTime(newValue)}
            label="结束时间"
          />
        </Grid>
      </Grid>
    </LocalizationProvider>
  );
}

4. 总结

Time Clock 组件为用户提供了简洁的时间选择界面，并且可以通过自定义属性控制其展示效果。通过和表单及布局组件的结合，Time Clock 可以适应不同应用场景，提供友好的用户体验。