TimeField 时间字段

基于 React Aria TimeField 的时间输入字段，包含标签、说明与校验。

用法

1import { TimeField } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.4import { TimeField } from "@lenso/ui";5import { styles } from "../date-field/demo-styles";6
7export function Basic() {8  return (9    <TimeField xstyle={styles.field} name="time">10      <TimeField.Label>Time</TimeField.Label>11      <TimeField.Group>12        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>13      </TimeField.Group>14    </TimeField>15  );16}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

1import {TimeField, Label, Description, FieldError} from '@lenso/ui';2
3export default () => (4  <TimeField>5    <Label />6    <TimeField.Group>7      <TimeField.Input>8        {(segment) => <TimeField.Segment segment={segment} />}9      </TimeField.Input>10    </TimeField.Group>11    <Description />12    <FieldError />13  </TimeField>14)

TimeField 将标签、时间输入、说明与错误信息组合为单个无障碍组件。

示例

带图标

添加前缀或后缀图标以增强时间字段。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { Clock } from "@gravity-ui/icons";4import { TimeField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../date-field/demo-styles";7
8export function WithPrefixIcon() {9  return (10    <TimeField xstyle={styles.field} name="time">11      <TimeField.Label>Time</TimeField.Label>12      <TimeField.Group>13        <TimeField.Prefix>14          <Clock {...stylex.props(styles.icon)} aria-hidden="true" />15        </TimeField.Prefix>16        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>17      </TimeField.Group>18    </TimeField>19  );20}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { Clock } from "@gravity-ui/icons";4import { TimeField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../date-field/demo-styles";7
8export function WithSuffixIcon() {9  return (10    <TimeField xstyle={styles.field} name="time">11      <TimeField.Label>Time</TimeField.Label>12      <TimeField.Group>13        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>14        <TimeField.Suffix>15          <Clock {...stylex.props(styles.icon)} aria-hidden="true" />16        </TimeField.Suffix>17      </TimeField.Group>18    </TimeField>19  );20}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { ChevronDown, Clock } from "@gravity-ui/icons";4import { TimeField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../date-field/demo-styles";7
8export function WithPrefixAndSuffix() {9  return (10    <TimeField xstyle={styles.field} name="time">11      <TimeField.Label>Time</TimeField.Label>12      <TimeField.Group>13        <TimeField.Prefix>14          <Clock {...stylex.props(styles.icon)} aria-hidden="true" />15        </TimeField.Prefix>16        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>17        <TimeField.Suffix>18          <ChevronDown {...stylex.props(styles.icon)} aria-hidden="true" />19        </TimeField.Suffix>20      </TimeField.Group>21      <TimeField.Description>Enter a time</TimeField.Description>22    </TimeField>23  );24}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表面样式

在 Surface 内使用时，请在 TimeField.Group 上使用 variant="secondary"，以应用适合表面背景的低强调变体。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { Clock } from "@gravity-ui/icons";4import { Surface, TimeField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../date-field/demo-styles";7
8export function OnSurface() {9  return (10    <Surface xstyle={styles.surface}>11      <TimeField xstyle={styles.full} name="time">12        <TimeField.Label>Time</TimeField.Label>13        <TimeField.Group variant="secondary">14          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>15        </TimeField.Group>16        <TimeField.Description>Enter a time</TimeField.Description>17      </TimeField>18      <TimeField xstyle={styles.full} name="time-2">19        <TimeField.Label>Appointment time</TimeField.Label>20        <TimeField.Group variant="secondary">21          <TimeField.Prefix>22            <Clock {...stylex.props(styles.icon)} aria-hidden="true" />23          </TimeField.Prefix>24          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>25        </TimeField.Group>26        <TimeField.Description>Enter a time for your appointment</TimeField.Description>27      </TimeField>28    </Surface>29  );30}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带描述

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { TimeField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { styles } from "../date-field/demo-styles";6
7export function WithDescription() {8  return (9    <div {...stylex.props(styles.column)}>10      <TimeField xstyle={styles.field} name="time">11        <TimeField.Label>Start time</TimeField.Label>12        <TimeField.Group>13          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>14        </TimeField.Group>15        <TimeField.Description>Enter the start time</TimeField.Description>16      </TimeField>17      <TimeField xstyle={styles.field} name="end-time">18        <TimeField.Label>End time</TimeField.Label>19        <TimeField.Group>20          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>21        </TimeField.Group>22        <TimeField.Description>Enter the end time</TimeField.Description>23      </TimeField>24    </div>25  );26}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

必填字段

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { TimeField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { styles } from "../date-field/demo-styles";6
7export function Required() {8  return (9    <div {...stylex.props(styles.column)}>10      <TimeField isRequired xstyle={styles.field} name="time">11        <TimeField.Label>Time</TimeField.Label>12        <TimeField.Group>13          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>14        </TimeField.Group>15      </TimeField>16      <TimeField isRequired xstyle={styles.field} name="appointment-time">17        <TimeField.Label>Appointment time</TimeField.Label>18        <TimeField.Group>19          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>20        </TimeField.Group>21        <TimeField.Description>Required field</TimeField.Description>22      </TimeField>23    </div>24  );25}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { TimeField } from "@lenso/ui";4import { Time, getLocalTimeZone, now } from "@internationalized/date";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../date-field/demo-styles";7
8export function Disabled() {9  const currentTime = now(getLocalTimeZone());10  const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);11  return (12    <div {...stylex.props(styles.column)}>13      <TimeField isDisabled xstyle={styles.field} name="time" value={timeValue}>14        <TimeField.Label>Time</TimeField.Label>15        <TimeField.Group>16          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>17        </TimeField.Group>18        <TimeField.Description>This time field is disabled</TimeField.Description>19      </TimeField>20      <TimeField isDisabled xstyle={styles.field} name="time-empty">21        <TimeField.Label>Time</TimeField.Label>22        <TimeField.Group>23          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>24        </TimeField.Group>25        <TimeField.Description>This time field is disabled</TimeField.Description>26      </TimeField>27    </div>28  );29}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

宽度充满

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { ChevronDown, Clock } from "@gravity-ui/icons";4import { TimeField } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6import { styles } from "../date-field/demo-styles";7
8export function FullWidth() {9  return (10    <div {...stylex.props(styles.wide)}>11      <TimeField fullWidth name="time">12        <TimeField.Label>Time</TimeField.Label>13        <TimeField.Group fullWidth>14          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>15        </TimeField.Group>16      </TimeField>17      <TimeField fullWidth name="time-icons">18        <TimeField.Label>Time</TimeField.Label>19        <TimeField.Group fullWidth>20          <TimeField.Prefix>21            <Clock {...stylex.props(styles.icon)} aria-hidden="true" />22          </TimeField.Prefix>23          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>24          <TimeField.Suffix>25            <ChevronDown {...stylex.props(styles.icon)} aria-hidden="true" />26          </TimeField.Suffix>27        </TimeField.Group>28      </TimeField>29    </div>30  );31}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表单校验

将 isInvalid 与 FieldError 配合使用，以展示校验消息。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { TimeField } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5import { styles } from "../date-field/demo-styles";6
7export function Invalid() {8  return (9    <div {...stylex.props(styles.column)}>10      <TimeField isInvalid isRequired xstyle={styles.field} name="time">11        <TimeField.Label>Time</TimeField.Label>12        <TimeField.Group>13          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>14        </TimeField.Group>15        <TimeField.Error>Please enter a valid time</TimeField.Error>16      </TimeField>17      <TimeField isInvalid xstyle={styles.field} name="invalid-time">18        <TimeField.Label>Time</TimeField.Label>19        <TimeField.Group>20          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>21        </TimeField.Group>22        <TimeField.Error>Time must be within business hours</TimeField.Error>23      </TimeField>24    </div>25  );26}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

控制 value 以与其他组件或状态管理同步。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import type { TimeValue } from "react-aria-components/TimeField";4import { Button, TimeField } from "@lenso/ui";5import { Time, getLocalTimeZone, now } from "@internationalized/date";6import { useState } from "react";7import * as stylex from "@stylexjs/stylex";8import { styles } from "../date-field/demo-styles";9
10export function Controlled() {11  const [value, setValue] = useState<TimeValue | null>(null);12  return (13    <div {...stylex.props(styles.column)}>14      <TimeField xstyle={styles.field} name="time" value={value} onChange={setValue}>15        <TimeField.Label>Time</TimeField.Label>16        <TimeField.Group>17          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>18        </TimeField.Group>19        <TimeField.Description>20          Current value: {value ? value.toString() : "(empty)"}21        </TimeField.Description>22      </TimeField>23      <div {...stylex.props(styles.row)}>24        <Button25          variant="tertiary"26          onClick={() => {27            const currentTime = now(getLocalTimeZone());28            setValue(new Time(currentTime.hour, currentTime.minute, currentTime.second));29          }}30        >31          Set now32        </Button>33        <Button variant="tertiary" onClick={() => setValue(null)}>34          Clear35        </Button>36      </div>37    </div>38  );39}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表单示例

包含校验与提交处理的完整表单示例。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import type { Time } from "@internationalized/date";4import { Clock } from "@gravity-ui/icons";5import { Button, TimeField } from "@lenso/ui";6import { Form } from "react-aria-components/Form";7import { parseTime } from "@internationalized/date";8import { useState, type FormEvent } from "react";9import * as stylex from "@stylexjs/stylex";10import { styles } from "../date-field/demo-styles";11
12export function FormExample() {13  const [value, setValue] = useState<Time | null>(null);14  const [isSubmitting, setIsSubmitting] = useState(false);15  const minTime = parseTime("09:00");16  const maxTime = parseTime("17:00");17  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);18  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {19    event.preventDefault();20    if (!value || isInvalid || isSubmitting) return;21    setIsSubmitting(true);22    setTimeout(() => {23      console.log("Time submitted:", { time: value });24      setValue(null);25      setIsSubmitting(false);26    }, 1500);27  };28  return (29    <Form {...stylex.props(styles.form)} onSubmit={handleSubmit}>30      <TimeField31        isRequired32        xstyle={styles.full}33        isInvalid={isInvalid}34        maxValue={maxTime}35        minValue={minTime}36        name="time"37        value={value}38        onChange={setValue}39      >40        <TimeField.Label>Appointment time</TimeField.Label>41        <TimeField.Group>42          <TimeField.Prefix>43            <Clock {...stylex.props(styles.icon)} aria-hidden="true" />44          </TimeField.Prefix>45          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>46        </TimeField.Group>47        {isInvalid ? (48          <TimeField.Error>Time must be between 9:00 AM and 5:00 PM</TimeField.Error>49        ) : (50          <TimeField.Description>Enter a time between 9:00 AM and 5:00 PM</TimeField.Description>51        )}52      </TimeField>53      <Button54        xstyle={styles.full}55        disabled={!value || isInvalid}56        isLoading={isSubmitting}57        type="submit"58        variant="primary"59      >60        {isSubmitting ? "Submitting..." : "Submit"}61      </Button>62    </Form>63  );64}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

带校验

TimeField 支持通过 minValue、maxValue 及自定义校验逻辑进行验证。

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import type { Time } from "@internationalized/date";4import { TimeField } from "@lenso/ui";5import { parseTime } from "@internationalized/date";6import { useState } from "react";7import * as stylex from "@stylexjs/stylex";8import { styles } from "../date-field/demo-styles";9
10export function WithValidation() {11  const [value, setValue] = useState<Time | null>(null);12  const minTime = parseTime("09:00");13  const maxTime = parseTime("17:00");14  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);15  return (16    <div {...stylex.props(styles.column)}>17      <TimeField18        isRequired19        xstyle={styles.field}20        isInvalid={isInvalid}21        maxValue={maxTime}22        minValue={minTime}23        name="time"24        value={value}25        onChange={setValue}26      >27        <TimeField.Label>Time</TimeField.Label>28        <TimeField.Group>29          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>30        </TimeField.Group>31        {isInvalid ? (32          <TimeField.Error>Time must be between 9:00 AM and 5:00 PM</TimeField.Error>33        ) : (34          <TimeField.Description>Enter a time between 9:00 AM and 5:00 PM</TimeField.Description>35        )}36      </TimeField>37    </div>38  );39}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { TimeField } from "@lenso/ui";4import { styles } from "../date-field/demo-styles";5
6export function RenderFunction() {7  return (8    <TimeField9      xstyle={styles.field}10      name="time"11      render={(props) => <div {...props} data-custom="foo" />}12    >13      <TimeField.Label>Time</TimeField.Label>14      <TimeField.Group>15        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>16      </TimeField.Group>17    </TimeField>18  );19}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2// HeroUI v3.2.6. Copyright NextUI Inc. SPDX-License-Identifier: Apache-2.0.3import { TimeField } from "@lenso/ui";4import { styles } from "../date-field/demo-styles";5
6export function CustomStyles() {7  return (8    <TimeField xstyle={styles.reminder} name="reminder">9      <TimeField.Label xstyle={styles.reminderLabel}>Reminder time</TimeField.Label>10      <TimeField.Description>Daily check-in notification.</TimeField.Description>11      <TimeField.Group xstyle={styles.reminderGroup}>12        <TimeField.Input>13          {(segment) => <TimeField.Segment xstyle={styles.foreground} segment={segment} />}14        </TimeField.Input>15      </TimeField.Group>16    </TimeField>17  );18}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

若要自定义组件类，可使用 @layer components 指令。了解更多。

1@layer components {2  .time-field {3    @apply flex flex-col gap-1;4
5    &[data-invalid="true"],6    &[aria-invalid="true"] {7      [data-slot="description"] {8        @apply hidden;9      }10    }11
12    [data-slot="label"] {13      @apply w-fit;14    }15
16    [data-slot="description"] {17      @apply px-1;18    }19  }20}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

.time-field – 轻量样式的根容器（flex flex-col gap-1）

说明： 子组件（Label、Description、FieldError）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。TimeField.Group 的样式见下文 API 参考。

交互状态

TimeField 会根据状态自动设置以下 data 属性：

无效：[data-invalid="true"] 或 [aria-invalid="true"] – 无效时自动隐藏 description 插槽
必填：[data-required="true"] – 当 isRequired 为 true 时添加
禁用：[data-disabled="true"] – 当 isDisabled 为 true 时添加
焦点在内：[data-focus-within="true"] – 任一子输入聚焦时添加

API 参考

TimeField

TimeField 继承 React Aria TimeField 的全部 props。

Base Props

Prop	类型	默认值	描述
`children`	`React.ReactNode \| (values: TimeFieldRenderProps) => React.ReactNode`	-	子组件（Label、TimeField.Group 等）或渲染函数。
`className`	`string \| (values: TimeFieldRenderProps) => string`	-	用于样式的 CSS 类，支持渲染 prop。
`style`	`React.CSSProperties \| (values: TimeFieldRenderProps) => React.CSSProperties`	-	内联样式，支持渲染 prop。
`fullWidth`	`boolean`	`false`	时间字段是否占满容器宽度。
`id`	`string`	-	元素的唯一 id。
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, TimeFieldRenderProps>`	-	使用自定义渲染函数覆盖默认 DOM 元素。

Value Props

Prop	类型	默认值	描述
`value`	`TimeValue \| null`	-	当前值（受控）。类型见 `@internationalized/date`。
`defaultValue`	`TimeValue \| null`	-	默认值（非受控）。类型见 `@internationalized/date`。
`onChange`	`(value: TimeValue \| null) => void`	-	值变化时触发的事件处理函数。
`placeholderValue`	`TimeValue \| null`	-	影响占位符格式的占位时间；默认随小时制为 12:00 AM 或 00:00。

Validation Props

Prop	类型	默认值	描述
`isRequired`	`boolean`	`false`	是否在提交表单前要求用户输入。
`isInvalid`	`boolean`	-	值是否无效。
`minValue`	`TimeValue \| null`	-	用户可选择最早时间。类型见 `@internationalized/date`。
`maxValue`	`TimeValue \| null`	-	用户可选择最晚时间。类型见 `@internationalized/date`。
`validate`	`(value: TimeValue) => ValidationError \| true \| null \| undefined`	-	自定义校验函数。
`validationBehavior`	`'native' \| 'aria'`	`'native'`	使用原生 HTML 表单校验还是 ARIA 属性。

Format Props

Prop	类型	默认值	描述
`granularity`	`'hour' \| 'minute' \| 'second'`	`'minute'`	时间选择器显示的最小单位。
`hourCycle`	`12 \| 24`	-	以 12 或 24 小时制显示时间；默认由语言环境决定。
`hideTimeZone`	`boolean`	`false`	是否隐藏时区缩写。
`shouldForceLeadingZeros`	`boolean`	-	是否始终为小时字段显示前导零；默认由语言环境决定。

State Props

Prop	类型	默认值	描述
`isDisabled`	`boolean`	-	是否禁用输入。
`isReadOnly`	`boolean`	-	是否可选中但不可修改。

Form Props

Prop	类型	默认值	描述
`name`	`string`	-	输入元素的 name，用于 HTML 表单提交；以 ISO 8601 字符串提交。
`autoFocus`	`boolean`	-	是否在渲染后自动聚焦该元素。

Accessibility Props

Prop	类型	默认值	描述
`aria-label`	`string`	-	无可见标签时的无障碍标签。
`aria-labelledby`	`string`	-	标注该字段的元素 id。
`aria-describedby`	`string`	-	描述该字段的元素 id。
`aria-details`	`string`	-	包含额外详情的元素 id。

组合组件

TimeField 与以下独立组件配合使用，请分别导入并直接使用：

Label – 来自 @lenso/ui 的字段标签
TimeField.Group – 时间输入分组（详见下文）
TimeField.Input – 来自 @lenso/ui 的分段位编辑输入
TimeField.Segment – 单个时间段位（时、分、秒等）
TimeField.Prefix / TimeField.Suffix – 输入组的前缀与后缀插槽
Description – 来自 @lenso/ui 的辅助说明
FieldError – 来自 @lenso/ui 的校验错误信息

这些组件各自有独立的 props API。在 TimeField 中直接组合使用：

1import {parseTime} from '@internationalized/date';2import {TimeField, Label, Description, FieldError} from '@lenso/ui';3
4<TimeField5  isRequired6  isInvalid={hasError}7  minValue={parseTime('09:00')}8  maxValue={parseTime('17:00')}9  value={time}10  onChange={setTime}11>12  <Label>Appointment Time</Label>13  <TimeField.Group>14    <TimeField.Input>15      {(segment) => <TimeField.Segment segment={segment} />}16    </TimeField.Input>17  </TimeField.Group>18  <Description>Select a time between 9:00 AM and 5:00 PM.</Description>19  <FieldError>Please select a valid time.</FieldError>20</TimeField>

TimeValue 类型

TimeField 使用 @internationalized/date 中的类型：

Time – 仅时间（时、分、秒）
CalendarDateTime – 含日期与时间、不含时区（TimeField 仅展示时间部分）
ZonedDateTime – 含日期、时间与时区（TimeField 仅展示时间部分）

示例：

1import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date';2
3// Parse from string4const time = parseTime('14:30');5
6// Create from current time7const currentTime = now(getLocalTimeZone());8const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);9
10// Use in TimeField11<TimeField value={time} onChange={setTime}>12  {/* ... */}13</TimeField>

说明： TimeField 使用 @internationalized/date 进行时间处理、解析与类型定义。更多类型与函数见 Internationalized Date 文档。

TimeFieldRenderProps

对 className、style 或 children 使用渲染 prop 时，可使用以下值：

Prop	类型	描述
`isDisabled`	`boolean`	字段是否禁用。
`isInvalid`	`boolean`	字段当前是否无效。
`isReadOnly`	`boolean`	字段是否只读。
`isRequired`	`boolean`	字段是否必填。
`isFocused`	`boolean`	字段是否聚焦。
`isFocusWithin`	`boolean`	是否有子元素聚焦。
`isFocusVisible`	`boolean`	焦点是否可见（键盘导航）。

TimeField.Group

TimeField.Group 继承 React Aria Group 的全部 props，并额外支持：

Prop	类型	默认值	描述
`className`	`string`	-	与组件样式合并的 Tailwind CSS 类。
`variant`	`"primary" \| "secondary"`	`"primary"`	视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。

TimeField.Input

TimeField.Input 继承 React Aria DateInput 的全部 props，并额外支持：

Prop	类型	默认值	描述
`className`	`string`	-	与组件样式合并的 Tailwind CSS 类。
`variant`	`"primary" \| "secondary"`	`"primary"`	输入的视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。

TimeField.Input 接受渲染函数作为子节点，函数接收日期段位；每个段位表示时间的一部分（时、分、秒等）。

TimeField.Segment

TimeField.Segment 继承 React Aria DateSegment 的全部 props：

Prop	类型	默认值	描述
`segment`	`DateSegment`	-	来自 TimeField.Input 渲染函数的 `DateSegment` 对象。
`className`	`string`	-	与组件样式合并的 Tailwind CSS 类。

TimeField.Prefix

TimeField.Prefix 接受标准 HTML div 属性：

Prop	类型	默认值	描述
`className`	`string`	-	与组件样式合并的 Tailwind CSS 类。
`children`	`ReactNode`	-	前缀插槽中要显示的内容。

TimeField.Suffix

TimeField.Suffix 接受标准 HTML div 属性：

Prop	类型	默认值	描述
`className`	`string`	-	与组件样式合并的 Tailwind CSS 类。
`children`	`ReactNode`	-	后缀插槽中要显示的内容。

TimeField.Group 样式

全局 CSS

基础类作用于所有实例，可通过 @layer components 一次性覆盖。

1@layer components {2  .date-input-group {3    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;4
5    &:hover,6    &[data-hovered="true"] {7      @apply bg-field-hover;8    }9
10    &[data-focus-within="true"],11    &:focus-within {12      @apply status-focused-field;13    }14
15    &[data-invalid="true"] {16      @apply status-invalid-field;17    }18
19    &[data-disabled="true"],20    &[aria-disabled="true"] {21      @apply status-disabled;22    }23  }24
25  .date-input-group__input {26    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;27  }28
29  .date-input-group__segment {30    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;31
32    &:focus,33    &[data-focused="true"] {34      @apply bg-accent-soft text-accent-soft-foreground;35    }36  }37
38  .date-input-group__prefix,39  .date-input-group__suffix {40    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;41  }42}

TimeField.Group CSS 类

.date-input-group – 根容器样式
.date-input-group__input – 输入包裹层样式
.date-input-group__segment – 单个时间段位样式
.date-input-group__prefix – 前缀元素样式
.date-input-group__suffix – 后缀元素样式

TimeField.Group 交互状态

悬停：:hover 或 [data-hovered="true"]
焦点在内：[data-focus-within="true"] 或 :focus-within
无效：[data-invalid="true"]（同时与 aria-invalid 同步）
禁用：[data-disabled="true"] 或 [aria-disabled="true"]
段位聚焦：段位上的 :focus 或 [data-focused="true"]
段位占位符：段位上的 [data-placeholder="true"]

TimeField 时间字段

用法

组件结构

示例

带图标

表面样式

带描述

必填字段

禁用

宽度充满

表单校验

受控组件

表单示例

带校验

渲染函数

自定义样式

Tailwind CSS

全局 CSS

样式参考

CSS 类

交互状态

API 参考

TimeField

Base Props

Value Props

Validation Props

Format Props

State Props

Form Props

Accessibility Props

组合组件

TimeValue 类型

TimeFieldRenderProps

TimeField.Group

TimeField.Input

TimeField.Segment

TimeField.Prefix

TimeField.Suffix

TimeField.Group 样式

全局 CSS

TimeField.Group CSS 类

TimeField.Group 交互状态

相关组件