# FormField 表单字段

一个表单字段包装组件，为表单输入提供一致的布局，包括标签、错误消息和必填指示器。

## 特性

- **标签支持**: 显示带可选后缀的标签
- **必填指示器**: 必填字段的视觉指示器
- **错误显示**: 显示验证错误消息
- **灵活布局**: 中心或顶部标签对齐
- **自定义样式**: 标签和容器的自定义样式
- **响应式高度**: 可调整的字段高度

## 安装

```bash
npm install @ticatec/uniface-element
```

```typescript
import FormField from '@ticatec/uniface-element/FormField';
```

## 基本用法

```svelte
<script>
  import FormField from '@ticatec/uniface-element/FormField';
  import TextEditor from '@ticatec/uniface-element/TextEditor';
</script>

<FormField label="用户名" required>
  <TextEditor placeholder="请输入用户名" />
</FormField>
```

## 属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|---------|-------------|
| `label` | `string` | `'Label:'` | 字段标签文本 |
| `labelSuffix` | `string` | `':'` | 标签后的后缀文本 |
| `required` | `boolean` | `false` | 显示必填指示器 (*) |
| `error` | `string \| null` | `null` | 要显示的错误消息 |
| `labelAlignment` | `'center' \| 'top'` | `'center'` | 标签垂直对齐方式 |
| `labelStyle` | `string \| null` | `null` | 标签的自定义CSS |
| `style` | `string` | `''` | 容器的自定义CSS |
| `height` | `string` | `'auto'` | 字段区域的高度 |
| `class` | `string` | `''` | CSS类名 |

## 示例

### 基本表单字段

```svelte
<script>
  import FormField from '@ticatec/uniface-element/FormField';
  import TextEditor from '@ticatec/uniface-element/TextEditor';
</script>

<FormField label="邮箱">
  <TextEditor type="email" placeholder="user@example.com" />
</FormField>
```

### 必填字段

```svelte
<script>
  import FormField from '@ticatec/uniface-element/FormField';
  import TextEditor from '@ticatec/uniface-element/TextEditor';
</script>

<FormField label="密码" required>
  <TextEditor type="password" placeholder="请输入密码" />
</FormField>
```

### 带错误消息

```svelte
<script>
  import FormField from '@ticatec/uniface-element/FormField';
  import TextEditor from '@ticatec/uniface-element/TextEditor';

  let error = '此字段为必填项';
</script>

<FormField label="用户名" {error} required>
  <TextEditor placeholder="请输入用户名" />
</FormField>
```

### 顶部标签对齐

```svelte
<script>
  import FormField from '@ticatec/uniface-element/FormField';
  import TextEditor from '@ticatec/uniface-element/TextEditor';
</script>

<FormField label="描述" labelAlignment="top">
  <TextEditor placeholder="请输入描述" />
</FormField>
```

### 自定义标签样式

```svelte
<script>
  import FormField from '@ticatec/uniface-element/FormField';
  import TextEditor from '@ticatec/uniface-element/TextEditor';
</script>

<FormField
  label="重要字段"
  labelStyle="color: #007acc; font-weight: bold;"
>
  <TextEditor placeholder="请输入值" />
</FormField>
```

### 完整表单示例

```svelte
<script>
  import FormField from '@ticatec/uniface-element/FormField';
  import TextEditor from '@ticatec/uniface-element/TextEditor';
  import Button from '@ticatec/uniface-element/Button';

  let formData = {
    username: '',
    email: '',
    password: ''
  };

  let errors = {
    username: '',
    email: '',
    password: ''
  };

  function validate() {
    if (!formData.username) {
      errors.username = '用户名为必填项';
    }
    if (!formData.email) {
      errors.email = '邮箱为必填项';
    }
    if (!formData.password) {
      errors.password = '密码为必填项';
    }
  }

  function handleSubmit() {
    validate();
    if (Object.values(errors).every(e => !e)) {
      console.log('表单提交:', formData);
    }
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <FormField label="用户名" required error={errors.username}>
    <TextEditor bind:value={formData.username} placeholder="请输入用户名" />
  </FormField>

  <FormField label="邮箱" required error={errors.email}>
    <TextEditor bind:value={formData.email} type="email" placeholder="user@example.com" />
  </FormField>

  <FormField label="密码" required error={errors.password}>
    <TextEditor bind:value={formData.password} type="password" placeholder="请输入密码" />
  </FormField>

  <Button type="primary" onclick={handleSubmit}>提交</Button>
</form>
```

## 最佳实践

1. **始终使用标签**: 为可访问性提供清晰、描述性的标签
2. **标记必填字段**: 对必填字段使用 `required` 属性
3. **显示错误**: 在字段下方显示验证错误
4. **一致对齐**: 在整个表单中使用相同的标签对齐方式
5. **自定义样式**: 需要特殊强调时使用 labelStyle

## 无障碍访问

- 表单字段的正确标签关联
- 屏幕阅读器的必填指示器
- 验证反馈的错误消息显示
- 语义化HTML结构