# TextField 文本输入框 · HeroUI

> 便于组合的文本字段，包含标签、说明与内联校验。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/components/text-field
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## 引入

```tsx
import { TextField } from '@heroui/react';
```

### 用法


> 示例 `textfield-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 组件结构

```tsx
import {TextField, Label, Input, Description, FieldError} from '@heroui/react';

export default () => (
  <TextField>
    <Label />
    <Input />
    <Description />
    <FieldError />
  </TextField>
)
```

> **TextField** 将标签、输入、说明与错误信息整合为单个无障碍组件。若只需独立输入，请使用 **[Input](/systems/heroui/docs/components/input)** 或 **[TextArea](/systems/heroui/docs/components/textarea)**。

### 带说明


> 示例 `textfield-with-description`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 必填字段


> 示例 `textfield-required`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 校验

使用 `isInvalid` 与 `FieldError` 展示校验信息。


> 示例 `textfield-validation`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 受控

通过受控 `value` 同步计数器、预览或格式化。


> 示例 `textfield-controlled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 错误信息


> 示例 `textfield-with-error`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 禁用状态


> 示例 `textfield-disabled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### TextArea

多行内容请使用 [TextArea](/systems/heroui/docs/components/textarea) 替代 [Input](/systems/heroui/docs/components/input)。


> 示例 `textfield-textarea`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### Input 类型


> 示例 `textfield-input-types`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 全宽


> 示例 `textfield-full-width`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 在 Surface 内

置于 [Surface](/systems/heroui/docs/components/surface) 中时，请在 Input 或 TextArea 上使用 `variant="secondary"`，以应用适合表面背景的弱强调变体。


> 示例 `textfield-on-surface`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


### 自定义渲染函数


> 示例 `textfield-custom-render-function`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/text-field


## 样式

### 传入 Tailwind CSS 类

```tsx
import {TextField, Label, Input, Description} from '@heroui/react';

function CustomTextField() {
  return (
    <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Project name
      </Label>
      <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" />
      <Description className="text-xs text-default-500">
        Keep it short and memorable.
      </Description>
    </TextField>
  );
}
```

### 自定义组件类

TextField 默认样式很少。覆盖 `.textfield` 类即可自定义容器样式。

```css
@layer components {
  .textfield {
    @apply flex flex-col gap-1;
  }

  /* 无效时自动隐藏说明 */
  .textfield[data-invalid="true"] [data-slot="description"],
  .textfield[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

  /* Description 默认内边距 */
  .textfield [data-slot="description"] {
    @apply px-1;
  }
}
```

### CSS 类

- `.textfield` – 根容器，样式极少（`flex flex-col gap-1`）

> **提示：** 子组件（[Label](/systems/heroui/docs/components/label)、[Input](/systems/heroui/docs/components/input)、[TextArea](/systems/heroui/docs/components/textarea)、[Description](/systems/heroui/docs/components/description)、[FieldError](/systems/heroui/docs/components/field-error)）各自拥有 CSS 类与样式，定制方式请参见对应文档。

### 交互状态

TextField 会根据状态自动管理以下 data 属性：

- **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` — 无效时自动隐藏 description 插槽
- **禁用**：`[data-disabled="true"]` — 在 `isDisabled` 为 true 时应用
- **焦点在内部**：`[data-focus-within="true"]` — 任一子级 input 聚焦时应用
- **可见焦点**：`[data-focus-visible="true"]` — 键盘导航产生可见焦点时应用

更多属性可通过 render prop 获取（见下文 TextFieldRenderProps）。

## API 参考

### TextField Props

继承 React Aria [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) 的全部 props。

#### Base Props

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

#### Validation Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `isRequired` | `boolean` | `false` | 提交表单前是否必须填写。 |
| `isInvalid` | `boolean` | - | 当前值是否无效。 |
| `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 |
| `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 |
| `validationErrors` | `string[]` | - | 服务端校验错误。 |

#### Value Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `value` | `string` | - | 当前值（受控）。 |
| `defaultValue` | `string` | - | 默认值（非受控）。 |
| `onChange` | `(value: string) => void` | - | 值变化时调用的事件处理函数。 |

#### State Props

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

#### Form Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `name` | `string` | - | 用于 HTML 表单提交的 input 名称。 |
| `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦。 |

#### Accessibility Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `aria-label` | `string` | - | 无可见标签时的无障碍标签。 |
| `aria-labelledby` | `string` | - | 用于标注该字段的元素 id。 |
| `aria-describedby` | `string` | - | 用于描述该字段的元素 id。 |
| `aria-details` | `string` | - | 提供附加详情的元素 id。 |

### Composition Components

TextField 与以下独立组件配合使用，请直接按需引入并组合：

- **Label** — `@heroui/react` 的字段标签组件
- **Input** — `@heroui/react` 的单行文本输入
- **TextArea** — `@heroui/react` 的多行文本输入
- **Description** — `@heroui/react` 的辅助说明组件
- **FieldError** — `@heroui/react` 的校验错误信息组件

这些组件各自有独立的 props API，请在 TextField 内直接使用：

```tsx
<TextField isRequired isInvalid={hasError}>
  <Label>Email Address</Label>
  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
  <Description>We'll never share your email.</Description>
  <FieldError>Please enter a valid email address.</FieldError>
</TextField>
```

### TextFieldRenderProps

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

| Prop | 类型 | 描述 |
|------|------|------|
| `isDisabled` | `boolean` | 字段是否禁用。 |
| `isInvalid` | `boolean` | 字段当前是否无效。 |
| `isReadOnly` | `boolean` | 字段是否只读。 |
| `isRequired` | `boolean` | 字段是否必填。 |
| `isFocused` | `boolean` | 字段是否聚焦（已弃用 — 请使用 `isFocusWithin`）。 |
| `isFocusWithin` | `boolean` | 是否有任一子元素聚焦。 |
| `isFocusVisible` | `boolean` | 是否为可见键盘焦点。 |

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt