# Input 输入框控件族

## 概述

输入框是图形界面中最基础的表单域控件，用于通过键盘输入内容。AtomUI 的 Input 控件族完整复刻了 [Ant Design 5.0 Input](https://ant.design/components/input-cn) 的设计规范，在 .NET / Avalonia 平台上提供与 Ant Design React 版一致的视觉体验和交互行为。

AtomUI 的 Input 控件族包含以下控件：

| 控件 | 对应 Ant Design | 说明 |
|---|---|---|
| `TextBox` | — | 底层基础文本输入控件（内部基类） |
| `LineEdit` | `Input` | 单行输入框，支持前缀/后缀装饰、左右附加组件（AddOn） |
| `SearchEdit` | `Input.Search` | 搜索输入框，带有搜索按钮 |
| `TextArea` | `Input.TextArea` | 多行文本域，支持自适应高度、字符计数、可拖拽调整大小 |

> 注意：Ant Design 的 `Input.Password` 在 AtomUI 中并非独立控件，而是通过 `LineEdit` 的 `PasswordChar` + `IsEnableRevealButton` 属性组合实现。

---

## 设计原理

### Ant Design 的输入框设计哲学

Ant Design 对输入框的定位是：**「通过鼠标或键盘输入内容，是最基础的表单域的包装」**。为了适配不同的使用场景，Ant Design 建立了一套完整的输入框变体体系：

**四种输入框变体**：

| 变体 | 设计意图 | 典型用途 |
|---|---|---|
| 📝 **基础输入框（Input）** | 最常用的单行文本输入 | 用户名、邮箱、地址等 |
| 🔍 **搜索框（Input.Search）** | 带搜索操作的输入框，右侧附带搜索按钮或图标 | 全局搜索、列表过滤 |
| 🔒 **密码框（Input.Password）** | 遮蔽输入内容，带可选的明文切换按钮 | 登录密码、安全验证 |
| 📄 **文本域（Input.TextArea）** | 多行文本输入，可自适应高度 | 评论、备注、描述 |

**四种样式变体**（所有输入框类型均支持）：

| 变体 | 设计意图 |
|---|---|
| 📦 **Outline（默认）** | 标准边框样式，最通用的输入框外观 |
| 🎨 **Filled** | 填充背景样式，在复杂表单中降低视觉噪音 |
| ➖ **Borderless** | 无边框样式，用于特定场景下的极简风格 |
| 📏 **Underlined** | 下划线样式，Material Design 风格 |

**两种验证状态**：

| 状态 | 设计意图 |
|---|---|
| ⚠️ **Warning** | 橙色边框，提示用户输入可能存在问题 |
| ❌ **Error** | 红色边框，明确告知用户输入不合法 |

### Avalonia TextBox 基础能力

AtomUI 的输入框控件族构建在 Avalonia 框架的 `Avalonia.Controls.TextBox` 之上。Avalonia TextBox 的继承链为：

```
Control → TemplatedControl → InputElement → TextBox
```

**Avalonia TextBox 提供的核心能力：**

| 能力 | 说明 |
|---|---|
| 文本编辑 | `Text` 双向绑定、光标管理（`CaretIndex`）、选区（`SelectionStart` / `SelectionEnd`） |
| 密码模式 | `PasswordChar` 掩码字符、`RevealPassword` 明文切换 |
| 多行支持 | `AcceptsReturn`、`AcceptsTab`、`MaxLines` / `MinLines` |
| 输入限制 | `MaxLength`、`IsReadOnly` |
| 占位文本 | `Watermark`（AtomUI 使用 `PlaceholderText` 替代） |
| 滚动支持 | 内置 `ScrollViewer` 支持文本超出可视区域时滚动 |
| 键盘导航 | 支持 Tab 导航、焦点管理 |

**Avalonia TextBox 提供的基础伪类：**

| 伪类 | 说明 |
|---|---|
| `:pointerover` | 鼠标悬浮 |
| `:focus` | 获得焦点 |
| `:focus-visible` | 通过键盘获得焦点 |
| `:disabled` | `IsEnabled == false` |
| `:empty` | 文本为空 |

### AtomUI 的扩展设计

AtomUI 在 Avalonia TextBox 的基础上，遵循 Ant Design 5.0 规范做了以下扩展：

| 扩展能力 | 实现方式 | 设计动机 |
|---|---|---|
| **四种样式变体** | `StyleVariant` 枚举 + 伪类驱动样式 | 对齐 Ant Design 的 `variant` 属性 |
| **验证状态反馈** | `Status` 枚举 + `IInputControlStatusAware` 接口 | 对齐 Ant Design 的 `status`，与 Form 表单验证无缝集成 |
| **三种尺寸** | `ISizeTypeAware` 接口 + `SizeType` 共享属性 | 全局统一的 Large / Middle / Small 尺寸系统 |
| **AddOn 装饰机制** | `AddOnDecoratedBox` 容器 | 支持左右附加组件（LeftAddOn / RightAddOn）和内部前后缀装饰 |
| **清除按钮** | `IsAllowClear` 属性 + `InputClearIconButton` | 内置清除图标，点击清空输入内容 |
| **密码显示切换** | `IsEnableRevealButton` + `RevealButton` | 复刻 Ant Design Input.Password 的密码可见性切换 |
| **字符计数** | `IsShowCount` + `MaxLength` | 实时显示已输入字符数 / 最大字符数 |
| **搜索按钮** | `SearchEdit` + `SearchButton` | 复刻 Ant Design Input.Search 的搜索按钮交互 |
| **自适应高度** | `TextArea.IsAutoSize` + `MinLines` / `MaxLines` | 文本域根据内容自动调整高度 |
| **可拖拽调整** | `TextArea.IsResizable` + `ResizeHandle` | 文本域支持拖拽调整大小 |
| **紧凑空间** | `ICompactSpaceAware` 接口 | 在 `Space.Compact` 中自动调整圆角和边框 |
| **表单集成** | `IFormItemAware` + `IFormItemFeedbackAware` | 可参与 FormItem 验证流程 |
| **Design Token** | `LineEditToken` / `TextAreaToken` | 所有视觉值从全局 Token 派生，支持主题切换 |

---

## 控件层级关系

Input 控件族的所有控件均定义在桌面端控件层（`AtomUI.Desktop.Controls`），没有对应的设备无关基类（`AtomUI.Controls` 层），因为这些控件直接继承自 Avalonia 的 `TextBox`。

```
Avalonia.Controls.TextBox
  └── AtomUI.Desktop.Controls.TextBox (ISizeTypeAware, IMotionAwareControl, ICompactSpaceAware, IFormItemAware)
        ├── AtomUI.Desktop.Controls.LineEdit (+ IInputControlStatusAware, IInputControlStyleVariantAware)
        │     └── AtomUI.Desktop.Controls.SearchEdit (+ SearchButtonClick 事件)
        └── [独立继承]
             AtomUI.Desktop.Controls.TextArea (ISizeTypeAware, IMotionAwareControl, IInputControlStatusAware, IInputControlStyleVariantAware, IFormItemAware)
```

### 各层级职责划分

| 层级 | 提供的能力 |
|---|---|
| `Avalonia.Controls.TextBox` | 文本编辑（输入/删除/选区/光标）、密码模式、多行支持、输入限制、滚动、键盘导航 |
| `AtomUI.Desktop.Controls.TextBox` | 尺寸系统（`SizeType`）、清除按钮（`IsAllowClear`）、密码可见性切换（`IsEnableRevealButton`）、字符计数（`IsShowCount`）、占位文本（`PlaceholderText`）、紧凑空间适配、表单集成、过渡动画 |
| `AtomUI.Desktop.Controls.LineEdit` | 样式变体（`StyleVariant`）、验证状态（`Status`）、AddOn 装饰（LeftAddOn / RightAddOn + InnerLeftContentTemplate / InnerRightContentTemplate）、与 `AddOnDecoratedBox` 集成 |
| `AtomUI.Desktop.Controls.SearchEdit` | 搜索按钮样式（`SearchButtonStyle`）、搜索按钮文本（`SearchButtonText`）、加载状态（`IsOperating`）、搜索按钮点击事件（`SearchButtonClick`） |
| `AtomUI.Desktop.Controls.TextArea` | 多行输入（`Lines`）、自适应高度（`IsAutoSize`）、可拖拽调整大小（`IsResizable`）、样式变体、验证状态、内部前后缀装饰 |

### 实现的共享接口

| 接口 | 定义位置 | 控件 | 作用 |
|---|---|---|---|
| `ISizeTypeAware` | `AtomUI.Controls.Shared` | TextBox, TextArea | 支持 `SizeType`（Small / Middle / Large）尺寸切换 |
| `IMotionAwareControl` | `AtomUI.Controls.Shared` | TextBox, TextArea | 支持动画开关 |
| `ICompactSpaceAware` | `AtomUI.Controls.Shared` | TextBox | 在 `Space.Compact` 中使用时自动调整圆角和边框 |
| `IFormItemAware` | `AtomUI.Controls.Shared` | TextBox, TextArea | 参与 FormItem 表单验证 |
| `IFormItemFeedbackAware` | `AtomUI.Controls.Shared` | TextBox, TextArea | 接收表单验证反馈控件 |
| `IInputControlStatusAware` | `AtomUI.Controls.Shared` | LineEdit, TextArea | 支持验证状态反馈（Error / Warning） |
| `IInputControlStyleVariantAware` | `AtomUI.Controls.Shared` | LineEdit, TextArea | 支持样式变体切换（Outline / Filled / Borderless） |

---

## 功能详解

### 装饰机制（AddOnDecoratedBox）

LineEdit 使用 `AddOnDecoratedBox` 作为装饰容器，提供了灵活的布局扩展能力：

```
┌──────────────────────────────────────────────────────────────────────┐
│ LeftAddOn │ InnerLeft │ [Text Input] │ InnerRight │ RightAddOn │
│  (http://)│  (🔍 icon)│              │ (clear/eye)│  (.com)    │
└──────────────────────────────────────────────────────────────────────┘
```

- **LeftAddOn / RightAddOn**：输入框外侧的附加组件，通过 `AddOnDecoratedBox` 的外部附加区域实现，常用于固定的前缀/后缀标签（如 `http://`、`.com`）。
- **InnerLeftContentTemplate / InnerRightContentTemplate**：输入框内侧的装饰元素，位于 `AddOnDecoratedBox` 的内容区域内，常用于图标（搜索图标、用户图标）。
- **ContentRightAddOn**（模板内部）：清除按钮、密码切换按钮、表单反馈图标等功能性元素。

### 搜索框特性（SearchEdit）

SearchEdit 继承自 LineEdit，额外提供：

- **SearchButtonStyle**：搜索按钮样式，支持 `Default`（仅图标）和 `Primary`（主色调按钮）两种。
- **SearchButtonText**：搜索按钮文字，设置后按钮显示文字而非图标。
- **IsOperating**：加载状态，设为 `true` 时搜索按钮显示加载动画。
- **SearchButtonClick**：搜索按钮点击事件，路由事件（Bubble 策略）。

搜索框内部使用 `SearchEditDecoratedBox`（继承自 `AddOnDecoratedBox`）和 `SearchEditPanel`（自定义 Panel）实现独特的搜索按钮布局。

### 多行文本域特性（TextArea）

TextArea 独立继承自 Avalonia TextBox（不通过 AtomUI TextBox），提供：

- **Lines**：指定显示行数（默认 2），自动计算高度。
- **IsAutoSize**：开启后根据输入内容自动调整高度。
- **MinLines / MaxLines**：配合 `IsAutoSize` 限制自适应高度范围。
- **IsResizable**：开启后右下角显示拖拽手柄，可手动调整高度。
- **字符计数**：通过 `IsShowCount` + `MaxLength` 显示 `已输入 / 最大` 格式的计数。

TextArea 内部使用 `TextAreaDecoratedBox`（继承自 `AddOnDecoratedBox`）和 `ResizeHandle`（拖拽手柄控件）。

### 清除与密码切换

- **清除按钮**：由 `InputClearIconButton`（继承自 `IconButton`）实现，默认使用 `CloseCircleFilled` 图标。仅当 `IsAllowClear == true` 且文本不为空且非只读时显示。
- **密码切换按钮**：由 `RevealButton`（继承自 `ToggleIconButton`）实现，默认使用 `EyeOutlined`（已选中/可见）和 `EyeInvisibleOutlined`（未选中/隐藏）图标，通过 `IsEnableRevealButton` 启用。

### 表单集成

TextBox 和 TextArea 均实现了 `IFormItemAware` 和 `IFormItemFeedbackAware` 接口：

- **SetFormValue / GetFormValue / ClearFormValue**：表单系统可通过统一接口读写输入值。
- **NotifyValidateStatus**：表单验证失败时自动设置 `Status`（仅 LineEdit 和 TextArea 支持，因为它们实现了 `IInputControlStatusAware`）。
- **SetFeedbackControl**：接收并显示表单验证反馈控件（如错误/成功图标）。

### CompactSpace 支持

TextBox 实现了 `ICompactSpaceAware` 接口，在 `Space.Compact` 容器中：
- 根据位置（First / Middle / Last / OnlyOne）自动裁剪圆角。
- LineEdit 会根据内部 `AddOnDecoratedBox` 的边框厚度提供紧凑边框值。

---

## 与 Ant Design 规范的对齐程度

| 特性 | Ant Design (React) | AtomUI (Avalonia) | 对齐情况 |
|---|---|---|---|
| 基础输入 `Input` | ✅ | ✅ `LineEdit` | ✅ 完全对齐 |
| 搜索框 `Input.Search` | ✅ | ✅ `SearchEdit` | ✅ 完全对齐 |
| 密码框 `Input.Password` | ✅ 独立组件 | ✅ `LineEdit` + `PasswordChar` + `IsEnableRevealButton` | ✅ 功能对齐（非独立组件） |
| 文本域 `Input.TextArea` | ✅ | ✅ `TextArea` | ✅ 完全对齐 |
| 前缀/后缀 `prefix`/`suffix` | ✅ | ✅ `InnerLeftContentTemplate` / `InnerRightContentTemplate` | ✅ 完全对齐 |
| 前置/后置标签 `addonBefore`/`addonAfter` | ✅ | ✅ `LeftAddOn` / `RightAddOn` | ✅ 完全对齐 |
| 样式变体 `variant` | ✅ `outlined/filled/borderless` | ✅ `StyleVariant` + `Underlined` | ✅ 完全对齐（多一个 Underlined） |
| 验证状态 `status` | ✅ `error/warning` | ✅ `Status` | ✅ 完全对齐 |
| 允许清除 `allowClear` | ✅ | ✅ `IsAllowClear` | ✅ 完全对齐 |
| 字符计数 `showCount` | ✅ | ✅ `IsShowCount` | ✅ 完全对齐 |
| 自适应高度 `autoSize` | ✅ | ✅ `IsAutoSize` + `MinLines` / `MaxLines` | ✅ 完全对齐 |
| 搜索按钮 `enterButton` | ✅ | ✅ `SearchButtonStyle` + `SearchButtonText` | ✅ 完全对齐 |
| 搜索加载 `loading` | ✅ | ✅ `IsOperating` | ✅ 完全对齐 |
| 禁用 `disabled` | ✅ | ✅ `IsEnabled` | ✅ 完全对齐 |
| 可拖拽调整大小 | ✅ CSS resize | ✅ `IsResizable` + `ResizeHandle` | ✅ 完全对齐 |
| `onChange` 回调 | ✅ | ✅ `TextChangedEvent` + `IFormItemAware.ValueChanged` | ✅ 完全对齐 |
| `onSearch` 回调 | ✅ | ✅ `SearchButtonClick` 事件 | ✅ 完全对齐 |

---

## 源码位置

| 层级 | 文件路径 | 说明 |
|---|---|---|
| TextBox 基类 | `src/AtomUI.Desktop.Controls/Input/TextBox.cs` | 底层文本输入控件（内部基类） |
| LineEdit 控件 | `src/AtomUI.Desktop.Controls/Input/LineEdit.cs` | 单行输入框实现 |
| SearchEdit 控件 | `src/AtomUI.Desktop.Controls/Input/SearchEdit.cs` | 搜索输入框实现 |
| TextArea 控件 | `src/AtomUI.Desktop.Controls/Input/TextArea.cs` | 多行文本域实现 |
| LineEdit Token | `src/AtomUI.Desktop.Controls/Input/LineEditToken.cs` | LineEdit / TextBox 组件 Token |
| TextArea Token | `src/AtomUI.Desktop.Controls/Input/TextAreaToken.cs` | TextArea 组件 Token |
| TextBox 主题 | `src/AtomUI.Desktop.Controls/Input/Themes/TextBoxTheme.axaml` | TextBox ControlTheme |
| LineEdit 主题 | `src/AtomUI.Desktop.Controls/Input/Themes/LineEditTheme.axaml` | LineEdit ControlTheme |
| SearchEdit 主题 | `src/AtomUI.Desktop.Controls/Input/Themes/SearchEditTheme.axaml` | SearchEdit ControlTheme |
| TextArea 主题 | `src/AtomUI.Desktop.Controls/Input/Themes/TextAreaTheme.axaml` | TextArea ControlTheme |
| 主题常量 | `src/AtomUI.Desktop.Controls/Input/Themes/InputThemeConstants.cs` | 模板部件名称常量 |
| 搜索按钮 | `src/AtomUI.Desktop.Controls/Input/SearchButton.cs` | 搜索按钮内部控件 |
| 搜索装饰盒 | `src/AtomUI.Desktop.Controls/Input/SearchEditDecoratedBox.cs` | 搜索编辑框装饰容器 |
| 搜索布局面板 | `src/AtomUI.Desktop.Controls/Input/SearchEditPanel.cs` | 搜索编辑框布局面板 |
| 清除按钮 | `src/AtomUI.Desktop.Controls/Input/InputClearIconButton.cs` | 清除图标按钮 |
| 密码切换按钮 | `src/AtomUI.Desktop.Controls/Input/RevealButton.cs` | 密码显示/隐藏切换按钮 |
| 文本域装饰盒 | `src/AtomUI.Desktop.Controls/Input/TextAreaDecoratedBox.cs` | 文本域装饰容器 |
| 拖拽手柄 | `src/AtomUI.Desktop.Controls/Input/ResizeHandle.cs` | 文本域拖拽调整大小手柄 |
| Gallery 示例 | `controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/LineEditShowCase.axaml` | 使用范例 |

---

## 模板结构

### LineEdit 模板结构

LineEdit 使用 `AddOnDecoratedBox` 作为根容器，提供完整的装饰能力：

```
AddOnDecoratedBox (PART_AddOnDecoratedBox)
├── [LeftAddOn 区域]                    ← 左侧附加组件（如 "http://"）
├── [ContentLeftAddOn 区域]             ← 内侧左装饰（如用户图标）
├── [主内容区域]
│   └── ScrollViewer (PART_ScrollViewer)
│       └── Panel
│           ├── TextBlock#Placeholder   ← 占位文本（Text 为空时显示）
│           └── TextPresenter           ← 文本展示器（PART_TextPresenter）
├── [ContentRightAddOn 区域]            ← 内侧右装饰
│   └── StackPanel (Horizontal)
│       ├── InputClearIconButton        ← 清除按钮（PART_ClearButton）
│       ├── RevealButton                ← 密码显示切换（PART_RevealButton）
│       ├── ContentPresenter#FormFeedBack ← 表单验证反馈图标
│       ├── ContentPresenter            ← InnerRightContent 展示
│       └── TextBlock#TextCountIndicator ← 字符计数显示
└── [RightAddOn 区域]                   ← 右侧附加组件（如 ".com"）
```

### SearchEdit 模板结构

SearchEdit 的模板基于 LineEdit，但使用 `SearchEditDecoratedBox` 替代标准 `AddOnDecoratedBox`，搜索按钮通过 `SearchEditPanel` 进行特殊布局。

### TextArea 模板结构

```
DockPanel
├── TextBlock#TextCountIndicator (Dock=Bottom) ← 字符计数（底部对齐）
└── Panel
    ├── TextAreaDecoratedBox (PART_AddOnDecoratedBox)
    │   ├── [ContentRightAddOn 区域]
    │   │   └── StackPanel (Vertical)
    │   │       ├── InputClearIconButton  ← 清除按钮（PART_ClearButton）
    │   │       ├── ContentPresenter#FormFeedBack ← 表单反馈
    │   │       └── ContentPresenter      ← InnerRightContent
    │   └── Panel#ContentLayout
    │       ├── TextBlock#Placeholder     ← 占位文本
    │       └── TextPresenter             ← 文本展示器（PART_TextPresenter）
    └── ResizeHandle (PART_ResizeHandle)  ← 拖拽调整大小手柄（右下角）
```

### 模板部件常量

| 常量名 | 值 | 说明 |
|---|---|---|
| `TextBoxThemeConstants.ClearButtonPart` | `"PART_ClearButton"` | 清除按钮 |
| `TextBoxThemeConstants.RevealButtonPart` | `"PART_RevealButton"` | 密码显示切换按钮 |
| `TextAreaThemeConstants.ResizeHandle` | `"PART_ResizeHandle"` | 拖拽调整大小手柄 |
| `TextAreaThemeConstants.ScrollViewerPart` | `"PART_ScrollViewer"` | 文本域滚动容器 |
| `TextAreaThemeConstants.ClearButtonPart` | `"PART_ClearButton"` | 文本域清除按钮 |
| `TextAreaThemeConstants.TextPresenterPart` | `"PART_TextPresenter"` | 文本展示器 |