Date Time Range Picker 是 Material UI 框架中的一个强大组件，允许用户选择一个日期和时间的范围。它适用于需要选择时间段的场景，如日程安排、数据筛选和报告生成等。本文将详细介绍 Date Time Range Picker 的使用方法、属性、以及如何与其他组件结合应用，示例代码将涵盖其所有功能。

1. 前期准备

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

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

1.1 导入组件

在使用 Date Time Range Picker 之前，你需要从相应的库中导入所需的组件和适配器：

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

2. 基本使用示例

下面是一个基础的 Date Time Range Picker 示例，展示了如何创建一个简单的日期时间范围选择器：

function BasicDateTimeRangePicker() {
  const [value, setValue] = useState([null, null]);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => setValue(newValue)}
        renderInput={(startProps, endProps) => (
          <>
            <TextField {...startProps} label="开始时间" variant="outlined" />
            <TextField {...endProps} label="结束时间" variant="outlined" />
          </>
        )}
      />
    </LocalizationProvider>
  );
}

export default BasicDateTimeRangePicker;

代码解析

• value: 用于存储选择的日期时间范围。
• onChange: 更新日期时间范围的函数。
• renderInput: 自定义输入框的渲染方式，可以根据需要定制。

3. 属性详解

3.1 value 和 onChange

• value: 需要传入一个数组，格式为 [startDate, endDate]。
• onChange: 当用户选择新的日期时间范围时触发的回调函数。

3.2 minDateTime 和 maxDateTime

• minDateTime: 限制选择的最早日期和时间。
• maxDateTime: 限制选择的最晚日期和时间。

<DateTimeRangePicker
  minDateTime={new Date(2023, 0, 1, 0, 0)} // 从2023年1月1日0点开始
  maxDateTime={new Date(2023, 11, 31, 23, 59)} // 到2023年12月31日23点59分结束
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.3 shouldDisableDate

• shouldDisableDate: 自定义逻辑以禁用某些特定日期。

<DateTimeRangePicker
  shouldDisableDate={(date) => date.getDay() === 0} // 禁用所有周日
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.4 localeText

• localeText: 自定义显示的文本，比如输入框的提示文本。

<DateTimeRangePicker
  localeText={{ start: '开始时间', end: '结束时间' }}
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.5 样式调整

使用 sx 属性来自定义组件的样式，例如设置背景色和字体颜色：

<DateTimeRangePicker
  sx={{
    '& .MuiOutlinedInput-root': {
      backgroundColor: '#f5f5f5',
    }
  }}
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

4. 进阶示例与应用场景

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

以下示例展示了一个包含 DateTimeRangePicker 的表单，当用户提交时校验日期时间范围：

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

function DateTimeRangeForm() {
  const [value, setValue] = useState([null, null]);
  const [error, setError] = useState(false);

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

  return (
    <form onSubmit={handleSubmit}>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <DateTimeRangePicker
          value={value}
          onChange={(newValue) => setValue(newValue)}
          renderInput={(startProps, endProps) => (
            <>
              <TextField {...startProps} label="开始时间" variant="outlined" />
              <TextField {...endProps} label="结束时间" variant="outlined" />
            </>
          )}
        />
      </LocalizationProvider>
      {error && <p style={{ color: 'red' }}>请选择完整的日期时间范围</p>}
      <Button type="submit" variant="contained" color="primary">提交</Button>
    </form>
  );
}

export default DateTimeRangeForm;

场景二：与数据表格结合使用

在数据分析场景中，可以结合 DataGrid 和 DateTimeRangePicker 实现基于时间范围的筛选功能：

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

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

function DateTimeRangeFilterTable() {
  const [value, setValue] = useState([null, null]);
  const [filteredData, setFilteredData] = useState(initialData);

  const handleFilter = () => {
    if (value[0] && value[1]) {
      const newData = initialData.filter((row) => {
        return row.dateTime >= value[0] && row.dateTime <= value[1];
      });
      setFilteredData(newData);
    }
  };

  return (
    <div>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <DateTimeRangePicker
          value={value}
          onChange={(newValue) => setValue(newValue)}
          renderInput={(startProps, endProps) => (
            <>
              <TextField {...startProps} label="开始时间" variant="outlined" />
              <TextField {...endProps} label="结束时间" variant="outlined" />
            </>
          )}
        />
      </LocalizationProvider>
      <Button variant="contained" onClick={handleFilter}>应用过滤</Button>
      <DataGrid rows={filteredData} columns={[{ field: 'id' }, { field: 'name' }, { field: 'dateTime', type: 'dateTime' }]} />
    </div>
  );
}

export default DateTimeRangeFilterTable;

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

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

<DateTimeRangePicker
  minDateTime={new Date(2023, 0, 1, 0, 0)} // 从2023年1月1日0点开始
  maxDateTime={new Date(2023, 11, 31, 23, 59)} // 到2023年12月31日23点59分结束
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

5. 总结

Material UI 中的 Date Time Range Picker 组件提供了灵活且强大的日期和时间范围选择功能。通过本文的详细介绍，包括基本用法、属性配置以及与其他组件结合的示例，开发者可以轻松实现复杂的时间选择需求。希望本文对你在项目中使用 Date Time Range Picker 组件有所帮助，助你在开发中事半功倍！