Material UI 是 React 开发者常用的 UI 解决方案，其中的日期与时间选择器为开发者提供了丰富的组件和定制选项。在 DateTimeRangePicker 组件中，DateTimeRangePickerToolbar API 用于自定义工具栏的外观和行为。

本篇博客将详细介绍 DateTimeRangePickerToolbar API 的使用方法，包括其属性、方法、示例代码，以及与其他组件的结合使用。

1. 什么是 DateTimeRangePickerToolbar API？

DateTimeRangePickerToolbar 是 DateTimeRangePicker 的一部分，用于提供用户界面顶部的工具栏，显示选择范围的起始和结束时间，并支持自定义标题、操作按钮等内容。

通过使用 DateTimeRangePickerToolbar API，开发者可以自由定义工具栏的样式、行为和显示内容，以更好地适应业务需求。

2. 安装必要的依赖

在开始使用之前，请确保已安装以下依赖项：

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

3. 基础使用示例

默认情况下，DateTimeRangePicker 包含一个内置的工具栏。通过 components.Toolbar 属性，可以自定义或替换默认工具栏。

示例：基本的 DateTimeRangePickerToolbar 使用

以下是一个简单的 DateTimeRangePicker 示例，其中使用默认的 DateTimeRangePickerToolbar：

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';

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

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => setValue(newValue)}
      />
    </LocalizationProvider>
  );
};

export default BasicDateTimeRangePickerToolbar;

此示例展示了默认的工具栏，显示选定的开始和结束时间。

4. DateTimeRangePickerToolbar API 的主要属性

以下是 DateTimeRangePickerToolbar API 提供的主要属性和方法：

5. 高级示例

示例 1：自定义工具栏标题和文本

通过 startText、endText 和 toolbarTitle 属性，可以设置工具栏显示的内容。

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';

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

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => setValue(newValue)}
        components={{
          Toolbar: (props) => (
            <DateTimeRangePickerToolbar
              {...props}
              toolbarTitle="选择日期时间范围"
              startText="开始时间"
              endText="结束时间"
            />
          ),
        }}
      />
    </LocalizationProvider>
  );
};

export default CustomToolbarText;

示例 2：自定义工具栏样式

通过 sx 属性，可以为工具栏添加自定义样式。

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';

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

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => setValue(newValue)}
        components={{
          Toolbar: (props) => (
            <DateTimeRangePickerToolbar
              {...props}
              toolbarTitle="日期时间选择"
              sx={{
                backgroundColor: '#1976d2',
                color: 'white',
                padding: '16px',
              }}
            />
          ),
        }}
      />
    </LocalizationProvider>
  );
};

export default StyledToolbar;

示例 3：与其他组件结合使用

通过 componentsProps 属性，可以将工具栏与其他组件结合，例如添加一个重置按钮。

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 Button from '@mui/material/Button';

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

  const handleReset = () => {
    setValue([null, null]);
  };

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => setValue(newValue)}
        components={{
          Toolbar: (props) => (
            <DateTimeRangePickerToolbar
              {...props}
              componentsProps={{
                actions: (
                  <Button
                    onClick={handleReset}
                    style={{ marginLeft: 'auto', color: 'white' }}
                  >
                    重置
                  </Button>
                ),
              }}
            />
          ),
        }}
      />
    </LocalizationProvider>
  );
};

export default ToolbarWithResetButton;

6. 与其他组件的结合

DateTimeRangePickerToolbar 可以与表单、图表或其他 Material UI 组件结合使用。

示例：结合表单验证

以下示例展示了如何在工具栏中显示表单验证错误信息：

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 Typography from '@mui/material/Typography';

const ToolbarWithValidation = () => {
  const [value, setValue] = useState([null, null]);
  const [error, setError] = useState('');

  const validate = (newValue) => {
    if (newValue[0] && newValue[1] && newValue[0] > newValue[1]) {
      setError('开始时间不能晚于结束时间');
    } else {
      setError('');
    }
  };

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimeRangePicker
        value={value}
        onChange={(newValue) => {
          setValue(newValue);
          validate(newValue);
        }}
        components={{
          Toolbar: (props) => (
            <DateTimeRangePickerToolbar
              {...props}
              componentsProps={{
                title: (
                  error ? (
                    <Typography color="error">{error}</Typography>
                  ) : (
                    <Typography>选择时间范围</Typography>
                  )
                ),
              }}
            />
          ),
        }}
      />
    </LocalizationProvider>
  );
};

export default ToolbarWithValidation;

7. 注意事项

1. 状态管理：确保工具栏的状态与主组件的状态同步。
2. 样式一致性：自定义样式时，保持与整体设计一致。
3. 合理的错误处理：在工具栏中显示错误信息时，确保用户能够轻松理解并解决问题。

8. 总结

通过 DateTimeRangePickerToolbar API，开发者可以自由定制日期时间范围选择器的工具栏内容、样式和交互行为。在结合其他组件时，可以创造出更加灵活和强大的用户界面。

希望本文中的详细说明和代码示例能帮助你充分掌握 DateTimeRangePickerToolbar API 的使用技巧！