DateTimeRangePicker 是 Material UI 的日期时间范围选择器组件，允许用户选择一个时间段的开始和结束日期时间。在需要选择时间范围的场景中，比如预订、数据筛选、活动安排等，DateTimeRangePicker 是一个强大的工具。

本文将详细介绍 DateTimeRangePicker 的使用，包括其主要属性、方法及其与其他组件的结合方式。通过丰富的代码示例，帮助你全面掌握这一组件。

1. 组件简介

DateTimeRangePicker 提供了一种直观的用户界面，用于选择两个日期时间值（开始日期和结束日期）。它在 Material UI 的 @mui/x-date-pickers 扩展包中提供。

2. 安装和配置

要使用 DateTimeRangePicker，首先确保安装了必要的依赖项：

npm install @mui/material @mui/x-date-pickers @emotion/react @emotion/styled

接着配置适配器，比如 AdapterDateFns：

import { LocalizationProvider } from '@mui/x-date-pickers';
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';

3. DateTimeRangePicker 的主要 API

DateTimeRangePicker 支持丰富的属性和事件，用于自定义其行为。以下是其关键属性的说明：

4. 使用示例

示例 1：基本使用

以下是一个基本的 DateTimeRangePicker 示例：

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

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

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

export default BasicDateTimeRangePicker;

此示例中，用户可以选择日期时间范围，并显示在两个输入框中。

示例 2：限制日期时间范围

通过 minDateTime 和 maxDateTime 限制可选范围：

<DateTimeRangePicker
  value={value}
  onChange={(newValue) => setValue(newValue)}
  minDateTime={new Date(2023, 0, 1)}
  maxDateTime={new Date(2023, 11, 31)}
  renderInput={(startProps, endProps) => (
    <>
      <TextField {...startProps} label="开始日期时间" />
      <TextField {...endProps} label="结束日期时间" style={{ marginLeft: 8 }} />
    </>
  )}
/>

示例 3：禁用过去和未来的日期时间

使用 disablePast 和 disableFuture 禁用无效时间范围：

<DateTimeRangePicker
  value={value}
  onChange={(newValue) => setValue(newValue)}
  disablePast
  disableFuture
  renderInput={(startProps, endProps) => (
    <>
      <TextField {...startProps} label="开始日期时间" />
      <TextField {...endProps} label="结束日期时间" style={{ marginLeft: 8 }} />
    </>
  )}
/>

示例 4：自定义工具栏

通过 components 属性，可以自定义工具栏外观和行为：

import React from 'react';
import { DateTimeRangePicker } from '@mui/x-date-pickers-pro';
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns';
import TextField from '@mui/material/TextField';
import Typography from '@mui/material/Typography';

const CustomToolbar = (props) => {
  return (
    <div style={{ padding: 16, backgroundColor: '#1976d2', color: 'white' }}>
      <Typography variant="h6">选择日期时间范围</Typography>
    </div>
  );
};

const CustomToolbarDateTimeRangePicker = () => {
  const [value, setValue] = React.useState([null, null]);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => setValue(newValue)}
        components={{
          Toolbar: CustomToolbar,
        }}
        renderInput={(startProps, endProps) => (
          <>
            <TextField {...startProps} label="开始日期时间" />
            <TextField {...endProps} label="结束日期时间" style={{ marginLeft: 8 }} />
          </>
        )}
      />
    </LocalizationProvider>
  );
};

export default CustomToolbarDateTimeRangePicker;

此示例展示了如何替换默认工具栏，并应用自定义样式。

示例 5：结合表单和按钮

以下示例展示了 DateTimeRangePicker 如何与表单提交结合：

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

const FormWithDateTimeRangePicker = () => {
  const [value, setValue] = useState([null, null]);

  const handleSubmit = () => {
    alert(`Selected range: ${value[0]} - ${value[1]}`);
  };

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => setValue(newValue)}
        renderInput={(startProps, endProps) => (
          <>
            <TextField {...startProps} label="开始日期时间" />
            <TextField {...endProps} label="结束日期时间" style={{ marginLeft: 8 }} />
          </>
        )}
      />
      <Button
        variant="contained"
        color="primary"
        onClick={handleSubmit}
        style={{ marginTop: 16 }}
      >
        提交
      </Button>
    </LocalizationProvider>
  );
};

export default FormWithDateTimeRangePicker;

5. 注意事项

1. 验证日期时间范围：确保用户选择的开始时间小于结束时间。
2. 支持本地化：通过 localeText 自定义日期时间选择器的提示文本和标签。
3. 性能优化：在大数据场景中，限制日期时间范围以提高性能。

6. 总结

DateTimeRangePicker 是 Material UI 提供的强大日期时间范围选择组件，支持高度的可定制性和广泛的应用场景。通过本文介绍的详细 API、属性说明和示例代码，你可以轻松将其集成到项目中，为用户提供优秀的交互体验。

希望本文能够帮助你全面掌握 DateTimeRangePicker 的使用！