# 提示文本编辑器组件

一个带自动建议功能的文本输入组件，点击时显示预定义单词/提示的下拉菜单。适用于用户需要从一组已知选项中输入并支持自定义输入的场景。

## 安装

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

## 导入

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

## 基本用法

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let value = '';
  let suggestions = ['苹果', '香蕉', '樱桃', '枣', '接骨木'];
  
  function handleChange(newValue) {
    console.log('值已更改：', newValue);
  }
</script>

<PromptsTextEditor 
  bind:value 
  words={suggestions} 
  onchange={handleChange} 
  placeholder="输入或选择一种水果..."
/>
```

## 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `value` | `string \| null` | 必需 | 当前输入值 |
| `words` | `Array<string>` | 必需 | 显示的建议单词数组 |
| `onchange` | `OnChangeHandler<string \| null>` | `null` | 值更改时的回调函数 |
| `onfocus` | `((event: FocusEvent) => void) \| null` | `null` | 输入框获得焦点时的回调函数 |
| `onblur` | `((event: FocusEvent) => void) \| null` | `null` | 输入框失去焦点时的回调函数 |
| `disabled` | `boolean` | `false` | 输入框是否禁用 |
| `readonly` | `boolean` | `false` | 输入框是否只读 |
| `placeholder` | `string` | `""` | 占位符文本 |
| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 输入框的视觉变体 |
| `compact` | `boolean` | `false` | 是否使用紧凑间距 |
| `prefix` | `string` | `""` | 显示的文本前缀 |
| `suffix` | `string` | `""` | 显示的文本后缀 |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式（编辑/查看） |
| `removable` | `boolean` | `true` | 是否显示清除按钮 |
| `menu$height` | `number` | `0` | 下拉菜单的固定高度 |
| `style` | `string` | `""` | 附加 CSS 样式 |
| `class` | `string` | `""` | CSS 类名 |

## 示例

### 基本文本提示

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let selectedTag = '';
  let availableTags = [
    'JavaScript', 'TypeScript', 'Svelte', 'React', 'Vue',
    'Python', 'Java', 'C++', 'Go', 'Rust'
  ];
</script>

<PromptsTextEditor 
  bind:value={selectedTag}
  words={availableTags}
  placeholder="选择或输入一种编程语言..."
/>
```

### 带事件处理程序

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let currentValue = '';
  let commands = [
    'git add .', 'git commit -m', 'git push origin', 
    'npm install', 'npm run build', 'npm test'
  ];
  
  function handleValueChange(newValue) {
    console.log('命令已更改：', newValue);
  }
  
  function handleFocus(event) {
    console.log('输入框已聚焦');
  }
  
  function handleBlur(event) {
    console.log('输入框已失焦');
  }
</script>

<PromptsTextEditor 
  bind:value={currentValue}
  words={commands}
  onchange={handleValueChange}
  onfocus={handleFocus}
  onblur={handleBlur}
  placeholder="输入或选择一个命令..."
/>
```

### 不同变体

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let value1 = '', value2 = '', value3 = '';
  let options = ['选项 1', '选项 2', '选项 3'];
</script>

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

<!-- 轮廓变体 -->
<PromptsTextEditor bind:value={value2} words={options} variant="outlined" placeholder="轮廓" />

<!-- 填充变体 -->
<PromptsTextEditor bind:value={value3} words={options} variant="filled" placeholder="填充" />
```

### 带图标

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  import Icon from "@ticatec/uniface-element/Icon";
  
  let searchQuery = '';
  let recentSearches = [
    'JavaScript 教程', 'Svelte 组件', 'TypeScript 类型',
    'CSS 动画', 'HTML 语义'
  ];
</script>

<PromptsTextEditor 
  bind:value={searchQuery}
  words={recentSearches}
  placeholder="搜索...">
  <svelte:fragment slot="leading-icon">
    <Icon name="search" />
  </svelte:fragment>
</PromptsTextEditor>
```

### 自定义菜单高度

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let selectedItem = '';
  let longList = Array.from({length: 50}, (_, i) => `项目 ${i + 1}`);
</script>

<PromptsTextEditor 
  bind:value={selectedItem}
  words={longList}
  menu$height={200}
  placeholder="从多个选项中选择..."
/>
```

### 表单集成

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  import Button from "@ticatec/uniface-element/Button";
  
  let formData = {
    category: '',
    priority: '',
    status: ''
  };
  
  const categories = ['错误', '功能', '增强', '文档'];
  const priorities = ['低', '中', '高', '紧急'];
  const statuses = ['开放', '进行中', '审核', '关闭'];
  
  function handleSubmit() {
    console.log('表单提交：', formData);
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <div class="form-field">
    <label>类别</label>
    <PromptsTextEditor 
      bind:value={formData.category}
      words={categories}
      placeholder="选择类别..."
    />
  </div>
  
  <div class="form-field">
    <label>优先级</label>
    <PromptsTextEditor 
      bind:value={formData.priority}
      words={priorities}
      placeholder="选择优先级..."
    />
  </div>
  
  <div class="form-field">
    <label>状态</label>
    <PromptsTextEditor 
      bind:value={formData.status}
      words={statuses}
      placeholder="选择状态..."
    />
  </div>
  
  <Button type="primary" label="提交" onClick={handleSubmit} />
</form>

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

### 禁用和只读状态

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let value1 = '只读值';
  let value2 = '';
  let options = ['选项 A', '选项 B', '选项 C'];
</script>

<!-- 只读 -->
<PromptsTextEditor 
  bind:value={value1} 
  words={options} 
  readonly 
  placeholder="这是只读的"
/>

<!-- 禁用 -->
<PromptsTextEditor 
  bind:value={value2} 
  words={options} 
  disabled 
  placeholder="这是禁用的"
/>
```

## 功能

- **自动建议**：显示预定义单词/提示的下拉列表
- **自由文本输入**：用户可以输入不在建议列表中的自定义值
- **清除功能**：当 `removable` 为 true 时显示可选的清除按钮
- **焦点管理**：自动处理焦点及相关事件
- **键盘导航**：支持通过键盘导航建议选项
- **灵活样式**：支持多种视觉变体和自定义样式
- **图标支持**：支持前导图标插槽以提供额外上下文

## 行为

1. **下拉触发**：点击下拉箭头显示所有可用选项
2. **选择**：点击任意选项进行选择并关闭下拉菜单
3. **自由输入**：输入任意文本，即使不在建议列表中
4. **清除操作**：点击清除按钮（启用时）清空输入框
5. **点击外部**：点击组件外部时关闭下拉菜单

## 样式

组件继承自基础 `CommonEditor` 的样式，并可通过以下方式自定义：

- CSS 自定义属性（在主题中定义）
- `style` 属性用于内联样式
- `class` 属性用于自定义 CSS 类
- `variant` 属性用于预定义视觉样式

## 可访问性

- 全面支持键盘导航
- 屏幕阅读器兼容
- 焦点管理和指示器
- 语义化 HTML 结构
- 下拉交互的 ARIA 属性

## 最佳实践

1. **建议质量**：提供符合用户预期的相关且有用的建议
2. **列表长度**：保持建议列表长度适中（少于 20 项以获得最佳用户体验）
3. **自定义高度**：对长列表使用 `menu$height` 以防止 UI 溢出
4. **清晰标签**：提供描述性的占位符和标签
5. **事件处理**：使用 `onchange`、`onfocus` 和 `onblur` 进行适当的表单集成
6. **状态管理**：绑定到响应式变量以确保状态正确更新

## 浏览器支持

- 支持 ES6+ 的现代浏览器
- 兼容 Svelte 5+
- 响应式设计原则

## 相关组件

- `TextEditor` - 不带建议的简单文本输入
- `OptionsSelect` - 从预定义选项中进行下拉选择
- `OptionsMultiSelect` - 多选下拉菜单
- `LookupEditor` - 具有搜索功能的高级查找组件