云策 WordPress 开发者社区

块编辑器开发文档

TimePicker

查看官方原文 ↗
💡 云策文档标注

概述

TimePicker 是一个 React 组件，用于渲染时间和日期选择表单输入，可独立使用或作为 DateTimePicker 的一部分。它还提供了 TimePicker.TimeInput 子组件，用于独立渲染时间输入字段。

关键要点

  • TimePicker 是一个 React 组件，支持时间选择，可配置 12 小时制或 24 小时制。
  • TimePicker.TimeInput 是一个独立的子组件，用于渲染时间输入，接受 24 小时格式的对象值。
  • 组件接受多个 props，如 currentTime、onChange、is12Hour、dateOrder 等，用于自定义行为和显示。
  • 支持无障碍访问，可通过 hideLabelFromVision 隐藏标签但保持屏幕阅读器可访问。

代码示例

import { useState } from 'react';
import { TimePicker } from '@wordpress/components';

const MyTimePicker = () => {
    const [ time, setTime ] = useState( new Date() );

    return (
        <TimePicker
            currentTime={ time }
            onChange={ ( newTime ) => setTime( newTime ) }
            is12Hour
        />
    );
};

注意事项

  • TimePicker 的 currentTime 可以是 Date、string、number 或 null，默认使用当前时间。
  • onChange 函数接收 ISO 格式字符串的时间参数。
  • dateOrder 属性可覆盖 is12Hour 确定的时间格式，默认值取决于 is12Hour 的设置。
  • TimePicker.TimeInput 的值以对象形式传递，如 { hours: 13, minutes: 30 }。
📄 原文内容

TimePicker is a React component that renders form inputs for time and date selection. It can be used independently or as part of the DateTimePicker component.

Note: TimePicker also exposes a compound sub-component, TimePicker.TimeInput, which can be used independently to render a time input field without the full picker UI.

Usage

Render a TimePicker.

import { useState } from 'react';
import { TimePicker } from '@wordpress/components';

const MyTimePicker = () => {
    const [ time, setTime ] = useState( new Date() );

    return (
        <TimePicker
            currentTime={ time }
            onChange={ ( newTime ) => setTime( newTime ) }
            is12Hour
        />
    );
};

Props

The component accepts the following props:

currentTime: Date | string | number | null

The current time at initialization. Optionally pass in a null value to specify no time is currently selected.

  • Required: No
  • Default: current time

onChange: ( time: string ) => void

The function called when a new time has been selected. It is passed the time as an ISO-formatted string.

  • Required: No

is12Hour: boolean

Whether we use a 12-hour clock. With a 12-hour clock, an AM/PM widget is displayed.

  • Required: No
  • Default: false

dateOrder: 'dmy' | 'mdy' | 'ymd'

The order of day, month, and year. This prop overrides the time format determined by is12Hour prop.

  • Required: No
  • Default: 'dmy' (or 'mdy' when is12Hour is true)

hideLabelFromVision: boolean

Whether to visually hide field labels while keeping them accessible to screen readers.

  • Required: No
  • Default: false

TimePicker.TimeInput

A standalone time input component. Values are passed as an object in 24-hour format ({ hours: number, minutes: number }).

Usage

import { useState } from 'react';
import { TimePicker } from '@wordpress/components';

const MyTimeInput = () => {
    const [ time, setTime ] = useState( { hours: 13, minutes: 30 } );

    return (
        <TimePicker.TimeInput
            value={ time }
            onChange={ setTime }
            label="Time"
        />
    );
};

Props

value: { hours: number, minutes: number }

The time input value in 24-hour format.

  • Required: No

defaultValue: { hours: number, minutes: number }

An optional default value for the control when used in uncontrolled mode. If left undefined, the current time will be used.

  • Required: No

onChange: ( time: { hours: number, minutes: number } ) => void

Called when the time changes. Receives the new value as an object with hours and minutes.

  • Required: No

is12Hour: boolean

Whether to use a 12-hour clock. With a 12-hour clock, an AM/PM widget is displayed.

  • Required: No

label: string

The label for the time input.

  • Required: No