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 value 和 onChange

• value：表示当前选择的日期时间。
• onChange：日期时间变更时的回调，用于更新 value。

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

2.2 minDateTime 和 maxDateTime

• minDateTime 和 maxDateTime 用于设置可选日期时间的最小和最大值。例如，限制时间范围在工作时间内：

<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 disabled 和 readOnly

• 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 error 和 helperText

• 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 多语言支持

可以通过 LocalizationProvider 的 locale 属性支持多语言显示，以下示例展示了使用中文：

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. 常见应用场景

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

使用 minDateTime 和 maxDateTime 动态设定用户可以选择的时间范围，例如设置截止时间不能早于当前时间：

<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 的使用，并在项目中高效实现日期时间的输入和管理。