Material UI 组件 Date Range Field 使用详解

person  smartzeng    watch_later 2024-10-27 19:45:36
visibility 43    class Date Range Field    bookmark 专栏

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>
  );
}

在此示例中:

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

3. 组件属性详解

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

3.1 valueonChange

  • value:表示用户选择的日期范围,格式为 [startDate, endDate]
  • onChange:回调函数,返回用户选择的日期范围。
<DateRangeField
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.2 startTextendText

  • startTextendText:用于指定开始和结束日期输入框的提示文本。
<DateRangeField
  startText="开始日期"
  endText="结束日期"
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.3 minDatemaxDate

  • minDatemaxDate:用于限制日期范围的最小和最大值。例如,限制用户只能选择未来日期范围:
<DateRangeField
  minDate={new Date()}
  maxDate={new Date(2025, 11, 31)}
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.4 disablePastdisableFuture

  • disablePast:禁用选择过去的日期。
  • disableFuture:禁用选择未来的日期。
<DateRangeField
  disablePast
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.5 calendars

  • calendars:设置显示的日历数量,默认为 2。可以根据需求调整为 13
<DateRangeField
  calendars={1}
  value={value}
  onChange={(newValue) => setValue(newValue)}
/>

3.6 inputFormatmask

  • 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,从而提高日期选择的用户体验。

chat评论区
评论列表
menu