# 文本编辑器组件

一个功能强大的文本输入组件，提供全面的输入处理、事件转发和显示模式。基于 `CommonEditor` 基础组件构建，具备高级功能，如前缀/后缀支持、清除功能和灵活的样式设置。

## 安装

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

## 导入

```typescript
import TextEditor from "@ticatec/uniface-element/TextEditor";
```

## 基本用法

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let inputValue = '';
</script>

<TextEditor 
  bind:value={inputValue} 
  placeholder="输入文本..."
/>
```

## 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `value` | `string` | `""` | 当前输入值 |
| `disabled` | `boolean` | `false` | 输入框是否禁用 |
| `readonly` | `boolean` | `false` | 输入框是否只读 |
| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 输入框的视觉变体 |
| `compact` | `boolean` | `false` | 是否使用紧凑间距 |
| `style` | `string` | `""` | 附加 CSS 样式 |
| `prefix` | `string` | `""` | 显示的文本前缀 |
| `suffix` | `string` | `""` | 显示的文本后缀 |
| `removable` | `boolean` | `true` | 是否显示清除按钮 |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式（编辑/查看） |
| `class` | `string` | `""` | CSS 类名 |

## 事件

文本编辑器组件转发所有原生输入事件：

| 事件 | 描述 |
|-------|-------------|
| `input` | 每次输入更改时触发 |
| `change` | 输入框失去焦点或按下回车键时触发 |
| `focus` | 输入框获得焦点时触发 |
| `blur` | 输入框失去焦点时触发 |
| `keydown` | 按下键盘按键时触发 |
| `keyup` | 释放键盘按键时触发 |
| `keypress` | 按下键盘按键时触发 |
| `compositionstart` | IME 组合输入开始时触发 |
| `compositionend` | IME 组合输入结束时触发 |
| `compositionupdate` | IME 组合输入期间触发 |

## 方法

| 方法 | 描述 |
|--------|-------------|
| `setFocus()` | 以编程方式使输入框获得焦点 |

## 示例

### 基本文本输入

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let userName = '';
  let email = '';
</script>

<div class="form-group">
  <label>用户名：</label>
  <TextEditor bind:value={userName} placeholder="输入用户名" />
</div>

<div class="form-group">
  <label>邮箱：</label>
  <TextEditor bind:value={email} placeholder="输入邮箱地址" />
</div>

<style>
  .form-group {
    margin-bottom: 16px;
  }
  
  label {
    display: block;
    margin-bottom: 4px;
    font-weight: 500;
  }
</style>
```

### 带事件处理程序

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let inputValue = '';
  let isFocused = false;
  
  function handleInput(event) {
    console.log('输入更改：', event.target.value);
  }
  
  function handleChange(event) {
    console.log('更改确认：', event.target.value);
  }
  
  function handleFocus(event) {
    console.log('输入框已聚焦');
    isFocused = true;
  }
  
  function handleBlur(event) {
    console.log('输入框已失焦');
    isFocused = false;
  }
</script>

<TextEditor 
  bind:value={inputValue}
  placeholder="输入一些内容..."
  on:input={handleInput}
  on:change={handleChange}
  on:focus={handleFocus}
  on:blur={handleBlur}
/>

{#if isFocused}
  <p>输入框当前已聚焦</p>
{/if}
```

### 不同变体

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let value1 = '', value2 = '', value3 = '', value4 = '';
</script>

<!-- 默认变体 -->
<TextEditor bind:value={value1} placeholder="默认" />

<!-- 简单变体 -->
<TextEditor bind:value={value2} variant="plain" placeholder="简单" />

<!-- 轮廓变体 -->
<TextEditor bind:value={value3} variant="outlined" placeholder="轮廓" />

<!-- 填充变体 -->
<TextEditor bind:value={value4} variant="filled" placeholder="填充" />
```

### 带前缀和后缀

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let amount = '';
  let website = '';
  let username = '';
</script>

<!-- 带前缀的货币输入 -->
<TextEditor 
  bind:value={amount} 
  prefix="$" 
  placeholder="0.00"
/>

<!-- 带前缀的网站 URL -->
<TextEditor 
  bind:value={website} 
  prefix="https://" 
  placeholder="example.com"
/>

<!-- 带后缀的用户名 -->
<TextEditor 
  bind:value={username} 
  suffix="@company.com" 
  placeholder="用户名"
/>
```

### 带图标

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  import Icon from "@ticatec/uniface-element/Icon";
  
  let searchTerm = '';
  let email = '';
</script>

<!-- 带前导图标的搜索输入 -->
<TextEditor bind:value={searchTerm} placeholder="搜索...">
  <svelte:fragment slot="leading-icon">
    <Icon name="search" />
  </svelte:fragment>
</TextEditor>

<!-- 带尾随图标的邮箱输入 -->
<TextEditor bind:value={email} placeholder="输入邮箱">
  <svelte:fragment slot="trailing-icon">
    <Icon name="email" />
  </svelte:fragment>
</TextEditor>
```

### 禁用和只读状态

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let normalValue = '';
  let readonlyValue = '这是只读的';
  let disabledValue = '';
</script>

<!-- 正常输入 -->
<TextEditor bind:value={normalValue} placeholder="正常输入" />

<!-- 只读输入 -->
<TextEditor bind:value={readonlyValue} readonly />

<!-- 禁用输入 -->
<TextEditor bind:value={disabledValue} disabled placeholder="禁用输入" />
```

### 紧凑模式

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let compactValue = '';
</script>

<div class="toolbar">
  <TextEditor 
    bind:value={compactValue} 
    compact 
    placeholder="紧凑输入" 
  />
</div>

<style>
  .toolbar {
    display: flex;
    align-items: center;
    padding: 8px;
    background: #f8f9fa;
  }
</style>
```

### 无清除按钮

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  
  let value = '';
</script>

<TextEditor 
  bind:value 
  removable={false}
  placeholder="无清除按钮"
/>
```

### 表单集成

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  import Button from "@ticatec/uniface-element/Button";
  
  let formData = {
    firstName: '',
    lastName: '',
    company: '',
    title: ''
  };
  
  function handleSubmit() {
    console.log('表单提交：', formData);
  }
  
  function resetForm() {
    formData = {
      firstName: '',
      lastName: '',
      company: '',
      title: ''
    };
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <div class="form-row">
    <div class="form-field">
      <label>名字</label>
      <TextEditor bind:value={formData.firstName} placeholder="张" />
    </div>
    <div class="form-field">
      <label>姓氏</label>
      <TextEditor bind:value={formData.lastName} placeholder="伟" />
    </div>
  </div>
  
  <div class="form-field">
    <label>公司</label>
    <TextEditor bind:value={formData.company} placeholder="某某公司" />
  </div>
  
  <div class="form-field">
    <label>职位</label>
    <TextEditor bind:value={formData.title} placeholder="软件工程师" />
  </div>
  
  <div class="form-actions">
    <Button type="secondary" label="重置" onClick={resetForm} />
    <Button type="primary" label="提交" onClick={handleSubmit} />
  </div>
</form>

<style>
  .form-row {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 16px;
    margin-bottom: 16px;
  }
  
  .form-field {
    margin-bottom: 16px;
  }
  
  label {
    display: block;
    margin-bottom: 4px;
    font-weight: 500;
  }
  
  .form-actions {
    display: flex;
    gap: 12px;
    justify-content: flex-end;
  }
</style>
```

### 编程式焦点

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  import Button from "@ticatec/uniface-element/Button";
  
  let textEditor;
  let inputValue = '';
  
  function focusInput() {
    textEditor.setFocus();
  }
</script>

<Button label="聚焦输入框" onClick={focusInput} />

<TextEditor 
  bind:this={textEditor}
  bind:value={inputValue}
  placeholder="点击按钮聚焦我"
/>
```

### 显示模式

```svelte
<script>
  import TextEditor from "@ticatec/uniface-element/TextEditor";
  import { DisplayMode } from "@ticatec/uniface-element/common/DisplayMode";
  
  let value = '示例文本';
  let isEditing = false;
</script>

<button on:click={() => isEditing = !isEditing}>
  {isEditing ? '切换到查看模式' : '切换到编辑模式'}
</button>

<TextEditor 
  bind:value 
  displayMode={isEditing ? DisplayMode.Edit : DisplayMode.View}
  placeholder="输入文本..."
/>
```

## 功能

- **全面事件处理**：自动转发所有原生输入事件
- **高级输入支持**：处理国际化文本输入的组合事件
- **灵活显示**：支持编辑和查看模式
- **清除功能**：可选的清除按钮，行为可自定义
- **图标支持**：支持前导和尾随图标插槽
- **前缀/后缀**：支持文本前缀和后缀
- **焦点管理**：支持编程式焦点控制
- **灵活样式**：支持多种视觉变体和自定义样式

## 事件转发

文本编辑器组件使用高级事件转发系统，自动转发所有原生输入事件，同时允许对特定事件（如 `input` 和 `change`）进行自定义处理。

## 可访问性

- 适当的语义化 HTML 结构
- 支持键盘导航
- 屏幕阅读器兼容
- 焦点指示器和管理
- 适当的 ARIA 属性

## 最佳实践

1. **事件处理**：使用 `on:input` 进行实时反馈，使用 `on:change` 进行确认更改
2. **验证**：在事件处理程序中实现验证逻辑
3. **占位符文本**：提供有用的占位符文本以提升用户体验
4. **标签**：始终将输入框与适当的标签关联
5. **错误状态**：适当处理和显示验证错误
6. **焦点管理**：使用编程式焦点提升可访问性

## 浏览器支持

- 支持完整输入事件的现代浏览器
- 兼容 Svelte 5+
- 支持国际化输入法编辑器（IME）
- 触控友好界面

## 相关组件

- `PasswordEditor` - 带可见性切换的专用密码输入
- `SearchBox` - 带内置搜索图标的搜索专用输入
- `NumberEditor` - 带验证的数字输入
- `MemoEditor` - 多行文本输入（textarea）
- `PromptsTextEditor` - 带自动建议的文本输入