> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# FormField

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

组合标签、输入控件、说明、必填标记与错误信息。

## 何时使用

输入控件需要可访问标签和辅助或错误文本时使用 FormField。

**推荐**

- 标签简短并直接描述输入内容。
- 错误信息同时说明问题与修复方式。

**避免**

- 不要仅用 placeholder 代替标签。

## 代码演示


### 基础用法
```tsx preview
import { FormField, Input } from '@rockshin/tao-ui';

function FormFieldExample() {
  return (
    <FormField
      label="Email"
      required
      description="Used for account notifications."
    >
      <Input placeholder="you@example.com" />
    </FormField>
  );
}

export default FormFieldExample;
```

### 说明与错误状态
```tsx preview
import { FormField, Input, Stack } from '@rockshin/tao-ui';

function FormFieldStates() {
  return (
    <Stack gap="lg" style={{ maxWidth: 420 }}>
      <FormField label="Workspace name" description="Visible to all members.">
        <Input placeholder="Acme Design" />
      </FormField>
      <FormField
        label="Slug"
        required
        error="Use lowercase letters and hyphens only."
      >
        <Input value="Acme Team" error readOnly />
      </FormField>
    </Stack>
  );
}

export default FormFieldStates;
```

### 语义部件
```tsx preview
import { FormField, Input } from '@rockshin/tao-ui';

function CustomizedFormField() {
  return (
    <FormField
      label="API token"
      description="Stored securely."
      styles={{
        label: { fontWeight: 600 },
        description: { maxWidth: 320 },
      }}
    >
      <Input type="password" value="secret-token" readOnly />
    </FormField>
  );
}

export default CustomizedFormField;
```

### 完整表单组合
组合布局、字段与操作区，用原生提交展示保存结果。
```tsx preview
import { useState } from 'react';
import {
  FormLayout,
  FormSection,
  FormField,
  FormActions,
  Input,
  Textarea,
  Button,
} from '@rockshin/tao-ui';
export default function Example() {
  const [saved, setSaved] = useState('');
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setSaved(String(new FormData(e.currentTarget).get('name')));
      }}
      onReset={() => setSaved('')}
    >
      <FormLayout>
        <FormSection title="Profile" description="Public workspace information">
          <FormField label="Display name" required>
            <Input name="name" required defaultValue="Alex" />
          </FormField>
          <FormField label="Bio" description="A short introduction">
            <Textarea name="bio" autoSize />
          </FormField>
        </FormSection>
        <FormActions>
          <Button type="reset">Reset</Button>
          <Button type="submit" variant="primary">
            Save
          </Button>
        </FormActions>
        <output aria-live="polite">
          {saved ? `Saved ${saved}` : 'No changes saved'}
        </output>
      </FormLayout>
    </form>
  );
}
```

### 错误提示与修复
字段错误随输入更新，label 与控件自动关联。
```tsx preview
import { useState } from 'react';
import { FormField, Input } from '@rockshin/tao-ui';
export default function Example() {
  const [value, setValue] = useState('');
  return (
    <FormField
      label="Project code"
      required
      error={value.length < 3 ? 'Enter at least 3 characters' : undefined}
    >
      <Input value={value} onChange={(e) => setValue(e.target.value)} />
    </FormField>
  );
}
```

### 明确关联控件
指定 htmlFor 和控件 id 可与已有表单标识对接；useId 避免多个示例冲突。
```tsx preview
import { useId } from 'react';
import { FormField, Input } from '@rockshin/tao-ui';
export default function Example() {
  const id = useId();
  return (
    <FormField
      label="Account email"
      htmlFor={id}
      description="Used for account notifications"
    >
      <Input id={id} type="email" />
    </FormField>
  );
}
```

## API


### [#](#formfield)FormField



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

