Date Range Field 是 Material UI 框架中提供的一个日期范围选择输入组件，用于高效地输入和处理两个日期之间的时间范围。在现代前端开发中，日期范围的选择在报表、时间过滤和数据筛选等功能中应用广泛。本文将深入介绍 Date Range Field 的属性、方法、基本用法及应用场景，并提供详细示例代码，帮助开发者轻松集成和使用。

1. 前期准备

在开始使用 Date Range Field 组件之前，请确保项目中已经安装了 @mui/material 和 @mui/x-date-pickers 以及日期适配器库 date-fns：

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

2. 组件的基本使用

首先导入 Date Range Field 组件及必要的适配器：

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

在初始化组件时，可以通过 LocalizationProvider 提供日期的国际化适配功能。

示例代码：基本的 Date Range Field

以下代码展示了一个基本的 Date Range Field 组件实例，允许用户选择开始日期和结束日期：

export default function BasicDateRangeField() {
  const [value, setValue] = useState([null, null]);

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateRangeField
        startText="开始日期"
        endText="结束日期"
        value={value}
        onChange={(newValue) => setValue(newValue)}
        renderInput={(startProps, endProps) => (
          <React.Fragment>
            <TextField {...startProps} />
            <Box sx={{ mx: 2 }}> 到 </Box>
            <TextField {...endProps} />
          </React.Fragment>
        )}
      />
    </LocalizationProvider>
  );
}

在此示例中：

• startText 和 endText 分别用于指定开始和结束日期输入框的占位文本。
• renderInput 自定义了输入框的显示样式，并通过 <Box /> 组件实现了输入框之间的分隔。

3. 组件属性详解

Date Range Field 组件提供了多个属性，方便开发者对日期选择的逻辑、样式和限制进行自定义设置。

3.1 value 和 onChange

• value：表示用户选择的日期范围，格式为 [startDate, endDate]。
• onChange：回调函数，返回用户选择的日期范围。

<DateRangeField
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.2 startText 和 endText

• startText 和 endText：用于指定开始和结束日期输入框的提示文本。

<DateRangeField
  startText="开始日期"
  endText="结束日期"
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.3 minDate 和 maxDate

• minDate 和 maxDate：用于限制日期范围的最小和最大值。例如，限制用户只能选择未来日期范围：

<DateRangeField
  minDate={new Date()}
  maxDate={new Date(2025, 11, 31)}
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.4 disablePast 和 disableFuture

• disablePast：禁用选择过去的日期。
• disableFuture：禁用选择未来的日期。

<DateRangeField
  disablePast
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.5 calendars

• calendars：设置显示的日历数量，默认为 2。可以根据需求调整为 1 或 3。

<DateRangeField
  calendars={1}
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.6 inputFormat 和 mask

• inputFormat：自定义日期显示格式，例如 dd/MM/yyyy。
• mask：设置输入的掩码，例如 __.__.____ 格式的日期输入框。

<DateRangeField
  inputFormat="dd/MM/yyyy"
  mask="__.__.____"
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.7 shouldDisableDate

• shouldDisableDate：可以设置禁用特定日期。例如禁用所有周末：

<DateRangeField
  shouldDisableDate={(date) => date.getDay() === 0 || date.getDay() === 6}
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

4. 应用场景和进阶示例

场景一：表单中的日期范围选择

以下代码展示了在表单中使用 Date Range Field 的方法，并添加了验证，确保用户选择的日期范围至少为 7 天：

import { Button } from '@mui/material';

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

  const handleSubmit = (event) => {
    event.preventDefault();
    const [start, end] = value;
    if (end && start && (end - start) / (1000 * 60 * 60 * 24) < 7) {
      setError(true);
    } else {
      setError(false);
      alert(`选择的日期范围是：${start.toLocaleDateString()} 到 ${end.toLocaleDateString()}`);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <DateRangeField
          startText="开始日期"
          endText="结束日期"
          value={value}
          onChange={(newValue) => setValue(newValue)}
          renderInput={(startProps, endProps) => (
            <>
              <TextField {...startProps} error={error} />
              <Box sx={{ mx: 2 }}> 到 </Box>
              <TextField {...endProps} error={error} />
            </>
          )}
        />
      </LocalizationProvider>
      {error && <p style={{ color: 'red' }}>日期范围必须大于 7 天</p>}
      <Button type="submit" variant="contained">提交</Button>
    </form>
  );
}

场景二：数据表中的日期范围筛选

在数据表筛选中，结合 Date Range Field，可以实现基于日期范围的筛选功能。例如，筛选日期在选择范围内的行：

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

export default function DateRangeFieldWithDataGrid() {
  const [value, setValue] = useState([null, null]);
  const [filteredData, setFilteredData] = useState(data);

  const handleFilter = () => {
    if (value[0] && value[1]) {
      const [start, end] = value;
      setFilteredData(
        data.filter((row) => {
          const date = new Date(row.date);
          return date >= start && date <= end;
        })
      );
    }
  };

  return (
    <div>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <DateRangeField
          startText="开始日期"
          endText="结束日期"
          value={value}
          onChange={(newValue) => setValue(newValue)}
          renderInput={(startProps, endProps) => (
            <>
              <TextField {...startProps} />
              <Box sx={{ mx: 2 }}> 到 </Box>
              <TextField {...endProps} />
            </>
          )}
        />
      </LocalizationProvider>
      <Button onClick={handleFilter} variant="contained">筛选</Button>
      <DataGrid rows={filteredData} columns={columns} />
    </div>
  );
}

5. 总结

Date Range Field 是 Material UI 中强大而灵活的日期范围选择器，本文详细介绍了其属性和方法，通过多个代码示例展示了在表单验证、数据表筛选等场景下的应用。希望本文能帮助你更好地理解并在实际项目中应用 Date Range Field，从而提高日期选择的用户体验。