Matarialize中文技术社区-Material UI 框架之 DateTime Picker 组件详解

Material UI 框架之 DateTime Picker 组件详解

smartzeng 2024-10-27 12:54:18

305 DateTime Picker 专栏

Material UI 提供的 DateTime Picker 组件用于同时选择日期和时间。它可以直观显示当前日期时间，且支持定制化选项，适合用户在预约系统、倒计时等需要精确选择日期时间的场景中使用。本文将详细介绍 DateTime Picker 的使用，涵盖组件的基本用法、属性、方法及与其他组件的结合应用。

1. 基础用法

1.1 安装依赖

首先，确保已经安装了 @mui/x-date-pickers 和 date-fns，用于日期时间格式的处理：

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

1.2 基础用法示例

在基础用法中，DateTimePicker 用于选择当前的日期和时间，通过 onChange 更新时间值。

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

export default function BasicDateTimePicker() {
  const [selectedDateTime, setSelectedDateTime] = useState(new Date());

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimePicker
        value={selectedDateTime}
        onChange={(newValue) => setSelectedDateTime(newValue)}
        label="选择日期和时间"
      />
    </LocalizationProvider>
  );
}

以上代码展示了 DateTimePicker 的基本用法，通过 LocalizationProvider 包裹 DateTimePicker 组件，提供时间适配器 AdapterDateFns。

2. 组件属性详解

2.1 `value` 和 `onChange`

value：用于指定日期和时间的默认值，通常为 Date 对象。
onChange：选择日期时间后触发的回调函数，用于更新日期时间值。

<DateTimePicker
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
/>

2.2 `minDateTime` 和 `maxDateTime`

minDateTime 和 maxDateTime：用于限制用户可以选择的日期时间范围。

<DateTimePicker
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  minDateTime={new Date(2024, 0, 1, 9, 0)} // 最早 2024-01-01 09:00
  maxDateTime={new Date(2024, 11, 31, 18, 0)} // 最晚 2024-12-31 18:00
/>

2.3 `ampm`

ampm：设定时间格式，true 为 12 小时制，false 为 24 小时制。

<DateTimePicker
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  ampm={false} // 24 小时制
/>

2.4 `disabled`

disabled：布尔值，用于禁用组件，防止用户交互。

<DateTimePicker
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  disabled
/>

2.5 `readOnly`

readOnly：将组件设置为只读模式，允许用户查看但不能更改日期时间。

<DateTimePicker
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  readOnly
/>

2.6 `openTo`

openTo：设置初次打开时显示的视图，day、month、year 和 hours 可选。

<DateTimePicker
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  openTo="year"
/>

3. 进阶用法

3.1 错误提示

通过 FormHelperText 显示错误信息，防止用户选择无效日期时间。例如：限制选择时间在工作日内。

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

export default function DateTimePickerWithValidation() {
  const [selectedDateTime, setSelectedDateTime] = useState(new Date());
  const [error, setError] = useState(false);

  const handleChange = (newValue) => {
    setSelectedDateTime(newValue);
    setError(newValue.getHours() < 9 || newValue.getHours() > 18);
  };

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <DateTimePicker
        value={selectedDateTime}
        onChange={handleChange}
        label="选择日期和时间"
      />
      {error && <FormHelperText error>请选择工作时间（9:00-18:00）</FormHelperText>}
    </LocalizationProvider>
  );
}

3.2 多语言支持

通过 LocalizationProvider 的 locale 属性切换到其他语言，例如中文：

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

export default function DateTimePickerWithLocalization() {
  const [selectedDateTime, setSelectedDateTime] = useState(new Date());

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns} locale={zhCN}>
      <DateTimePicker
        value={selectedDateTime}
        onChange={(newValue) => setSelectedDateTime(newValue)}
        label="选择日期和时间"
      />
    </LocalizationProvider>
  );
}

3.3 与表单组件结合

可以将 DateTimePicker 与表单组件结合，完成表单数据的提交处理：

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

export default function FormWithDateTimePicker() {
  const [selectedDateTime, setSelectedDateTime] = useState(new Date());

  const handleSubmit = (event) => {
    event.preventDefault();
    alert(`提交的时间是: ${selectedDateTime}`);
  };

  return (
    <form onSubmit={handleSubmit}>
      <LocalizationProvider dateAdapter={AdapterDateFns}>
        <DateTimePicker
          value={selectedDateTime}
          onChange={(newValue) => setSelectedDateTime(newValue)}
          label="选择日期和时间"
        />
      </LocalizationProvider>
      <Button type="submit" variant="contained" color="primary">
        提交
      </Button>
    </form>
  );
}

3.4 自定义外观

可以通过 sx 属性自定义组件样式，使其适应页面的整体设计风格：

<DateTimePicker
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  sx={{
    width: '100%',
    backgroundColor: 'lightgray',
    '& .MuiInputBase-input': {
      color: 'blue',
    },
  }}
/>

3.5 Grid 布局结合使用

使用 Grid 布局将多个 DateTimePicker 组件排列在页面中，例如创建一个选择起始时间和结束时间的表单：

import Grid from '@mui/material/Grid';

export default function DateTimePickerGridExample() {
  const [startDateTime, setStartDateTime] = useState(new Date());
  const [endDateTime, setEndDateTime] = useState(new Date());

  return (
    <LocalizationProvider dateAdapter={AdapterDateFns}>
      <Grid container spacing={2}>
        <Grid item xs={6}>
          <DateTimePicker
            value={startDateTime}
            onChange={(newValue) => setStartDateTime(newValue)}
            label="开始时间"
          />
        </Grid>
        <Grid item xs={6}>
          <DateTimePicker
            value={endDateTime}
            onChange={(newValue) => setEndDateTime(newValue)}
            label="结束时间"
          />
        </Grid>
      </Grid>
    </LocalizationProvider>
  );
}