Matarialize中文技术社区-Material UI 组件 Date Range Picker 使用详解

Material UI 组件 Date Range Picker 使用详解

smartzeng 2024-10-27 19:38:09

155 Date Range Picker 专栏

Material UI 提供的 Date Range Picker 是一个非常实用的组件，用于选择两个日期之间的时间范围。在现代项目中，日期范围选择器被广泛应用于过滤、时间段选择等功能场景。本文将全面讲解 Date Range Picker 的使用，包括其属性、方法以及与其他组件结合的方式。

1. 准备工作

1.1 安装依赖

在使用 Date Range Picker 之前，确保安装了 @mui/x-date-pickers 包和日期适配器，如 date-fns：

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

1.2 基础引入

在 React 项目中导入相关组件和适配器，以便开始使用 Date Range Picker：

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

2. 基本用法

以下是一个简单的 Date Range Picker 示例，其中用户可以选择一个日期范围，并展示选择的开始和结束日期：

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

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

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateRangePicker
        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>
  );
}

3. 组件属性详解

3.1 `value` 和 `onChange`

value：设置选中的日期范围，格式为 [start, end]。
onChange：回调函数，返回用户选择的日期范围。

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

3.2 `startText` 和 `endText`

startText 和 endText：分别为开始和结束日期输入框的占位符文本。

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

3.3 `minDate` 和 `maxDate`

minDate 和 maxDate：限制日期范围，设置可选日期的最小和最大值。例如，限制只能选择未来的日期范围：

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

3.4 `disablePast` 和 `disableFuture`

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

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

3.5 `calendars`

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

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

3.6 `renderInput`

renderInput：用于自定义日期输入框。可以使用 TextField 作为输入框，同时自定义文本框的显示和样式。

renderInput={(startProps, endProps) => (
  <React.Fragment>
    <TextField {...startProps} />
    <Box sx={{ mx: 2 }}> 到 </Box>
    <TextField {...endProps} />
  </React.Fragment>
)}

3.7 `mask`

mask：设置输入格式的掩码，例如 __.__.____ 格式的日期输入。

<DateRangePicker
  mask="__.__.____"
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

4. 进阶用法

4.1 自定义日期格式

可以使用 inputFormat 来自定义日期格式，例如 dd/MM/yyyy：

<DateRangePicker
  inputFormat="dd/MM/yyyy"
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

4.2 动态禁用日期

通过 shouldDisableDate 禁用特定日期。例如禁用周末日期：

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

4.3 多语言支持

Date Range Picker 支持多语言，通过 LocalizationProvider 的 locale 属性设置。例如，以下代码使用中文（zhCN）显示日期：

import { zhCN } from 'date-fns/locale';

<LocalizationProvider dateAdapter={AdapterDateFns} locale={zhCN}>
  <DateRangePicker
    value={value}
    onChange={(newValue) => setValue(newValue)}
  />
</LocalizationProvider>

5. 实际应用场景

场景一：在表单中选择有效期范围

以下代码展示了表单中的有效期选择器，并进行表单验证，确保用户选择的范围大于等于 7 天：

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

export default function DateRangePickerForm() {
  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}>
        <DateRangePicker
          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 Picker 和数据表，可以实现数据筛选功能。例如，基于时间范围筛选表格数据：

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

export default function DateRangePickerWithDataGrid() {
  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}>
        <DateRangePicker
          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>
  );
}

6. 总结

Date Range Picker 是 Material UI 中强大且实用的日期范围选择器组件。本文涵盖了其主要属性、方法和应用场景，通过丰富的代码示例演示了该组件在表单、数据过滤等场景中的具体实现方法。希望通过本篇内容，能够帮助您在实际项目中更好地应用 Date Range Picker 组件。

评论区