@jzt-packages/components 1.0.0

package/src/JztFormGrid/README.md

@@ -0,0 +1,520 @@
+# JztFormGrid 表单组件
+
+> 一个基于 **配置驱动（Config-Driven）** 的表单组件，基于 Element Plus `el-form` 封装，通过 `queryItems` 配置数组即可渲染出完整的表单，无需手写大量 `el-form-item` 模板。
+
+适用场景：新增 / 编辑 / 详情弹窗、查询条件区、复杂业务表单（如产品信息维护、订单录入等）。
+
+---
+
+## 目录
+
+- [一、核心特性](#一核心特性)
+- [二、快速上手](#二快速上手)
+- [三、组件文件结构](#三组件文件结构)
+- [四、组件 Props（JztFormGrid）](#四组件-propsjztformgrid)
+- [五、queryItems 表单项配置（核心）](#五queryitems-表单项配置核心)
+- [六、el 支持的组件类型](#六el-支持的组件类型)
+- [七、enum 枚举字典（下拉数据）](#七enum-枚举字典下拉数据)
+- [八、cascader 级联选择](#八cascader-级联选择)
+- [九、动态显示 / 隐藏 / 禁用](#九动态显示--隐藏--禁用)
+- [十、表单分组](#十表单分组)
+- [十一、操作按钮](#十一操作按钮)
+- [十二、查看模式 vs 详情模式](#十二查看模式-vs-详情模式)
+- [十三、暴露的方法（ref 调用）](#十三暴露的方法ref-调用)
+- [十四、插槽](#十四插槽)
+- [十五、自定义渲染（tsx）](#十五自定义渲染tsx)
+- [十六、时间 / 数字范围字段](#十六时间--数字范围字段)
+- [十七、常见踩坑点](#十七常见踩坑点)
+
+---
+
+## 一、核心特性
+
+1. **配置驱动**：一个 `queryItems` 数组描述整个表单，类型由 TypeScript 完整推导。
+2. **支持多种控件**：`el-input`、`el-select`、`el-date-picker`、`el-cascader`、`el-tree-select`、`el-switch` 等 Element Plus 组件，以及业务自定义组件（上传、行政区划、数字范围等）。
+3. **内置枚举字典机制**：`enum` 支持静态数组 / 异步接口请求，自动填充下拉。
+4. **级联选择**：`cascader` 配置上级，自动联动加载下级数据，清空时递归清除。
+5. **三种模式切换**：编辑模式（默认）/ 查看模式（`isShow`）/ 详情模式（`isDetail`），同一份配置即可复用。
+6. **分组 & 折叠**：通过 `groupTitle + children` 实现分组卡片，支持折叠展开。
+7. **自定义渲染（tsx）**：`render`、`labelRender` 等支持灵活的自定义内容。
+
+---
+
+## 二、快速上手
+
+```vue
+<template>
+  <JztFormGrid ref="formRef" :query-items="columns" :rule-form="form" />
+  <el-button type="primary" @click="onSubmit">提交</el-button>
+</template>
+
+<script setup lang="ts">
+import { JztFormGrid } from '@jzt-spd/components'
+import type { JztFormInstance, FormItemsProps } from '@jzt-spd/components/JztFormGrid'
+
+const formRef = ref<JztFormInstance>()
+const form = reactive({ name: '', status: 1, remark: '' })
+
+const columns = ref<FormItemsProps[]>([
+  {
+    label: '姓名',
+    prop: 'name',
+    el: 'el-input',
+    span: 12,
+    rules: [{ required: true, message: '请输入姓名', trigger: 'blur' }]
+  },
+  {
+    label: '状态',
+    prop: 'status',
+    el: 'el-select',
+    span: 12,
+    enum: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 }
+    ]
+  },
+  {
+    label: '备注',
+    prop: 'remark',
+    el: 'el-input',
+    span: 24,
+    props: { type: 'textarea', rows: 3 }
+  }
+])
+
+const onSubmit = () => {
+  formRef.value?.onConfirm((valid, formData) => {
+    if (valid) {
+      console.log('校验通过，提交数据：', formData)
+    }
+  })
+}
+</script>
+```
+
+> 💡 **导入约定**
+> - 组件本身：`import { JztFormGrid } from '@jzt-spd/components'`
+> - 类型：`import type { JztFormInstance, FormItemsProps } from '@jzt-spd/components/JztFormGrid'`
+
+---
+
+## 三、组件文件结构
+
+```
+JztFormGrid/
+├── index.vue                 # 主组件：表单容器、分组渲染、数据格式化、ref 方法暴露
+├── index.scss                # 公共样式
+├── interface/index.ts        # FormItemsProps 等类型定义（最重要）
+└── components/
+    ├── formItem.vue          # 单个表单项容器：决定渲染编辑态/查看态/详情态
+    ├── formItemValue.vue     # 编辑态：真正渲染 el-* 控件、enum 处理、级联事件
+    └── showDetailForm.vue    # 详情态：左右布局的 label:value 展示
+```
+
+**渲染链路**：`index.vue`（遍历 queryItems）→ `formItem.vue`（判断模式）→ `formItemValue.vue`（编辑）/ `showDetailForm.vue`（详情）。
+
+---
+
+## 四、组件 Props（JztFormGrid）
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `queryItems` | `FormItemsProps[]` | `[]` | **必填**，表单配置项数组 |
+| `ruleForm` | `object` | `{}` | 表单数据对象（双向绑定，直接修改即生效） |
+| `isShow` | `boolean` | `false` | 查看模式：表单项以只读文本展示 |
+| `disabled` | `boolean` | `false` | 整个表单禁用 |
+| `isDetail` | `boolean` | `false` | 详情模式：使用 `showDetailForm` 的 `label : value` 左右布局展示 |
+| `labelWidth` | `number \| string` | `'auto'` | 整体 label 宽度 |
+| `border` | `boolean` | `false` | 显示网格边框样式 |
+| `isCard` | `boolean` | `false` | 分组卡片样式（带边框 + 浅灰背景头部） |
+| `showCollapsed` | `boolean` | `true` | 分组是否显示折叠按钮 |
+| `infoEmptyText` | `string` | `'-'` | 查看 / 详情模式下空值的占位符 |
+| `showOverflowTooltip` | `boolean` | - | 详情 value 是否超长显示 Tooltip |
+| `formProps` | `object` | - | 透传给 `el-form` 的属性 |
+| `groupProps` | `object` | `{}` | 透传给分组标题组件 `JztLabelTitle` 的属性 |
+
+> 三种"只读"模式的区别见 [第十二章](#十二查看模式-vs-详情模式)。
+
+---
+
+## 五、queryItems 表单项配置（核心）
+
+每个数组元素是一个 `FormItemsProps` 对象。**最常用的字段**：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `label` | `string` | 表单项标签 |
+| `prop` | `string` | 绑定到 `ruleForm` 的字段名（必填） |
+| `el` | `ElType` | 渲染的控件类型，见 [第六章](#六el-支持的组件类型) |
+| `span` | `number` | 栅格宽度，默认 `12`（24 栅格制，12 = 一行两列） |
+| `props` | `object` | 透传给 el 控件的属性（如 `placeholder`、`disabled`、`type` 等） |
+| `events` | `object` | 透传给 el 控件的事件（key 为事件名，如 `change`、`focus`） |
+| `rules` | `array` | Element Plus 校验规则 |
+| `enum` | 见 [第七章](#七enum-枚举字典下拉数据) | 下拉 / 选项数据 |
+| `fieldNames` | `{ label, value, children }` | 自定义选项的字段映射（接口字段非 label/value 时用） |
+| `change` | `(scope) => void` | 控件 change 回调，`scope = { value, optionsItem }` |
+| `hideFun` | `() => boolean` | 返回 `true` 则隐藏该项（动态） |
+| `disabledFn` | `(form) => boolean` | 返回 `true` 则禁用该项（动态） |
+| `slotName` | `string` | 自定义插槽名，用 `<template #slotName>` 渲染内容 |
+| `tooltip` | `string` | label 后的感叹号提示 |
+| `className` | `string` | 给 `el-form-item` 加 class |
+| `formItemProps` | `object` | 透传给 `el-form-item` 的属性 |
+| `labelWidth` | `string \| number` | 单项 label 宽度（覆盖整体设置） |
+
+---
+
+## 六、el 支持的组件类型
+
+```ts
+type ElType =
+  | 'el-input' | 'el-input-number'
+  | 'el-select' | 'el-select-v2'
+  | 'el-tree-select' | 'el-cascader'
+  | 'el-date-picker' | 'el-time-picker' | 'el-time-select'
+  | 'el-switch' | 'el-slider'
+  | 'el-radio-group' | 'el-checkbox-group'
+  // 业务自定义组件
+  | 'JztUploadImg' | 'JztUploadMultipleImgs'        // 单图 / 多图上传
+  | 'JztUploadSingleFile' | 'JztUploadMultipleFiles' // 单文件 / 多文件上传
+  | 'JztDictionary'                                   // 字典组件
+  | 'JztTable'                                        // 表格（常用于明细）
+  | 'JztRegionSelect'                                 // 行政区划选择
+```
+
+> 当 `el` 不传或为非 `el-*` 的自定义组件时，组件会按自定义组件逻辑渲染。
+> 常用三件套：`el-input`（输入）、`el-select`（下拉）、`el-date-picker`（日期）。
+
+---
+
+## 七、enum 枚举字典（下拉数据）
+
+`enum` 有三种写法，**优先级**：`enum` > `options` > 通过 `provide('fromEnumMap')` 注入。
+
+### 1. 静态数组
+
+```ts
+{
+  label: '状态', prop: 'status', el: 'el-select',
+  enum: [
+    { label: '启用', value: 1 },
+    { label: '禁用', value: 0 }
+  ]
+}
+```
+
+### 2. 异步接口（函数）
+
+```ts
+{
+  label: '生产厂家', prop: 'manufactureId', el: 'el-select',
+  enum: async () => await getManufacturerList({ enterpriseType: 2 }),
+  fieldNames: { label: 'value', value: 'key' } // 接口字段不是 label/value 时必配
+}
+```
+
+### 3. 级联接口（接收上级值）
+
+```ts
+{
+  label: '供应商', prop: 'supplierId', el: 'el-select-v2',
+  enum: (val) => getSupplierDDL(val), // val = 上级 prop 的值
+  fieldNames: { label: 'name', value: 'id' }
+}
+```
+
+**配套字段：**
+
+| 字段 | 说明 |
+| --- | --- |
+| `fieldNames` | `{ label, value, children }`，把接口返回字段映射成标准 label/value |
+| `isSetFirstValue` | 接口返回后，是否自动选中第一项 |
+| `isAwait` | 级联场景：是否等待上级有值后才请求（详情回显常用） |
+| `enumKey` | 当多个字段共用同一份字典时，指定读取 enumMap 的 key |
+
+> ⚠️ 异步 `enum` 函数返回值需为 `{ result: [] }` 或 `{ data: [] }` 结构（与后端约定）。
+
+---
+
+## 八、cascader 级联选择
+
+实现"省 → 市 → 区"或"产品大类 → 小类"的联动。
+
+```ts
+{
+  label: '产品大类', prop: 'productClassId', el: 'el-select',
+  cascader: ['productTypeId'],           // 声明：我的下级是 productTypeId
+  enum: async () => await getProductClassListAsync(),
+  fieldNames: { value: 'productClassId', label: 'productClassName' }
+},
+{
+  label: '产品小类', prop: 'productTypeId', el: 'el-select',
+  isAwait: true,                         // 等待上级选中后再请求
+  enum: async (parentId) => {
+    // parentId = 上级 productClassId 的值
+    return await getGoodsClassToProduceClassTypeList({ ClassCode: ... })
+  }
+}
+```
+
+**联动机制：**
+- 上级 `change` 时，自动调用下级 `enum(上级值)` 刷新下拉，并清空下级已选值。
+- 清空上级时，会**递归清空**所有下级的值与下拉数据（适用于三级及以上）。
+
+---
+
+## 九、动态显示 / 隐藏 / 禁用
+
+```ts
+// 1. 动态隐藏：返回 true 则不渲染该项
+{
+  label: '产品外码', prop: 'productOutCode', el: 'el-input',
+  hideFun: () => mode.value === 'add'
+}
+
+// 2. 动态禁用：返回 true 则禁用
+{
+  label: '名称', prop: 'name', el: 'el-input',
+  disabledFn: (form) => form.status === 0
+}
+
+// 3. 通过 props.disabled 静态禁用单个控件
+{
+  label: '型号', prop: 'model', el: 'el-input',
+  props: { disabled: true }
+}
+```
+
+> `hideFun` 直接控制 `v-if`，隐藏的字段不会出现在 DOM 中。
+
+---
+
+## 十、表单分组
+
+通过 `groupTitle` + `children` 将表单拆成多个卡片分组：
+
+```ts
+const queryItems = reactive<FormItemsProps[]>([
+  {
+    groupTitle: '基本信息',
+    prop: 'group1',           // 分组需有唯一 prop
+    children: [
+      { label: '姓名', prop: 'name', el: 'el-input', span: 12 },
+      { label: '年龄', prop: 'age', el: 'el-input-number', span: 12 }
+    ]
+  },
+  {
+    groupTitle: '附加信息',
+    prop: 'group2',
+    children: [ /* ... */ ]
+  }
+])
+```
+
+配合 Props：
+- `isCard` → 卡片样式（带边框 + 灰色头部）
+- `showCollapsed` → 头部点击可折叠 / 展开（默认开启）
+- 不需要分组时，直接平铺配置即可（无需 `groupTitle`/`children`）。
+
+---
+
+## 十一、操作按钮
+
+在 `queryItems` 末尾加一个 `prop: 'submitBtn'` 的特殊项，可渲染内置的操作按钮：
+
+```ts
+{
+  prop: 'submitBtn',
+  span: 24,
+  btnLList: [
+    {
+      id: 'confirm',            // 内置：触发校验 + 获取格式化数据
+      text: '提交',
+      type: 'primary',
+      fun: (valid, form) => {   // valid: 校验结果; form: 格式化后的数据
+        if (valid) saveApi(form)
+      }
+    },
+    {
+      id: 'reset',              // 内置：重置表单
+      text: '重置',
+      fun: () => console.log('已重置')
+    },
+    {
+      id: 'custom',             // 自定义 id：直接拿到格式化数据
+      text: '暂存',
+      fun: (form) => draftApi(form)
+    }
+  ]
+}
+```
+
+> 按钮也可以放在组件外部，通过 `ref` 调用 `onConfirm`（见 [第十三章](#十三暴露的方法ref-调用)），更灵活。
+
+---
+
+## 十二、查看模式 vs 详情模式
+
+| 模式 | 触发方式 | 表现 | 适用场景 |
+| --- | --- | --- | --- |
+| **编辑（默认）** | - | 正常可交互控件 | 新增 / 编辑 |
+| **查看模式** | `is-show="true"` | 控件变为只读文本，下拉值自动反显为 label | 弹窗内只读查看 |
+| **详情模式** | `is-detail="true"` | `label : value` 左右布局（灰 label + 黑 value），更紧凑 | 详情页、打印 |
+| **整体禁用** | `disabled="true"` | 控件保留但变灰不可操作 | 审批中等场景 |
+
+详情模式额外配置：
+
+```ts
+{
+  label: '描述', prop: 'remark', el: 'el-input',
+  detailProps: {
+    showProp: 'showRemark',     // 详情展示用别的字段（编辑是id，展示是name）
+    showOverflowTooltip: true   // 超长 Tooltip
+  }
+}
+```
+
+> 单项也可独立设置 `isDetail: true`，与整体 `isDetail` 取 `item.isDetail ?? isDetail`。
+
+---
+
+## 十三、暴露的方法（ref 调用）
+
+通过 `ref` 可调用以下方法（`defineExpose`）：
+
+| 方法 | 签名 | 说明 |
+| --- | --- | --- |
+| `onConfirm` | `(callback?) => Promise` | **常用**。先校验，再回调 `callback(valid, formatForm)` |
+| `onReset` | `(callback?) => void` | 重置表单字段 + 清除校验 |
+| `validateForm` | `() => Promise<boolean>` | 校验整个表单，返回是否通过 |
+| `validateFields` | `(fields) => Promise<boolean>` | 校验指定字段（string 或 string[]） |
+| `clearValidateForm` | `() => void` | 清除校验结果 |
+| `getFormatForm` | `(form?) => object` | 拿到格式化后的数据（处理范围字段、空值，见下） |
+| `formRef` | `FormInstance` | Element Plus `el-form` 实例，可调用任意原生方法 |
+
+**外部提交按钮的标准写法：**
+
+```vue
+<template>
+  <JztFormGrid ref="formRef" :query-items="columns" :rule-form="form" />
+  <el-button type="primary" @click="onSubmit">提交</el-button>
+  <el-button @click="onReset">重置</el-button>
+</template>
+
+<script setup lang="ts">
+const formRef = ref<JztFormInstance>()
+
+const onSubmit = () => {
+  formRef.value?.onConfirm((valid, formData) => {
+    if (valid) saveApi(formData)  // formData 已自动处理范围字段、空值
+  })
+}
+const onReset = () => {
+  formRef.value?.onReset(() => console.log('重置成功'))
+}
+</script>
+```
+
+---
+
+## 十四、插槽
+
+| 插槽名 | 说明 |
+| --- | --- |
+| `footer` | 表单底部内容 |
+| `header_right` | 分组标题右侧区域（仅 `showCollapsed=false` 时生效） |
+| `自定义 slotName` | 在表单项配置 `slotName` 后，用 `<template #你的slotName>` 完全自定义该项内容 |
+
+```vue
+<JztFormGrid :query-items="[{ label: '年级', prop: 'grade', el: 'el-select', slotName: 'mySlot' }]" :rule-form="form">
+  <template #mySlot>
+    <el-radio-group v-model="form.grade">...</el-radio-group>
+  </template>
+</JztFormGrid>
+```
+
+---
+
+## 十五、自定义渲染（tsx）
+
+需要 `<script lang="tsx" setup>`。所有 render 函数都接收上下文（如 `form`），返回 VNode。
+
+| 字段 | 作用位置 |
+| --- | --- |
+| `labelRender` | 自定义 label 内容 |
+| `render` | 自定义表单项内容（编辑 + 查看通用） |
+| `showRender` | 详情 / 查看态内容（优先级高于 `render`） |
+| `outerRender` | 在 form-item **同层级外部**渲染 |
+| `rightRender` | 控件右侧追加内容 |
+| `valueLeftRender` / `valueRightRender` | 详情模式下 value 左右追加内容 |
+
+```tsx
+{
+  label: '年龄', prop: 'age', el: 'el-input',
+  labelRender: () => <span style="color: red">年龄：</span>,
+  render: ({ form }) => <span>男生（{form.age}）</span>
+}
+```
+
+---
+
+## 十六、时间 / 数字范围字段
+
+将一个**数组型控件**的值，拆 / 合到两个独立字段提交。
+
+```ts
+// 时间范围：UI 是一个 datetimerange，提交时拆成 startTime / endTime
+{
+  label: '事件范围', prop: 'timeList', el: 'el-date-picker',
+  startField: 'startTime',
+  endField: 'endTime',
+  props: { type: 'datetimerange', valueFormat: 'YYYY-MM-DD HH:mm:ss' }
+}
+```
+
+**机制（在 `index.vue` 的 `queryFrom` / `getFormatForm` 中处理）：**
+- **回显**：若 `startTime`/`endTime` 有值，自动合并为 `[startTime, endTime]` 赋给 `prop`。
+- **提交**：`getFormatForm` 把数组拆回 `startTime`/`endTime`，并删除中间字段 `timeList`。
+
+数字范围同理（`el: 'JztNumericalRange'` + `startField`/`endField`）。
+
+---
+
+## 十七、常见踩坑点
+
+1. **`ruleForm` 必须是响应式对象**：用 `reactive({})` 或 `ref({})`，否则值无法更新。直接修改 `ruleForm.xxx = yyy` 即可双向绑定，无需 `emit`。
+
+2. **`prop` 必须唯一**：作为 `el-form-item` 的 key 与校验字段，重复会导致校验错乱。分组项也要有唯一 `prop`。
+
+3. **接口字段不是 label/value 时务必配 `fieldNames`**：否则下拉显示空白或 value 错误。
+
+4. **级联下级要加 `isAwait`（详情回显场景）**：否则下级在上级还没值时就请求，拿不到数据。
+
+5. **查看 / 详情模式下，`ruleForm` 也要有对应字段的值**，否则显示空占位符（`infoEmptyText`，默认 `-`）。
+
+6. **范围字段提交后被删除**：`timeList` 这类中间字段在 `getFormatForm` 后会被删除，只保留 `startField`/`endField`，接口以此为准。
+
+7. **空值默认值 `GUIDNoneValue`**：后端某些字段（如供应商、机构）要求不选时传全零 GUID `00000000-0000-0000-0000-000000000000`。配置：
+   ```ts
+   { prop: 'agencyId', isSetEmptyData: true, emptyNullValue: userStore.userAgencyId }
+   ```
+   - 初始化（页面）：取 `emptyNullValue`
+   - 提交（结果）：空值时填 `GUIDNoneValue`
+
+8. **`queryItems` 变更会重新深拷贝**：组件内部对 `queryItems` 做了 `cloneDeep`（避免折叠状态互相影响），所以**不要在配置里放函数闭包外还能被外部修改的引用**，且动态改配置请整体替换数组。
+
+9. **`submitBtn` 与外部按钮二选一**：内部按钮交互固定，需要自定义交互（如 loading、二次确认）时，建议用外部按钮 + `onConfirm`。
+
+---
+
+## 附：完整真实示例参考
+
+仓库内已有丰富示例，新同学可直接参考：
+
+| 场景 | 参考文件 |
+| --- | --- |
+| **官方示例（含全配置演示）** | `spd-main-layout/src/views/assembly/form/useFormGrid/index.vue` |
+| 复杂编辑表单（产品主信息） | `spd-basic-system/src/components/ProductForm/MainInfo.vue` |
+| 上传文件表单 | `spd-main-layout/src/views/assembly/uploadFile/components/formFile.vue` |
+| 弹窗新增 / 编辑 | `spd-basic-system/src/views/order/equipmentApplicationForm/components/addDialog.vue` |
+
+> 建议先把 `useFormGrid/index.vue` 这个官方 Demo 跑起来，对照本文档逐项调试，能最快上手。