签入版本

2026-10-25 17:24:27 +08:00
parent 48911cc08f
commit fdbeae092a
1010 changed files with 30682 additions and 95274 deletions
@@ -1,114 +1,61 @@
 # 9.10 数据录入组件

 :::tip 概述
-本节介绍前端项目中常用的数据录入组件，包括表单（BasicForm）、弹窗表单和上传组件的使用方法。
+表单录入类公共组件：Select/BasicSelect（异步数据源下拉）、TableSelect（表格选择器）、Upload（上传）、Editor（富文本）、Cropper（裁剪）、ChinaArea/Region（行政区划）、Password、numberInput、priceInput、importFile（导入）。
 :::

-## Form 表单组件
+## 组件清单

-```vue
-<template>
-  <BasicForm @register="registerForm" />
-</template>
+| 组件 | 职责 |
+|---|---|
+| Select（components/Select） | 下拉封装：支持 `options` 直配与 `request` 异步取数（可 cache/cacheKey 缓存） |
+| TableSelect | 表格选择器（选人/选部门等弹出表格单/多选） |
+| Upload | 文件/图片上传（对接两段式契约） |
+| Editor | 富文本（TinyMCE / vue-quill 双引擎） |
+| Cropper | 图片裁剪（配合 Upload 完成头像类流程） |
+| ChinaArea / Region | 省市区级联（对接 city 模块级联数据） |
+| Password | 密码输入 |
+| numberInput / priceInput | 数字/金额输入（精度与范围控制） |
+| importFile | 导入文件交互（example 页以异步组件方式引用） |

-<script setup>
-import { BasicForm, useForm } from '@/components/Form';
+## Select 的两种数据来源（components/Select/src/props.ts）

-const [registerForm] = useForm({
-  schemas: [
-    {
-      field: 'name',
-      label: '名称',
-      component: 'Input',
-      required: true,
-    },
-    {
-      field: 'status',
-      label: '状态',
-      component: 'Select',
-      componentProps: {
-        options: [
-          { label: '启用', value: 1 },
-          { label: '禁用', value: 0 },
-        ],
-      },
-    },
-  ],
-});
-</script>
+```typescript
+// ① options 直配 —— example 查询表单的实际用法（querySchemas.ts 节选）
+{
+  field: 'status',
+  component: 'Select',
+  label: '案例状态',
+  componentProps: {
+    placeholder: '请输入案例状态',
+    clearable: true,
+    options: [
+      { label: '在用', value: 1 },
+      { label: '停用', value: 2 },
+    ],
+  },
+}
+
+// ② request 异步取数 —— 组件内置 request 函数 prop（Promise<Option[]>），支持 cache/cacheKey
 ```

-## Modal 弹窗组件
+字典类选项经 request 函数调 `/api/dict/item/getDictItemList/{code}` 获取（与后端 SerializeMaps 同编码），不硬编码业务枚举；example 的查询配置为演示简化直接内联了 options。

-```vue
-<template>
-  <BasicModal @register="registerModal" @ok="handleSubmit" />
-</template>
+## 上传与两段式契约

-<script setup>
-import { BasicModal, useModal } from '@/components/Modal';
+选择文件 → 调上传接口拿 temp 结果（fileUrl/filePath）→ 表单字段持有 → 保存记录时后端转正。前端不关心物理路径（见 [7.5 前端文件组件](/zh/tools/file-components.html)）。

-const [registerModal, { openModal, closeModal }] = useModal();
+## 行政区划

-// 打开弹窗
-const handleAdd = () => {
-  openModal(true, { isUpdate: false });
-};
+ChinaArea/Region 消费 city 模块级联接口，三级选择后取编码组合——地址类字段配套（gin_user 的 province_code/city_code/district_code 即此形态）。

-// 提交
-const handleSubmit = async () => {
-  const values = await getFormValues();
-  await exampleAdd(values);
-  closeModal();
-};
-</script>
-```
+## 使用规约

-## Upload 上传组件
+- 业务页面不裸写 el-upload/手写上传逻辑，一律公共组件
+- 组件 props 与后端字段语义对齐（modelValue 映射 dto json 名）
+- 页面私有的复合控件放 views 下 components/，不进全局

-```vue
-<template>
-  <BasicUpload v-model="formData.avatar" :action="uploadUrl" />
-</template>
+## 相关

-<script setup>
-import { BasicUpload } from '@/components/Upload';
-const uploadUrl = '/api/upload/uploadFile';
-</script>
-```
-
-## Editor 富文本编辑器
-
-```vue
-<template>
-  <Editor v-model="formData.content" />
-</template>
-
-<script setup>
-import Editor from '@/components/Editor/index.vue';
-</script>
-```
-
-## Password 密码强度组件
-
-```vue
-<template>
-  <Password v-model="formData.password" />
-</template>
-
-<script setup>
-import { Password } from '@/components/Password';
-</script>
-```
-
-## ChinaArea 行政区划组件
-
-```vue
-<template>
-  <ChinaArea v-model="formData.city" />
-</template>
-
-<script setup>
-import ChinaArea from '@/components/ChinaArea/index.vue';
-</script>
-```
+- [5.11 字典模块](/zh/core/dict.html)
+- [9.9 表格与页面组件](/zh/frontend/table-components.html)