Date Range Calendar 是 Material UI 框架中的日期范围选择器组件，提供了直观的日期范围选择功能，适合用于数据筛选、报表生成和时间段选择等场景。本文将详细介绍 Date Range Calendar 组件的使用方法、属性配置和应用场景，通过多个代码示例展示其灵活的定制和与其他组件的集成。

1. 前期准备

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

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

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

2. Date Range Calendar 基本使用

以下是一个最基础的 Date Range Calendar 组件实例：

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

function BasicDateRangeCalendar() {
  const [dateRange, setDateRange] = useState([null, null]);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateRangeCalendar
        value={dateRange}
        onChange={(newRange) => setDateRange(newRange)}
      />
    </LocalizationProvider>
  );
}

export default BasicDateRangeCalendar;

在这个示例中，DateRangeCalendar 组件允许用户选择一个日期范围：

• value: 表示当前选择的日期范围。
• onChange: 用于处理日期范围的更新。

3. Date Range Calendar 属性详解

3.1 value 和 onChange

• value: 日期范围数组格式的值，例如 [startDate, endDate]。
• onChange: 事件回调函数，用于响应用户选择的日期范围。

<DateRangeCalendar
  value={dateRange}
  onChange={(newRange) => setDateRange(newRange)}
/>

3.2 minDate 和 maxDate

• minDate 和 maxDate：限制用户选择的日期范围。

<DateRangeCalendar
  minDate={new Date(2022, 0, 1)}
  maxDate={new Date(2023, 11, 31)}
  value={dateRange}
  onChange={(newRange) => setDateRange(newRange)}
/>

3.3 calendars

• calendars: 显示的日历数量（默认值为 2）。通过设置为 1 或 3 可以调整所展示的日历个数。

<DateRangeCalendar
  calendars={1}
  value={dateRange}
  onChange={(newRange) => setDateRange(newRange)}
/>

3.4 disablePast 和 disableFuture

• disablePast：禁用选择今天之前的日期。
• disableFuture：禁用选择未来日期。

<DateRangeCalendar
  disablePast
  value={dateRange}
  onChange={(newRange) => setDateRange(newRange)}
/>

3.5 shouldDisableDate

• shouldDisableDate：自定义日期禁用的逻辑。可以根据特定需求禁用特定日期。例如，禁用所有周末日期：

<DateRangeCalendar
  shouldDisableDate={(date) => date.getDay() === 0 || date.getDay() === 6}
  value={dateRange}
  onChange={(newRange) => setDateRange(newRange)}
/>

3.6 localeText 属性

• localeText: 设置日历中显示的文字，例如开始日期和结束日期的提示文本。

<DateRangeCalendar
  localeText={{ start: '开始日期', end: '结束日期' }}
  value={dateRange}
  onChange={(newRange) => setDateRange(newRange)}
/>

3.7 Date Range Calendar 组件中的样式调整

可以通过 Material UI 的 sx 属性来自定义 Date Range Calendar 的样式。例如，将日历的背景色和字体颜色进行自定义：

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

4. 进阶示例与应用场景

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

以下示例展示了一个表单，其中包含了 Date Range Calendar，并在表单提交时校验日期范围：

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

function DateRangeForm() {
  const [dateRange, setDateRange] = useState([null, null]);
  const [error, setError] = useState(false);

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

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

export default DateRangeForm;

场景二：与数据表格结合

在数据分析应用中，可以结合 DataGrid 和 DateRangeCalendar 实现基于日期范围的过滤功能：

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

const initialData = [
  { id: 1, name: 'Alice', date: new Date(2023, 3, 14) },
  { id: 2, name: 'Bob', date: new Date(2023, 6, 23) },
  // 更多数据...
];

function DateRangeFilterTable() {
  const [dateRange, setDateRange] = useState([null, null]);
  const [filteredData, setFilteredData] = useState(initialData);

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

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

export default DateRangeFilterTable;

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

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

<DateRangeCalendar
  minDate={new Date(2022, 0, 1)}
  maxDate={new Date(2023, 11, 31)}
  value={dateRange}
  onChange={(newRange) => setDateRange(newRange)}
/>

5. 总结

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