# Uniface Element 组件使用指南

本指南帮助你根据使用场景选择合适的组件。

## 📋 目录

- [布局组件](#布局组件)
- [表单组件](#表单组件)
- [数据展示](#数据展示)
- [反馈组件](#反馈组件)
- [导航组件](#导航组件)
- [高级组件](#高级组件)

---

## 🏗️ 布局组件

### 应用布局
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **SidebarLayout** | 需要左侧边栏的布局 | 可调整边栏宽度 |
| **HeaderLayout** | 需要顶部标题栏的布局 | 固定顶部，内容滚动 |
| **ClassicLayout** | 完整的应用布局 | 包含头部、侧边栏、主内容和页脚 |
| **ColumnsLayout** | 多列布局 | 响应式列布局 |
| **RowsLayout** | 多行布局 | 响应式行布局 |

### 容器组件
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **Box** | 简单的容器 | 基础样式容器 |
| **Card** | 卡片展示 | 带标题和内容的卡片 |
| **Page** | 页面容器 | 全页面容器 |
| **Accordion** | 折叠面板 | 可展开/折叠的内容区 |
| **Split** | 可调整大小的分割区域 | 拖动调整面板大小 |
| **Separator** | 分隔线 | 视觉分隔元素 |

### 何时使用哪个布局组件？

```
需要整个应用布局？
  ├── 有侧边栏？ → SidebarLayout
  ├── 只有顶部栏？ → HeaderLayout
  ├── 需要完整的经典布局？ → ClassicLayout
  └── 需要多列/多行？ → ColumnsLayout / RowsLayout

需要容器或分隔？
  ├── 卡片展示？ → Card
  ├── 可折叠内容？ → Accordion
  ├── 可调整大小？ → Split
  └── 简单分隔？ → Separator
```

---

## 📝 表单组件

### 基础输入
| 组件 | 使用场景 | 输入类型 |
|------|---------|---------|
| **TextEditor** | 单行文本输入 | 文本、邮箱、网址等 |
| **NumberEditor** | 数字输入 | 整数、小数 |
| **MemoEditor** | 多行文本输入 | 长文本、备注 |
| **TimeEditor** | 时间输入 | 时:分 |
| **UnitNumberEditor** | 带单位的数字 | 金额、尺寸等 |

### 选择组件
| 组件 | 使用场景 | 选择方式 |
|------|---------|---------|
| **CheckBox** | 单个布尔选项 | 勾选框 |
| **RadioButton** | 单选（多选一） | 单选按钮 |
| **Switch** | 开关切换 | 开/关 |
| **OptionsSelect** | 下拉单选 | 下拉框 |
| **OptionsMultiSelect** | 下拉多选 | 多选下拉框 |
| **CascadeOptionsSelect** | 级联选择 | 省市区等 |
| **InputOptionsSelect** | 输入可选择 | 可输入也可选择 |

### 日期和时间
| 组件 | 使用场景 | 功能 |
|------|---------|------|
| **DatePicker** | 日期选择 | 选择日期 |
| **DateTimePicker** | 日期时间选择 | 选择日期和时间 |
| **DateRange** | 日期范围 | 开始和结束日期 |
| **TimeEditor** | 时间选择 | 时:分选择 |

### 文件和数据
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **AttachmentFiles** | 文件上传 | 支持多文件、进度显示 |
| **ImageFiles** | 图片上传 | 专门处理图片 |
| **LookupEditor** | 查找选择 | 弹窗查找选择 |
| **Transfer** | 穿梭框 | 左右选择移动 |

### 高级输入
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **SearchBox** | 搜索输入 | 带搜索图标 |
| **CriteriaField** | 条件字段 | 多条件筛选 |
| **NumberRange** | 数字范围 | 最小值-最大值 |
| **PromptsTextEditor** | 提示文本输入 | 自动完成提示 |
| **InlineCellEditor** | 单元格内编辑 | 表格内编辑 |

### 表单布局
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **FormField** | 表单字段包装 | 标签、错误提示 |
| **FlexForm** | 弹性表单 | 灵活布局 |
| **GridForm** | 网格表单 | 对齐网格 |

### 何时使用哪个表单组件？

```
文本输入？
  ├── 单行文本 → TextEditor
  ├── 多行文本 → MemoEditor
  ├── 数字输入 → NumberEditor
  ├── 带单位数字 → UnitNumberEditor
  ├── 时间输入 → TimeEditor
  └── 需要提示 → PromptsTextEditor

选择输入？
  ├── 是/否 → CheckBox / Switch
  ├── 单选（多选一）→ RadioButton
  ├── 下拉单选 → OptionsSelect
  ├── 下拉多选 → OptionsMultiSelect
  ├── 级联选择 → CascadeOptionsSelect
  └── 可输入可选择 → InputOptionsSelect

日期时间？
  ├── 日期 → DatePicker
  ├── 日期和时间 → DateTimePicker
  ├── 日期范围 → DateRange
  └── 时间 → TimeEditor

文件数据？
  ├── 普通文件 → AttachmentFiles
  ├── 图片 → ImageFiles
  ├── 查找选择 → LookupEditor
  └── 左右选择 → Transfer
```

---

## 📊 数据展示

### 表格组件
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **DataTable** | 完整功能表格 | 分页、排序、选择 |
| **ConciseDataTable** | 简洁表格 | 轻量级表格 |

### 列表组件
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **ListBox** | 列表展示 | 选择列表 |
| **TreeView** | 树形结构 | 分层数据 |

### 进度指示
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **ProgressBar** | 进度条 | 水平/垂直进度 |
| **ProgressStepBar** | 步骤进度 | 多步骤进度指示 |
| **Navigator** | 向导导航 | 步骤导航器 |
| **Tag** | 标签 | 状态标签 |

### 何时使用哪个数据展示组件？

```
表格数据？
  ├── 复杂表格（分页、排序）→ DataTable
  └── 简单表格 → ConciseDataTable

列表数据？
  ├── 平面列表 → ListBox
  └── 树形结构 → TreeView

进度展示？
  ├── 进度百分比 → ProgressBar
  ├── 步骤进度 → ProgressStepBar / Navigator
  └── 状态标签 → Tag
```

---

## 💬 反馈组件

### 对话框
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **Dialog** | 通用对话框 | 自定义内容 |
| **CommonDialog** | 标准对话框 | 确认/取消按钮 |
| **MessageBox** | 消息框 | 信息提示 |
| **Drawer** | 抽屉 | 侧边滑出 |

### 通知
| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **Toast** | 消息提示 | 轻量级提示 |
| **PopupHint** | 弹出提示 | 悬浮提示 |

### 何时使用哪个反馈组件？

```
需要弹窗？
  ├── 完整对话框 → Dialog
  ├── 标准确认框 → CommonDialog / MessageBox
  └── 侧边面板 → Drawer

需要提示？
  ├── 轻量消息 → Toast
  └── 悬浮提示 → PopupHint
```

---

## 🧭 导航组件

| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **Breadcrumbs** | 面包屑导航 | 层级导航 |
| **Tabs** | 标签页 | 内容分组 |
| **NavigatorMenu** | 导航菜单 | 菜单导航 |
| **ActionBar** | 操作栏 | 工具栏 |
| **AppTopBar** | 应用顶部栏 | 顶部应用栏 |
| **ContextMenu** | 右键菜单 | 上下文菜单 |
| **Navigator** | 向导导航 | 步骤向导 |

### 何时使用哪个导航组件？

```
导航类型？
  ├── 层级导航 → Breadcrumbs
  ├── 内容分组 → Tabs
  ├── 菜单 → NavigatorMenu
  ├── 步骤向导 → Navigator
  └── 工具栏 → ActionBar / AppTopBar

交互菜单？
  └── 右键菜单 → ContextMenu
```

---

## 🎨 按钮组件

| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **Button** | 标准按钮 | 多种类型和样式 |
| **IconButton** | 图标按钮 | 只显示图标 |
| **TextButton** | 文本按钮 | 文本样式按钮 |

### 按钮类型选择

```
按钮重要性？
  ├── 主要操作 → type="primary"
  ├── 次要操作 → type="secondary"
  ├── 第三级 → type="third"
  └── 危险操作 → 自定义样式

按钮样式？
  ├── 标准 → variant=""
  ├── 纯净 → variant="plain"
  └── 圆角 → variant="round"
```

---

## 🔧 高级组件

| 组件 | 使用场景 | 特点 |
|------|---------|------|
| **PropertyEditor** | 属性编辑 | 键值对编辑 |
| **Pagination** | 分页 | 数据分页 |
| **PaginationPanel** | 分页面板 | 完整分页控件 |
| **color-picker** | 颜色选择 | 颜色选择器 |

---

## 🎯 场景化选择指南

### 场景 1：用户注册表单
```
需要组件：
├── Page - 页面容器
├── FormField - 表单字段包装
├── TextEditor - 用户名
├── TextEditor - 邮箱
├── PasswordEditor - 密码
├── OptionsSelect - 国家/地区
├── CheckBox - 同意条款
└── Button - 提交按钮

示例代码：
import Page from '@ticatec/uniface-element/Page';
import FormField from '@ticatec/uniface-element/FormField';
import TextEditor from '@ticatec/uniface-element/TextEditor';
import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
import CheckBox from '@ticatec/uniface-element/CheckBox';
import Button from '@ticatec/uniface-element/Button';
```

### 场景 2：数据管理页面
```
需要组件：
├── SidebarLayout - 应用布局
├── DataTable - 数据表格
├── SearchBox - 搜索框
├── CriteriaField - 筛选条件
├── Button - 新增/删除/编辑按钮
├── Pagination - 分页
└── Dialog - 编辑对话框
```

### 场景 3：设置页面
```
需要组件：
├── Page - 页面容器
├── Tabs - 分组设置
├── FormField - 表单字段
├── TextEditor - 文本设置
├── NumberEditor - 数字设置
├── Switch - 开关设置
├── OptionsSelect - 选项设置
└── Button - 保存按钮
```

### 场景 4：向导流程
```
需要组件：
├── Page - 页面容器
├── Navigator - 步骤导航
├── FormField - 表单字段
├── 各种表单组件 - 根据步骤需求
└── Button - 上一步/下一步
```

### 场景 5：文件管理
```
需要组件：
├── DataTable - 文件列表
├── AttachmentFiles - 文件上传
├── Button - 操作按钮
├── SearchBox - 文件搜索
├── CriteriaField - 文件筛选
└── Dialog - 文件详情
```

---

## 📌 快速决策树

```
你需要什么？

1. 布局相关？
   └─→ [布局组件](#布局组件)

2. 收集用户输入？
   └─→ [表单组件](#表单组件)

3. 展示数据列表？
   └─→ [数据展示](#数据展示)

4. 用户反馈或通知？
   └─→ [反馈组件](#反馈组件)

5. 页面导航？
   └─→ [导航组件](#导航组件)

6. 触发操作？
   └─→ [按钮组件](#按钮组件)

7. 高级功能？
   └─→ [高级组件](#高级组件)
```

---

## 💡 最佳实践

### 1. 组件组合模式

```
表单页面：
Page → FormField → [具体输入组件]

布局：
SidebarLayout → Box → Card → [内容]

数据管理：
SidebarLayout → DataTable → Pagination → Dialog → FormField
```

### 2. 响应式考虑

```
桌面端优先：
├── SidebarLayout - 完整侧边栏
└── DataTable - 大表格

移动端友好：
├── HeaderLayout - 简化头部
└── ConciseDataTable - 轻量表格
```

### 3. 无障碍访问

```
所有表单组件配合 FormField 使用
按钮提供明确的 label
对话框提供关闭按钮
导航支持键盘操作
```

---

## 🔍 组件查找速查表

| 需求 | 组件 | 导入路径 |
|------|------|---------|
| 输入文本 | TextEditor | `@ticatec/uniface-element/TextEditor` |
| 输入数字 | NumberEditor | `@ticatec/uniface-element/NumberEditor` |
| 下拉选择 | OptionsSelect | `@ticatec/uniface-element/OptionsSelect` |
| 选择日期 | DatePicker | `@ticatec/uniface-element/DatePicker` |
| 上传文件 | AttachmentFiles | `@ticatec/uniface-element/AttachmentFiles` |
| 数据表格 | DataTable | `@ticatec/uniface-element/DataTable` |
| 弹窗对话框 | Dialog | `@ticatec/uniface-element/Dialog` |
| 侧边抽屉 | Drawer | `@ticatec/uniface-element/Drawer` |
| 消息提示 | Toast | `@ticatec/uniface-element/Toast` |
| 按钮 | Button | `@ticatec/uniface-element/Button` |
| 标签页 | Tabs | `@ticatec/uniface-element/Tabs` |
| 分页 | Pagination | `@ticatec/uniface-element/Pagination` |

---

## 📚 相关文档

- [组件 API 文档](./src/lib)
- [示例代码](./src/routes/demo)
- [贡献指南](./CONTRIBUTING.md)
- [更新日志](./CHANGELOG.md)