Time Range Field 是 Material UI 框架中的一个时间范围输入组件，允许用户选择一段时间，适用于需要时间段选择的场景，比如排程、过滤和数据分析等。本文将详细介绍 Time Range Field 的使用方法、属性配置，以及与其他组件的结合应用，通过多个代码示例展示其灵活性和强大功能。

1. 前期准备

确保项目中安装了 @mui/material 和 @mui/x-date-pickers 以及时间适配器库 date-fns：

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

在组件中应用时，还需要使用 LocalizationProvider 来提供时间的国际化适配功能，并选择适配器。

2. Time Range Field 基本使用

以下是一个最基础的 Time Range Field 组件实例：

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

function BasicTimeRangeField() {
  const [timeRange, setTimeRange] = useState([null, null]);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <TimeRangeField
        value={timeRange}
        onChange={(newRange) => setTimeRange(newRange)}
        label="选择时间范围"
        format="HH:mm"
      />
    </LocalizationProvider>
  );
}

export default BasicTimeRangeField;

代码解析

• value: 绑定时间范围的状态。
• onChange: 处理时间范围变化的函数。
• label: 输入框的标签。
• format: 显示时间的格式。

3. Time Range Field 属性详解

3.1 value 和 onChange

• value: 时间范围数组，格式为 [startTime, endTime]。
• onChange: 事件回调函数，当用户选择新的时间范围时触发。

<TimeRangeField
  value={timeRange}
  onChange={(newRange) => setTimeRange(newRange)}
/>

3.2 minTime 和 maxTime

• minTime: 限制用户选择的开始时间。
• maxTime: 限制用户选择的结束时间。

<TimeRangeField
  minTime={new Date(2023, 0, 1, 8, 0)} // 从早上8点开始
  maxTime={new Date(2023, 0, 1, 17, 0)} // 到下午5点结束
  value={timeRange}
  onChange={(newRange) => setTimeRange(newRange)}
/>

3.3 shouldDisableTime

• shouldDisableTime: 自定义时间禁用逻辑，可以根据特定需求禁用某些时间。例如，禁用午休时间（中午12点到1点）：

<TimeRangeField
  shouldDisableTime={(time) => {
    const hour = time.getHours();
    return hour === 12; // 禁用12点
  }}
  value={timeRange}
  onChange={(newRange) => setTimeRange(newRange)}
/>

3.4 localeText 属性

• localeText: 自定义输入框中显示的文字，比如开始时间和结束时间的提示文本。

<TimeRangeField
  localeText={{ start: '开始时间', end: '结束时间' }}
  value={timeRange}
  onChange={(newRange) => setTimeRange(newRange)}
/>

3.5 样式调整

可以通过 Material UI 的 sx 属性来自定义 Time Range Field 的样式。例如，设置时间范围输入框的背景色和字体颜色：

<TimeRangeField
  sx={{
    backgroundColor: '#f5f5f5',
    color: '#333',
    '& .Mui-selected': {
      backgroundColor: '#1976d2',
      color: '#fff',
    }
  }}
  value={timeRange}
  onChange={(newRange) => setTimeRange(newRange)}
/>

4. 进阶示例与应用场景

场景一：带有时间范围的表单

以下示例展示了一个表单，其中包含了 Time Range Field，并在表单提交时校验时间范围：

import React, { useState } from 'react';
import { Button, TextField } from '@mui/material';

function TimeRangeForm() {
  const [timeRange, setTimeRange] = useState([null, null]);
  const [error, setError] = useState(false);

  const handleSubmit = (e) => {
    e.preventDefault();
    const [start, end] = timeRange;
    if (!start || !end) {
      setError(true);
    } else {
      setError(false);
      alert(`选择的时间范围：${start.toLocaleTimeString()} - ${end.toLocaleTimeString()}`);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <TimeRangeField
          value={timeRange}
          onChange={(newRange) => setTimeRange(newRange)}
          label="选择时间范围"
        />
      </LocalizationProvider>
      {error && <p style={{ color: 'red' }}>请选择完整的时间范围</p>}
      <Button type="submit" variant="contained" color="primary">提交</Button>
    </form>
  );
}

export default TimeRangeForm;

场景二：与数据表格结合

在数据分析应用中，可以结合 DataGrid 和 Time Range Field 实现基于时间范围的过滤功能：

import React, { useState } from 'react';
import { DataGrid } from '@mui/x-data-grid';
import { Button } from '@mui/material';

const initialData = [
  { id: 1, name: 'Alice', time: new Date(2023, 0, 1, 9, 0) },
  { id: 2, name: 'Bob', time: new Date(2023, 0, 1, 14, 30) },
  // 更多数据...
];

function TimeRangeFilterTable() {
  const [timeRange, setTimeRange] = useState([null, null]);
  const [filteredData, setFilteredData] = useState(initialData);

  const handleFilter = () => {
    if (timeRange[0] && timeRange[1]) {
      const [start, end] = timeRange;
      const newData = initialData.filter((row) => {
        return row.time >= start && row.time <= end;
      });
      setFilteredData(newData);
    }
  };

  return (
    <div>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <TimeRangeField
          value={timeRange}
          onChange={(newRange) => setTimeRange(newRange)}
        />
      </LocalizationProvider>
      <Button variant="contained" onClick={handleFilter}>应用过滤</Button>
      <DataGrid rows={filteredData} columns={[{ field: 'id' }, { field: 'name' }, { field: 'time', type: 'dateTime' }]} />
    </div>
  );
}

export default TimeRangeFilterTable;

场景三：时间限制的时间范围选择

以下代码示例展示了如何设置时间范围的最小和最大时间，用于限制用户只能选择特定时间段内的时间范围。

<TimeRangeField
  minTime={new Date(2023, 0, 1, 9, 0)} // 从早上9点开始
  maxTime={new Date(2023, 0, 1, 18, 0)} // 到下午6点结束
  value={timeRange}
  onChange={(newRange) => setTimeRange(newRange)}
/>

5. 总结

Material UI 中的 Time Range Field 组件为时间范围选择提供了灵活且高效的解决方案。本文详细介绍了其主要属性、方法以及在不同场景中的应用，并展示了如何结合表单、数据表格等其他组件使用。掌握这些方法，能够帮助开发者在项目中实现自定义的时间范围选择功能。希望本文对你在实际项目中应用 Time Range Field 组件有所帮助。