Material UI 框架之 DateTime Field 组件详解

person smartzeng   watch_later 2024-10-27 19:36:19
visibility 41    class DateTime Field    bookmark 专栏

Material UI 中的 DateTime Field 组件用于输入和显示日期时间,具有自定义时间格式、表单验证、多语言支持等特点。本文将详细介绍 DateTime Field 的使用,涵盖组件的基本用法、属性、方法及其与其他组件的结合应用,帮助开发者掌握该组件的所有功能。

1. 基础用法

DateTime Field 组件基于 Material UI 的日期时间选择器,允许用户在表单中输入或选择日期和时间。首先需要引入 DateTime Field 组件并设置基本的日期时间值和事件。

1.1 安装依赖

确保项目中已安装 Material UI 的 @mui/x-date-pickers 包和时间格式适配器,例如 date-fns

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

1.2 基本使用示例

以下是使用 DateTime Field 的基本代码示例,它显示当前日期时间,并允许用户选择新的日期时间:

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

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

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

2. 组件属性详解

2.1 valueonChange

  • value:表示当前选择的日期时间。
  • onChange:日期时间变更时的回调,用于更新 value
<DateTimeField
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
/>

2.2 minDateTimemaxDateTime

  • minDateTimemaxDateTime 用于设置可选日期时间的最小和最大值。例如,限制时间范围在工作时间内:
<DateTimeField
  label="选择工作时间"
  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:是否使用 12 小时制,true 表示 12 小时制,false 表示 24 小时制。默认值为 true
<DateTimeField
  label="选择时间"
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  ampm={false} // 使用 24 小时制
/>

2.4 disabledreadOnly

  • disabled:禁用组件。
  • readOnly:设置为只读模式,仅展示日期时间而不允许用户修改。
<DateTimeField
  label="禁用的日期时间"
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  disabled
/>
<DateTimeField
  label="只读日期时间"
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  readOnly
/>

2.5 format

  • format:自定义日期时间格式,例如 dd/MM/yyyy HH:mm
<DateTimeField
  label="自定义日期时间格式"
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  format="dd/MM/yyyy HH:mm"
/>

2.6 errorhelperText

  • error:布尔值,表示是否显示错误状态。
  • helperText:错误提示文本,通常结合表单验证使用。
<DateTimeField
  label="日期时间(仅工作时间)"
  value={selectedDateTime}
  onChange={(newValue) => {
    const isValidTime = newValue.getHours() >= 9 && newValue.getHours() <= 18;
    setError(!isValidTime);
  }}
  error={error}
  helperText={error ? "请选择工作时间(09:00 - 18:00)" : ""}
/>

3. 进阶用法

3.1 多语言支持

可以通过 LocalizationProviderlocale 属性支持多语言显示,以下示例展示了使用中文:

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

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

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

3.2 表单集成

DateTime Field 可以与表单组件集成,实现提交表单数据。例如,以下代码展示了选择日期时间并提交的表单:

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

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

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

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

3.3 与 Grid 布局结合

通过 Grid 布局可以创建多个 DateTime Field 组件的排布,例如设置开始时间和结束时间的表单:

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

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

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

3.4 自定义样式

通过 sx 属性可以自定义组件的外观,例如修改输入框颜色和背景:

<DateTimeField
  label="自定义样式的日期时间"
  value={selectedDateTime}
  onChange={(newValue) => setSelectedDateTime(newValue)}
  sx={{
    width: '100%',
    '& .MuiInputBase-root': {
      backgroundColor: 'lightgray',
      color: 'blue',
    },
  }}
/>

4. 常见应用场景

场景一:动态禁用日期时间范围

使用 minDateTimemaxDateTime 动态设定用户可以选择的时间范围,例如设置截止时间不能早于当前时间:

<DateTimeField
  label="截止时间"
  value={deadline}
  onChange={(newValue) => setDeadline(newValue)}
  minDateTime={new Date()} // 不能选择过去的时间
/>

场景二:表单验证和提交

通过 error 属性和 helperText 显示错误信息,确保用户输入符合条件。例如,限制日期时间在指定时间范围内:

<DateTimeField
  label="限定范围的日期时间"
  value={selectedDateTime}
  onChange={(newValue) => {
    const isValid = newValue >= minDate && newValue <= maxDate;
    setError(!isValid);
    setHelperText(isValid

 ? '' : '日期时间超出范围');
  }}
  error={error}
  helperText={helperText}
/>

5. 总结

DateTime Field 是一个灵活且功能强大的组件,本文详细介绍了其主要属性和方法,并通过丰富的示例展示其应用场景,包括表单集成、多语言支持和动态日期时间控制。希望通过本文,您能掌握 DateTime Field 的使用,并在项目中高效实现日期时间的输入和管理。

chat评论区
评论列表
menu