@zy-frontend/form-core 2.0.6

package/README.md

@@ -0,0 +1,422 @@
+# 配置化表单
+
+## 特点
+
+- 👍简洁的配置规则
+- 📦与UI库解耦，兼容多端，可自定义样式
+- ⚙️支持主动/被动联动，可实现复杂的字段/表单间的联动关系
+- ⚔️支持单表单、多表单两种模式
+- 🛡️支持分级字段校验
+- ☁️支持远程加载选项列表
+
+## 使用
+
+### 安装
+
+```sh
+npm i -S @zy/form-core
+```
+
+### 使用示例
+
+单表单场景：
+```html
+<script setup lang="ts">
+  import { ZYForm } from '@zy/form-core'
+  import formConfig from './form-config.json'
+  import { ElForm, ElFormItem, ElInput } from 'element-plus'
+
+  // 表单数据
+  const formData = ref({})
+  // 表单字段组件
+  const components = {
+    form: ElForm,
+    formItem: ElFormItem,
+    input: ElInput,
+  }
+  // 请求方法
+  const requestFn: RequestFunction = async (
+    keyPath,
+    value,
+    url,
+    extraParams,
+    componentParams = {},
+  ) => {
+    const res: Option[] = await getSelectOptions(url, extraParams, componentParams.query)
+    return res
+  }
+</script>
+
+<template>
+  <ZYForm
+    ref="formRef"
+    v-model="formData"
+    :config="formConfig"
+    :components="components"
+    :requestFn="requestFn"
+  />
+</template>
+```
+
+多表单场景：
+```html
+<script setup lang="ts">
+  import { ZYFormGroup } from '@zy/form-core'
+  import formConfig from './form-config.json'
+  import { ElForm, ElFormItem, ElInput } from 'element-plus'
+
+  // 表单数据
+  const formData = ref({})
+  // 表单字段组件
+  const components = {
+    form: ElForm,
+    formItem: ElFormItem,
+    input: ElInput,
+  }
+  // 请求方法
+  const requestFn: RequestFunction = async (
+    keyPath,
+    value,
+    url,
+    extraParams,
+    componentParams = {},
+  ) => {
+    const res: Option[] = await getSelectOptions(url, extraParams, componentParams.query)
+    return res
+  }
+</script>
+
+<template>
+  <ZYFormGroup
+    ref="formRef"
+    v-model="formData"
+    :config="formConfig"
+    :components="components"
+    :requestFn="requestFn"
+  />
+</template>
+```
+
+### API
+
+#### Form Attributes
+
+| 属性名            | 说明                                                                        | 类型            | 是否必填 | 默认值 |
+| ----------------- | --------------------------------------------------------------------------- | --------------- | -------- | ------ |
+| v-model           | 表单数据                                                                    | object          | 是       |        |
+| config            | 表单配置                                                                    | Form[]          | 是       |        |
+| formKey           | 表单唯一key                                                                 | string          | 是       |        |
+| components        | 表单字段组件集合                                                            | UIComponents    | 是       |        |
+| requestFn         | 请求方法，使用场景包括远程选项获取、文件上传等                                 | RequestFunction | 否       |        |
+| scenario          | 场景：用带指定前缀的属性覆盖原属性，如scenario为pc时，会用pc-props覆盖props     | string          | 否       |        |
+| requiredFieldOnly | 是否只显示必填字段                                                           | boolean         | 否       | false  |
+| disabled          | 禁用                                                                        | boolean         | 否       | false  |
+| readonly          | 只读                                                                        | boolean         | 否       | false  |
+
+#### Form Methods
+
+| 方法名         | 说明                   | 类型                                           |
+| -------------- | ---------------------- | ---------------------------------------------- |
+| initFormData   | 更新表单数据           | (newData?: Record<string, any>) => void        |
+| resetFormValue | 重置表单数据           | () => void                                     |
+| validate       | 表单校验，支持分级校验  | (maxLevel: number = Infinity, fields: string[] = []) => Promise<void> |
+| clearValidate  | 清空表单校验           | () => void                                     |
+| getFormData    | 获取表单数据           | () => Record<string, any>                      |
+
+#### Form Events
+
+| 事件名     | 说明                       | 回调参数                                             |
+| ---------- | -------------------------- | ---------------------------------------------------- |
+| change     | 当表单字段值发生改变时触发 | (keyPath: string, fieldValue: any)                    |
+| blur       | 当表单字段失去焦点时触发   | (e: FocusEvent, keyPath: string, fieldValue: any)     |
+| keyupEnter | 当enter键按下时触发        | (e: KeyboardEvent, keyPath: string, fieldValue: any) |
+| mounted    | 表单加载后触发             |                                                      |
+
+#### FormGroup Attributes
+
+| 属性名            | 说明                                                                        | 类型            | 是否必填 | 默认值 |
+| ----------------- | --------------------------------------------------------------------------- | --------------- | -------- | ------ |
+| v-model           | 表单数据                                                                    | object          | 是       |        |
+| config            | 表单配置                                                                    | Form[]          | 是       |        |
+| components        | 表单字段组件集合                                                            | UIComponents    | 是       |        |
+| requestFn         | 请求方法，使用场景包括远程选项获取、文件上传等                                 | RequestFunction | 否       |        |
+| scenario          | 场景：用带指定前缀的属性覆盖原属性，如scenario为pc时，会用pc-props覆盖props     | string          | 否       |        |
+| requiredFieldOnly | 是否只显示必填字段                                                           | boolean         | 否       | false  |
+| disabled          | 禁用                                                                        | boolean         | 否       | false  |
+| readonly          | 只读                                                                        | boolean         | 否       | false  |
+| defaultTabKey     | 默认激活的tab的key                                                           | string          | 否       |        |
+
+#### FormGroup Methods
+
+| 方法名         | 说明                   | 类型                                           |
+| -------------- | ---------------------- | ---------------------------------------------- |
+| initFormData   | 更新表单数据           | (newData?: Record<string, any>) => void        |
+| resetFormValue | 重置表单数据           | (formKey?: string | string[]) => void          |
+| validate       | 表单校验，支持分级校验  | (formKey?: string | string[], maxLevel?: number) => Promise<void> |
+| clearValidate  | 清空表单校验           | (formKey?: string | string[]) => void          |
+| getFormData    | 获取表单数据           | () => Record<string, any>                      |
+
+#### FormGroup Events
+
+| 事件名     | 说明                       | 回调参数                                             |
+| ---------- | -------------------------- | ---------------------------------------------------- |
+| change     | 当表单字段值发生改变时触发  | (keyPath: string, fieldValue: any)                   |
+| tabChange  | 切换tab时触发              | (...args: any) 传递Tab组件emit的所有参数              |
+| blur       | 当表单字段失去焦点时触发    | (e: FocusEvent, keyPath: string, fieldValue: any)    |
+| keyupEnter | 当enter键按下时触发        | (e: KeyboardEvent, keyPath: string, fieldValue: any) |
+| mounted    | 表单加载后触发             |                                                      |
+
+### 表单配置
+
+#### 类型声明
+
+```typescript
+export interface Form {
+  key: string // 表单唯一键
+  title?: string // 表单标题，多表单模式下必填
+  props?: FormProps // 表单组件props
+  show?: boolean // 显示/隐藏
+  gutter?: FormGutter // 表单项间距
+  fields: Field[] // 表单项数组
+  preScript?: string | PreScriptFunction // 表单数据前置处理脚本
+  postScript?: string | PostScriptFunction // 表单数据后置处理脚本
+  [key: string]: any
+}
+
+export type PreScriptFunction = (
+  formData: Ref<Record<string, any>>, // 当前表单数据
+  formConfig: UnwrapNestedRefs<Form>, // 当前表单配置
+) => void
+export type PostScriptFunction = (
+  formData: Ref<Record<string, any>>, // 当前表单数据
+  formConfig: UnwrapNestedRefs<Form>, // 当前表单配置
+) => Record<string, any>
+
+export type FormGutter = {
+  horizontal?: number | string // 表单项横向间距（默认单位px）
+  vertical?: number | string // 表单项纵向间距（默认单位px）
+  [key: string]: any
+}
+
+export interface FormProps {
+  labelPosition?: FormLabelPosition // 表单项标签位置
+  labelWidth?: string | number // 表单项标签宽度
+  hideRequiredAsterisk?: boolean // 是否隐藏必填星号
+  disabled?: boolean // 表单禁用
+  [key: string]: any
+}
+export type FormLabelPosition = 'left' | 'right' | 'top'
+
+export interface Field {
+  key: string // 字段键，在当前表单中需唯一
+  formKey?: string // 所属表单键，自动赋值，无需填写
+  span?: number // 表单项占据的栅格列数，最小1，最大24（默认24）
+  label?: Label | string // 标签
+  description?: string // 字段描述
+  props?: Record<string, any> // 表单项组件props
+  type: FieldType // 字段类型
+  defaultValue?: any // 默认值
+  show?: boolean // 显示/隐藏
+  disabled?: boolean | IsFieldDisabled | string // 禁用/启用，支持传入动态计算方法
+  rules?: Rule[] // 校验逻辑集合
+  component?: Component // 组件
+  actions?: Array<Action | ActionHandler | string> // 主动联动配置
+  subscribers?: Subscriber[] // 被动联动配置
+  datetimeFormatPattern?: string // 日期格式，仅当表单为只读且字段type为datetime时生效
+  className?: string // 自定义类名
+  advancedConfig?: AdvancedConfig // 高级配置项
+  [key: string]: any
+}
+
+export interface Label {
+  text?: string // 标签文本
+  width?: string // 标签宽度，会覆盖表单的labelWidth
+  [key: string]: any
+}
+
+// 校验逻辑，继承自async-validator的RuleItem类型
+export interface Rule extends Omit<RuleItem, 'validator'> {
+  level?: number // 规则级别，数值越小优先级越高，默认0
+  validator?: string | ValidatorFunction | Validator // 表单验证函数/对象
+  trigger?: string | string[] // 触发方式
+}
+export type ValidatorFunction = (
+  rule: any,
+  value: any,
+  callback: any,
+  formData: UnwrapNestedRefs<Record<string, any>>, // 当前表单数据
+  formConfig: UnwrapNestedRefs<Form>, // 当前表单配置
+  validatorParams: { rule: any; value: any; callback: any },
+  formGroupData: UnwrapNestedRefs<Record<string, any>>,
+  depValues?: any[], // 依赖项值的集合，作为Validator的校验函数时有值
+) => void
+export interface Validator {
+  name?: string // 名称
+  deps: string[] // 依赖项，格式为formKey.fieldKey
+  handler: string | ValidatorFunction // 校验函数
+}
+
+export interface Component {
+  type: ComponentType // 组件类型
+  props?: Record<string, any> // 组件props
+  options?: Option[] // 组件选项集合
+  remote?: ComponentRemote | boolean // 远程请求配置
+  [key: string]: any
+}
+export interface ComponentRemote {
+  url?: string // 远程请求URL，执行requestFn时会作为参数传入
+  extraParams?: Record<string, string | number | boolean> // 远程请求参数，执行requestFn时会作为参数传入
+  [key: string]: any
+}
+
+export type Option = {
+  value: string | number | boolean | Record<string, any>
+  label: string
+  disabled?: boolean
+  [key: string]: any
+}
+export type LabelPosition = 'top' | 'right' | 'left'
+export type FieldType =
+  | 'boolean'
+  | 'string'
+  | 'number'
+  | 'array'
+  | 'object'
+  | 'datetime'
+  | 'images'
+  | 'null'
+  | 'container'
+  | 'invisible'
+export type IsFieldDisabled = (fieldValue: any, formData: any, fieldConfig: Field) => boolean
+// 组件类型
+export enum ComponentTypeEnum {
+  Input = 'input',
+  InputNumber = 'inputNumber',
+  Select = 'select',
+  MultiSelect = 'multiSelect',
+  Cascader = 'cascader',
+  Radio = 'radio',
+  Checkbox = 'checkbox',
+  Switch = 'switch',
+  DatePicker = 'datePicker',
+  DateTimePicker = 'dateTimePicker',
+  Upload = 'upload',
+  DynamicTable = 'dynamicTable',
+  DynamicForm = 'dynamicForm',
+  DynamicTabs = 'dynamicTabs',
+  Title = 'title',
+  Collapse = 'collapse',
+  ImageList = 'imageList',
+}
+export type ComponentType = ComponentTypeEnum | string
+
+// 被动联动配置
+export interface Subscriber {
+  name?: string // 名称
+  immediate?: boolean // 是否在数据初始化后立即触发
+  deps: string[] // 依赖项，格式为formKey.fieldKey
+  handler: SubscriberHandler | string // 联动函数
+}
+export type SubscriberHandler = (
+  depValues: any[], // 依赖项值的集合
+  formKey: string, // 当前表单key
+  formData: Record<string, any>, // 当前所有表单数据
+  fieldConfig: Field, // 当前字段配置
+) => void
+export type Action = {
+  name?: string // 名称
+  immediate?: boolean // 是否在数据初始化后立即触发
+  handler: string | ActionHandler // 联动函数
+}
+export type ActionHandler = (
+  fieldValue: any, // 当前字段的值
+  formKey: string, // 当前表单key
+  formData: Record<string, any>, // 当前所有表单数据
+  formConfig: Record<string, FormWithFieldMap>, // 所有表单配置的Map
+  oldFieldValue: any, // 当前字段的旧值
+) => void
+export type FormWithFieldMap = { fieldMap: Record<string, Field> } & Form
+
+// 高级配置项
+export type AdvancedConfig = {
+  skipAutoDataReset?: boolean // 是否跳过自动数据重置，默认false
+}
+
+// UI组件
+export interface UIComponents extends Record<ComponentType, any> {
+  form: any // 表单组件
+  formItem: any // 表单项组件
+  tabs?: any // 标签页组件，用于多表单模式
+  collapse?: any // 折叠面板根组件
+  collapseItem?: any // 折叠面板子组件
+  [key: string]: any
+}
+
+export type RemoteResponse = Option[] | Promise<Option[]> | any
+export interface RequestContext {
+  requestId: number // 当前组件内递增的请求标识，用于识别过期响应
+  signal?: AbortSignal // 新请求替换旧请求或组件卸载时触发
+}
+// 远程请求方法
+export type RequestFunction = (
+  keyPath: string, // 字段键路径，格式为formKey.fieldKey
+  value: any, // 字段值
+  url?: string, // 字段remote里配置的远程请求URL
+  extraParams?: Record<string, string | number | boolean>, // 字段remote里配置的远程请求参数
+  componentParams?: Record<string, any>, // 由UI组件传入的参数，如Select组件的query、Upload组件的file等
+  context?: RequestContext, // 请求上下文，用于取消请求及识别过期响应
+) => RemoteResponse
+export type RemoteMethod = (
+  componentParams?: Record<string, any>,
+  context?: RequestContext,
+) => Option[] | Promise<Option[]> // 远程选项获取方法
+export type UploadResponse = any | Promise<any>
+export type UploadMethod = (
+  componentParams?: Record<string, any>,
+  context?: RequestContext,
+) => UploadResponse // 上传文件方法
+export type FileRemoveMethod = (
+  componentParams?: Record<string, any>,
+  context?: RequestContext,
+) => Promise<void> | void // 文件删除方法
+```
+
+远程查询和上传应将 `context.signal` 传给 `fetch`、Axios 等请求库。组件会在新查询替换旧查询、文件删除或组件卸载时触发取消；不支持取消的实现也必须避免使用过期响应回写状态。
+
+Axios 示例：
+
+```typescript
+const requestFn: RequestFunction = async (
+  keyPath,
+  value,
+  url,
+  extraParams,
+  componentParams,
+  context,
+) => {
+  const { data } = await axios.get(url || '', {
+    params: {
+      ...extraParams,
+      ...componentParams,
+    },
+    signal: context?.signal,
+  })
+
+  return data
+}
+```
+
+### 自定义组件
+
+提供一个对象，通过键名匹配自定义组件
+
+```javascript
+{
+  // ...
+  components: {
+    // 自定义组件（示例）
+    // ref: https://elemefe.github.io/element-react/#/zh-CN/component/form
+    'ZYInput': Input,
+  }
+}
+```