@ticatec/uniface-element 0.3.18 → 0.3.19

package/COMPONENT_SELECTION_PROMPTS.md

@@ -0,0 +1,568 @@
+# Uniface Element 组件选择提示词系统
+
+本文档提供了一套结构化的提示词，帮助用户或 AI 助手根据具体使用场景快速选择合适的组件。
+
+---
+
+## 🤖 如何使用此系统
+
+### 作为用户：
+1. 找到符合你需求的场景描述
+2. 查看推荐的组件
+3. 参考示例代码
+
+### 作为 AI 助手：
+当用户描述需求时，使用以下决策逻辑来推荐组件：
+1. 识别用户需求的类别（布局、表单、数据展示等）
+2. 匹配对应的场景描述
+3. 推荐最合适的组件
+4. 提供示例代码
+
+---
+
+## 📦 按需求场景分类
+
+### 🏗️ 需求：创建应用布局
+
+**场景描述：**
+- "我需要创建一个应用的整体布局"
+- "需要一个带侧边栏的页面"
+- "想要一个经典的顶部导航+侧边栏+内容的布局"
+- "需要响应式的多列布局"
+
+**关键问题：**
+```
+1. 需要侧边栏吗？
+   └─ 是 → SidebarLayout
+   └─ 否 → 继续问 2
+
+2. 需要顶部导航栏吗？
+   └─ 是 → HeaderLayout
+   └─ 否 → 继续问 3
+
+3. 需要完整的经典布局（头+侧边+内容+底）吗？
+   └─ 是 → ClassicLayout
+   └─ 否 → 继续问 4
+
+4. 需要多列还是多行？
+   └─ 多列 → ColumnsLayout
+   └─ 多行 → RowsLayout
+```
+
+**推荐组件：**
+```typescript
+// 侧边栏布局
+import SidebarLayout from '@ticatec/uniface-element/app-layout/SidebarLayout';
+
+// 顶部栏布局
+import HeaderLayout from '@ticatec/uniface-element/app-layout/HeaderLayout';
+
+// 经典布局
+import ClassicLayout from '@ticatec/uniface-element/app-layout/ClassicLayout';
+```
+
+---
+
+### 📝 需求：创建表单
+
+**场景描述：**
+- "我需要创建一个用户注册表单"
+- "需要一个输入框来收集用户信息"
+- "需要数字输入"
+- "需要下拉选择"
+- "需要日期选择"
+- "需要文件上传"
+
+**决策树：**
+```
+1. 输入什么类型的数据？
+
+   文本类型：
+   ├── 单行文本 → TextEditor
+   ├── 多行文本/备注 → MemoEditor
+   ├── 需要提示/自动完成 → PromptsTextEditor
+   └── 单元格内编辑 → InlineCellEditor
+
+   数字类型：
+   ├── 普通数字 → NumberEditor
+   ├── 带单位（如 $100）→ UnitNumberEditor
+   └── 数字范围（如价格区间）→ NumberRange
+
+   选择类型：
+   ├── 是/否开关 → Switch
+   ├── 勾选 → CheckBox
+   ├── 单选（多选一）→ RadioButton
+   ├── 下拉单选 → OptionsSelect
+   ├── 下拉多选 → OptionsMultiSelect
+   ├── 级联选择（省市区）→ CascadeOptionsSelect
+   ├── 可输入也可选择 → InputOptionsSelect
+   └── 查找选择 → LookupEditor
+
+   日期时间：
+   ├── 日期选择 → DatePicker
+   ├── 日期时间选择 → DateTimePicker
+   ├── 日期范围 → DateRange
+   └── 时间选择 → TimeEditor
+
+   文件：
+   ├── 普通文件上传 → AttachmentFiles
+   ├── 图片上传 → ImageFiles
+   └── 穿梭选择（左右移动）→ Transfer
+```
+
+**最佳实践：**
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  import Button from '@ticatec/uniface-element/Button';
+</script>
+
+<form>
+  <FormField label="用户名" required>
+    <TextEditor placeholder="请输入用户名" />
+  </FormField>
+
+  <FormField label="年龄">
+    <NumberEditor placeholder="请输入年龄" />
+  </FormField>
+
+  <FormField label="国家">
+    <OptionsSelect options={countries} />
+  </FormField>
+
+  <Button type="primary">提交</Button>
+</form>
+```
+
+---
+
+### 📊 需求：展示数据
+
+**场景描述：**
+- "我需要展示一个数据表格"
+- "需要分页展示数据"
+- "需要显示树形结构的数据"
+- "需要显示进度条"
+- "需要显示状态标签"
+
+**决策树：**
+```
+1. 数据展示形式？
+
+   表格数据：
+   ├── 复杂表格（需要分页、排序、选择）→ DataTable
+   └── 简单表格 → ConciseDataTable
+
+   列表数据：
+   ├── 平面列表 → ListBox
+   └── 树形结构 → TreeView
+
+   进度/状态：
+   ├── 进度百分比 → ProgressBar
+   ├── 步骤进度 → ProgressStepBar
+   ├── 向导导航 → Navigator
+   └── 状态标签 → Tag
+```
+
+**示例代码：**
+```svelte
+<script>
+  import DataTable from '@ticatec/uniface-element/DataTable';
+  import type { DataColumn } from '@ticatec/uniface-element/DataTable';
+
+  let columns: DataColumn[] = [
+    { field: 'name', title: '姓名', width: 150 },
+    { field: 'email', title: '邮箱', width: 200 },
+    { field: 'status', title: '状态', width: 120 }
+  ];
+
+  let data = [
+    { name: '张三', email: 'zhangsan@example.com', status: 'Active' },
+    { name: '李四', email: 'lisi@example.com', status: 'Inactive' }
+  ];
+</script>
+
+<DataTable {columns} list={data} />
+```
+
+---
+
+### 💬 需求：用户反馈和通知
+
+**场景描述：**
+- "需要弹出一个对话框确认操作"
+- "需要显示成功/失败消息"
+- "需要显示一个侧边面板"
+- "需要一个提示框"
+
+**决策树：**
+```
+1. 反馈类型？
+
+   弹窗类型：
+   ├── 完整自定义对话框 → Dialog
+   ├── 标准确认框（确定/取消）→ CommonDialog
+   └── 消息提示框 → MessageBox
+
+   侧边类型：
+   └── 从侧边滑出 → Drawer
+
+   轻量提示：
+   ├── 消息提示（自动消失）→ Toast
+   └── 悬浮提示 → PopupHint
+```
+
+**使用场景示例：**
+```svelte
+<!-- 确认删除对话框 -->
+<script>
+  import Dialog from '@ticatec/uniface-element/Dialog';
+  import Button from '@ticatec/uniface-element/Button';
+
+  let showDialog = false;
+
+  function handleDelete() {
+    showDialog = true;
+  }
+
+  function confirmDelete() {
+    console.log('已删除');
+    showDialog = false;
+  }
+</script>
+
+<Button onclick={handleDelete}>删除</Button>
+
+<Dialog bind:visible={showDialog} title="确认删除">
+  <p>确定要删除此项吗？</p>
+  <svelte:fragment slot="actions">
+    <Button onclick={() => showDialog = false}>取消</Button>
+    <Button type="primary" onclick={confirmDelete}>确定</Button>
+  </svelte:fragment>
+</Dialog>
+
+<!-- 成功消息提示 -->
+<script>
+  import Toast from '@ticatec/uniface-element/Toast';
+
+  function showSuccess() {
+    Toast.success('操作成功！');
+  }
+</script>
+```
+
+---
+
+### 🧭 需求：页面导航
+
+**场景描述：**
+- "需要显示面包屑导航"
+- "需要标签页来分组内容"
+- "需要创建向导流程"
+- "需要导航菜单"
+
+**决策树：**
+```
+1. 导航类型？
+
+   层级导航：
+   └── 面包屑 → Breadcrumbs
+
+   内容分组：
+   └── 标签页 → Tabs
+
+   流程导航：
+   └── 向导步骤 → Navigator
+
+   菜单导航：
+   ├── 顶部菜单 → NavigatorMenu
+   ├── 工具栏 → ActionBar
+   └── 右键菜单 → ContextMenu
+```
+
+---
+
+### 🎨 需求：按钮和操作
+
+**场景描述：**
+- "需要一个提交按钮"
+- "需要一个图标按钮"
+- "需要一个工具栏"
+
+**决策树：**
+```
+1. 按钮重要性？
+
+   主要操作：
+   └── type="primary"
+
+   次要操作：
+   └── type="secondary"
+
+   危险操作：
+   └── 自定义红色样式
+
+2. 按钮样式？
+
+   标准按钮：
+   └── Button
+
+   图标按钮：
+   └── IconButton
+
+   文本按钮：
+   └── TextButton
+```
+
+---
+
+### 🔍 需求：搜索和筛选
+
+**场景描述：**
+- "需要一个搜索框"
+- "需要多条件筛选"
+- "需要数字范围筛选"
+- "需要日期范围筛选"
+
+**推荐组件：**
+```
+搜索：
+└── SearchBox - 带搜索图标的输入框
+
+多条件筛选：
+└── CriteriaField - 组合多个筛选条件
+
+范围筛选：
+├── 数字范围 → NumberRange
+└── 日期范围 → DateRange
+```
+
+**示例：**
+```svelte
+<script>
+  import SearchBox from '@ticatec/uniface-element/SearchBox';
+  import CriteriaField from '@ticatec/uniface-element/CriteriaField';
+  import NumberRange from '@ticatec/uniface-element/NumberRange';
+  import DateRange from '@ticatec/uniface-element/DateRange';
+</script>
+
+<!-- 搜索框 -->
+<SearchBox placeholder="搜索..." />
+
+<!-- 多条件筛选 -->
+<CriteriaField>
+  <NumberRange label="价格区间" />
+  <DateRange label="发布日期" />
+</CriteriaField>
+```
+
+---
+
+## 🎯 常见场景速查
+
+### 场景 1：用户注册页面
+```
+需求：收集用户基本信息
+
+推荐组件：
+├── Page - 页面容器
+├── FormField - 表单字段包装（提供标签和错误提示）
+├── TextEditor - 用户名、邮箱
+├── PasswordEditor - 密码
+├── OptionsSelect - 国家/地区选择
+├── CheckBox - 同意条款
+└── Button - 提交按钮（type="primary"）
+
+完整示例代码：
+见 COMPONENT_GUIDE.md 场景 1
+```
+
+### 场景 2：数据管理后台
+```
+需求：展示和管理数据列表
+
+推荐组件：
+├── SidebarLayout - 应用布局（侧边栏+主内容）
+├── DataTable - 数据表格（支持分页、排序、选择）
+├── SearchBox - 搜索框
+├── CriteriaField - 筛选区域
+├── Button - 新增、删除、编辑按钮
+├── Pagination - 分页组件
+├── Dialog - 编辑对话框
+└── Toast - 操作反馈
+
+完整示例代码：
+见 COMPONENT_GUIDE.md 场景 2
+```
+
+### 场景 3：设置页面
+```
+需求：用户配置设置
+
+推荐组件：
+├── Page - 页面容器
+├── Tabs - 分组不同设置类别
+├── FormField - 表单字段包装
+├── TextEditor - 文本类设置
+├── NumberEditor - 数字类设置
+├── Switch - 开关类设置
+├── OptionsSelect - 选项类设置
+└── Button - 保存按钮
+
+完整示例代码：
+见 COMPONENT_GUIDE.md 场景 3
+```
+
+### 场景 4：多步骤向导
+```
+需求：引导用户完成多步骤流程
+
+推荐组件：
+├── Page - 页面容器
+├── Navigator - 步骤导航器（显示进度）
+├── FormField - 表单字段
+├── 各类表单组件 - 根据每步需求
+└── Button - 上一步/下一步按钮
+
+完整示例代码：
+见 COMPONENT_GUIDE.md 场景 4
+```
+
+### 场景 5：文件管理系统
+```
+需求：上传和管理文件
+
+推荐组件：
+├── DataTable - 文件列表
+├── AttachmentFiles - 文件上传（带进度）
+├── Button - 操作按钮（上传、删除、下载）
+├── SearchBox - 文件搜索
+├── CriteriaField - 文件类型筛选
+├── Dialog - 文件详情/预览
+└── Tag - 文件类型标签
+```
+
+---
+
+## 💡 AI 助手决策逻辑
+
+当用户描述需求时，按以下逻辑思考：
+
+### 第一步：识别需求类别
+```
+需求关键词识别：
+
+布局相关：
+├─ "布局"、"页面结构"、"侧边栏"、"顶部栏"
+└─ → 转到 [布局组件决策](#需求创建应用布局)
+
+表单相关：
+├─ "输入"、"表单"、"填写"、"收集信息"
+├─ "文本"、"数字"、"日期"、"选择"、"上传"
+└─ → 转到 [表单组件决策](#需求创建表单)
+
+数据展示：
+├─ "表格"、"列表"、"数据"、"展示"
+├─ "分页"、"进度"、"状态"
+└─ → 转到 [数据展示决策](#需求展示数据)
+
+反馈通知：
+├─ "对话框"、"弹窗"、"提示"、"消息"
+├─ "确认"、"通知"
+└─ → 转到 [反馈组件决策](#需求用户反馈和通知)
+
+导航相关：
+├─ "导航"、"菜单"、"面包屑"、"标签页"
+├─ "步骤"、"向导"
+└─ → 转到 [导航组件决策](#需求页面导航)
+```
+
+### 第二步：细化需求
+```
+对于表单需求，问自己：
+1. 输入什么类型的数据？
+   - 文本 → TextEditor / MemoEditor
+   - 数字 → NumberEditor
+   - 日期 → DatePicker
+   - 选择 → OptionsSelect / CheckBox / RadioButton
+   - 文件 → AttachmentFiles
+
+2. 需要验证吗？
+   - 是 → 使用 FormField 的 error 属性
+
+3. 需要标签和提示吗？
+   - 是 → 使用 FormField 包装
+```
+
+### 第三步：推荐并生成代码
+```
+1. 列出需要的组件
+2. 提供完整的导入语句
+3. 提供基础示例代码
+4. 说明重要属性
+5. 提供最佳实践建议
+```
+
+---
+
+## 🔧 高级场景组合
+
+### 复杂表单 + 数据表格
+```
+场景：数据管理系统的编辑页面
+
+组件组合：
+├── Dialog - 弹窗编辑
+├── FormField - 表单字段
+├── TextEditor - 文本输入
+├── OptionsSelect - 下拉选择
+├── DataTable - 主数据表格
+├── Button - 操作按钮
+└── Toast - 操作反馈
+
+代码结构：
+<Split>
+└── 创建 DataTable 展示列表
+└── 点击"编辑"按钮打开 Dialog
+└── Dialog 内包含 FormField + 各种输入组件
+└── 保存后刷新 DataTable
+</Split>
+```
+
+### 文件上传 + 预览
+```
+场景：图片上传和预览
+
+组件组合：
+├── AttachmentFiles / ImageFiles - 文件上传
+├── DataTable - 已上传文件列表
+├── Dialog - 图片预览
+└── Tag - 文件类型标签
+
+代码结构：
+<Split>
+└── 上传区：AttachmentFiles 组件
+└── 文件列表：DataTable 显示已上传文件
+└── 点击文件：Dialog 显示大图预览
+</Split>
+```
+
+---
+
+## 📚 相关文档
+
+- [组件使用指南](./COMPONENT_GUIDE.md)
+- [组件 API 文档](./src/lib)
+- [示例代码](./src/routes/demo)
+
+---
+
+## 🎓 使用技巧
+
+1. **从需求到组件**：使用本文档的决策树快速定位组件
+2. **查看示例**：每个组件的 README 都有丰富的示例
+3. **组合使用**：参考"高级场景组合"了解组件搭配
+4. **最佳实践**：遵循组件使用指南的最佳实践部分