v0.7.14

grid-layout-form.d.ts

@@ -1,21 +1,12 @@
 import React, { CSSProperties } from 'react';
-import { FormInstance, Rule } from 'rc-field-form/es/interface';
-import PropTypes from 'prop-types';
-
-/**
- * 执行一段 JS 表达式/函数并跟踪其依赖的表单字段,依赖字段变化时自动重新执行
- * @param {string} fn 要执行的表达式源码,为空时直接返回 initialValue
- * @param {*} initialValue 初始值/执行出错时的回退值
- * @param {Object} [params] 传给表达式的额外参数
- * @param {Object} [fns] 传给表达式的额外可调用函数
- * @param {*} [basicForm] 表达式里 getFieldValueForBasicForm 取值用的外层表单实例
- * @param {string} [resultType] 结果值的目标类型,用于类型转换
- * @returns {[*, *]} [执行结果(按 resultType 转换后), 执行出错时的错误对象]
- */
-declare function useFnRun(fn: string, initialValue: any, params?: any, fns?: any, basicForm?: any, resultType?: string): [any, any];
+import { GridLayoutProps, LayoutField, GridLayoutItem, GridLayoutGroup, FormInstance } from './grid-layout';
+export { FormInstance } from './grid-layout';
+import { Rule } from 'rc-field-form/es/interface';
+export { Rule } from 'rc-field-form/es/interface';
+export { useFnRun } from './grid-layout';
 
 /** useStructure 返回的表单结构数据，请求完成前为 `{ items: [], hides: [] }` */
-interface FormStructure {
+interface GridLayoutFormStructure extends GridLayoutProps {
   /** 记录主键 */
   pk?: unknown
   /** 表单唯一标识 */
@@ -26,38 +17,18 @@ interface FormStructure {
   resource?: string
   /** 字段对齐方式 */
   align?: unknown
-  /** 网格列数 */
-  cols?: number
-  /** 网格行高（px） */
-  rowHeight?: number
-  /** 网格水平间距（px） */
-  marginX?: number
-  /** 网格垂直间距（px） */
-  marginY?: number
-  /** 容器主题标识，对应 core.getWidgetComponent 的加载路径 */
-  theme?: string
-  /** 传给 theme 组件的 $setting 配置 */
-  themeProps?: Record<string, unknown>
-  /** 字段分组配置 */
-  groups?: FormGroup[]
   /** 字段联动监听字段列表（字段 code 数组） */
   listenChangeFields?: string[]
   /** 字段联动处理函数/表达式，经 func.exec 执行 */
-  listenChangeFieldsFunc?: WidgetDecorator
+  listenChangeFieldsFunc?: GridLayoutFormWidgetDecorator
   /** 可见字段列表（field.hidden 为 false） */
-  items?: FormItem[]
+  items?: GridLayoutFormItem[]
   /** 隐藏字段列表（field.hidden 为 true） */
-  hides?: FormField[]
+  hides?: GridLayoutFormField[]
 }
 
-/** 表单字段定义（对应后端返回的 field 对象） */
-interface FormField {
-  /** 字段 name，对应 rc-field-form Field.name */
-  code?: string
-  /** 字段值类型（string/number/boolean/array/bool/json 等） */
-  type?: string
-  /** 字段标签 */
-  label?: string
+/** 表单字段定义（对应后端返回的 field 对象，继承布局通用字段） */
+interface GridLayoutFormField extends LayoutField {
   /** 是否必填 */
   required?: boolean
   /** 是否隐藏 */
@@ -71,47 +42,42 @@ interface FormField {
   /** 字段提示文字 */
   help?: string
   /** 校验规则配置 */
-  validators?: FieldValidators
-  /** 透传给控件 $setting 的扩展配置 */
-  extras?: Record<string, unknown>
-  /** 字段初始值 */
-  initialValue?: unknown
-  /** 初始值语言（用于特定类型的取值转换） */
-  initialValueLanguage?: string
-  /** 虚拟字段，不参与表单提交 */
-  isVirtual?: boolean
-  /** 控件标识 */
-  widget?: string
-  /** 控件前缀 */
-  widgetPrefix?: string
+  validators?: GridLayoutFormFieldValidators
   /** 控件切换表达式/函数 */
-  widgetDecorator?: WidgetDecorator
+  widgetDecorator?: GridLayoutFormWidgetDecorator
   /** 可切换的候选子控件列表 */
-  subWidgets?: SubWidget[]
+  subWidgets?: GridLayoutFormSubWidget[]
 }
 
 /** 表单项（网格布局单元，包含字段定义与布局信息） */
-interface FormItem {
-  /** 字段定义 */
-  field?: FormField
-  /** 网格 x 坐标 */
-  x?: number
-  /** 网格 y 坐标 */
-  y?: number
-  /** 网格宽度（列数） */
-  w?: number
-  /** 网格高度（行数） */
-  h?: number
-  [key: string]: unknown
+interface GridLayoutFormItem extends GridLayoutItem {
+  /** 表单字段定义（收窄自 GridLayoutItem.field） */
+  field?: GridLayoutFormField
 }
 
-/** 字段分组配置，用于主题多分组渲染 */
-interface FormGroup {
-  /** 分组唯一标识 */
-  key: string
-  /** 分组显示标签 */
-  label?: string
-  [key: string]: unknown
+/** 字段分组配置，用于主题多分组渲染（结构等同于 GridLayoutGroup） */
+type GridLayoutFormGroup = GridLayoutGroup
+
+/** itemWidgetRender 生成的渲染函数接收的字段 props（即 GridLayoutFormField 字段在运行时的合并结果） */
+type GridLayoutFormItemWidgetProps = GridLayoutFormField & Record<string, unknown>
+
+/**
+ * itemWidgetRender 中实际渲染的部件组件约定接收的 props
+ * （由 itemWidgetRender 注入，开发者在实现自定义控件时参考此约定）
+ */
+interface GridLayoutFormItemWidgetComponentProps {
+  /** 字段值类型 */
+  type?: string
+  /** rc-field-form 表单实例 */
+  rcform?: unknown
+  /** 外层表单实例，用于字段联动/表达式求值 */
+  basicForm?: unknown
+  /** 传给 antd FormItem 的属性（label/noStyle/style/required/validateStatus/help 等） */
+  itemProps?: Record<string, unknown>
+  /** 传给实际输入控件的属性（placeholder/value/onChange 等） */
+  fieldProps?: Record<string, unknown>
+  /** 扩展配置，由 defaultProps.extras 的 key 从 props 中拆分而来 */
+  $setting?: Record<string, unknown>
 }
 
 /**
@@ -121,7 +87,7 @@ interface FormGroup {
 type EnhancedFormInstance = FormInstance & Record<string, unknown>
 
 /** useFormData / useFormSubmit / useFormAction 的表单配置参数 */
-interface FormSetting {
+interface GridLayoutFormSetting {
   /** 初始化数据的请求地址，默认 `/api/{code}` */
   initDataUri?: string
   /** 初始化数据的请求方法，默认 `'GET'` */
@@ -143,7 +109,7 @@ interface SubmitOptions {
 }
 
 /** widgetDecorator 命中时可切换的候选子控件 */
-interface SubWidget {
+interface GridLayoutFormSubWidget {
   /** 控件标识，规则同 GridLayoutFormWidget.widget */
   widget: string
   /** 控件前缀，默认同外层 widgetPrefix */
@@ -153,7 +119,16 @@ interface SubWidget {
 }
 
 /** 决定控件切换的表达式或函数，经 useFnRun 执行，返回值作为 subWidgets 下标 */
-type WidgetDecorator = string | ((...args: unknown[]) => number | undefined)
+type GridLayoutFormWidgetDecorator = string | ((...args: unknown[]) => number | undefined)
+
+/**
+ * listenChangeFieldsFunc / validator 动态表达式可调用的表单字段 API；
+ * 由 GridLayoutForm 和 useRules 通过 func.exec 第三参数注入
+ */
+type GridLayoutFormAPI = Pick<
+  FormInstance,
+  'getFieldValue' | 'setFieldValue' | 'setFieldsValue' | 'isFieldTouched' | 'isFieldsTouched'
+>
 
 /** useFieldArray 的返回值 */
 interface UseFieldArrayReturn {
@@ -185,7 +160,7 @@ interface UseFieldArrayReturn {
  * GridLayoutFormWidget 字段校验规则配置
  * 对应 useRules 的入参，由 validators prop 传入
  */
-interface FieldValidators {
+interface GridLayoutFormFieldValidators {
   /** 校验类型：string 长度校验 / pattern 正则校验 / validator 自定义 */
   type?: 'string' | 'pattern' | 'validator' | ''
   /** 是否必填 */
@@ -205,53 +180,53 @@ interface FieldValidators {
 /**
  * 按表单编码(code)拉取表单结构定义,并把字段列表拆分为可见项(items)与隐藏项(hides)
  * @param {string} code 表单编码,为空时不发起请求
- * @returns {FormStructure} 表单结构数据,请求完成前为 `{ items: [], hides: [] }`
+ * @returns {GridLayoutFormStructure} 表单结构数据,请求完成前为 `{ items: [], hides: [] }`
  */
-declare function useStructure(code: string): FormStructure;
+declare function useStructure(code: string): GridLayoutFormStructure;
 /**
  * 根据字段的校验配置生成 rc-field-form 的 rules 数组;支持必填、长度限制、正则、自定义校验函数
- * @param {FieldValidators} config
+ * @param {GridLayoutFormFieldValidators} config
  * @param {string} fieldName 字段名,传给自定义 validator 表达式
  * @param {string} fieldType 字段类型('number'|'string'|'array'|'bool'|'json' 等),决定必填校验的 type 及 bool/json 的映射
  * @returns {Rule[]} rc-field-form 规则数组
  */
-declare function useRules({ max, min, type, message, pattern, required, validator, }: FieldValidators, fieldName: string, fieldType: string): Rule[];
+declare function useRules({ max, min, type, message, pattern, required, validator, }: GridLayoutFormFieldValidators, fieldName: string, fieldType: string): Rule[];
 /**
  * 按主键(primaryKey)拉取表单初始数据;primaryKey 为空时不请求
  * @param {string} code 表单编码,用于拼接默认的请求地址 `/api/{code}`
  * @param {string|number} primaryKey 记录主键,为空时不发起请求
- * @param {FormSetting} [formSetting] 表单配置
+ * @param {GridLayoutFormSetting} [formSetting] 表单配置
  * @returns {Record<string, unknown>|null} 拉取到的表单数据,请求完成前为 `null`
  */
-declare function useFormData(code: string, primaryKey: string | number, formSetting?: FormSetting): Record<string, unknown> | null;
+declare function useFormData(code: string, primaryKey: string | number, formSetting?: GridLayoutFormSetting): Record<string, unknown> | null;
 /**
  * 生成提交表单的回调函数;校验通过后按 `__RESOURCE__` 字段值裁剪数据(若存在),经 opt.serialize 序列化后提交
  * @param {string} code 表单编码,用于拼接默认的请求地址 `/api/{code}`
  * @param {string|number} primaryKey 记录主键,存在时拼到请求地址后面
- * @param {FormSetting} [formSetting] 表单配置
+ * @param {GridLayoutFormSetting} [formSetting] 表单配置
  * @returns {(form: FormInstance, opt?: SubmitOptions) => Promise<*>} 提交函数
  */
-declare function useFormSubmit(code: string, primaryKey: string | number, formSetting?: FormSetting): (form: FormInstance, opt?: SubmitOptions) => Promise<any>;
+declare function useFormSubmit(code: string, primaryKey: string | number, formSetting?: GridLayoutFormSetting): (form: FormInstance, opt?: SubmitOptions) => Promise<any>;
 /**
  * 组合 useFormData 与 useFormSubmit:数据拉取到后自动回填表单(否则重置),并返回已绑定 form 的提交函数
  * @param {FormInstance} form rc-field-form 的表单实例
  * @param {string} code 表单编码
  * @param {string|number} primaryKey 记录主键
- * @param {FormSetting} [formSetting] 表单配置(透传给 useFormData/useFormSubmit)
+ * @param {GridLayoutFormSetting} [formSetting] 表单配置(透传给 useFormData/useFormSubmit)
  * @returns {(opt?: SubmitOptions) => Promise<*>} 已绑定当前 form 的提交函数
  */
-declare function useFormAction(form: FormInstance, code: string, primaryKey: string | number, formSetting?: FormSetting): (opt?: SubmitOptions) => Promise<any>;
+declare function useFormAction(form: FormInstance, code: string, primaryKey: string | number, formSetting?: GridLayoutFormSetting): (opt?: SubmitOptions) => Promise<any>;
 /**
  * 根据 widgetDecorator 表达式动态决定字段实际渲染的控件;
  * widgetDecorator 执行结果为 subWidgets 的下标时,切换为对应子控件(合并其 props),
  * 同时暴露 setDisabled/setRequired/getDisabled/getRequired 供 widgetDecorator 内部调用来动态调整禁用/必填状态
  * @param {string} itemWidget 默认使用的控件(已归一化的 widget 路径)
- * @param {WidgetDecorator} widgetDecorator 决定控件切换的表达式/函数,经 useFnRun 执行,返回值作为 subWidgets 下标
- * @param {SubWidget[]} [subWidgets=[]] 可切换的候选子控件列表
+ * @param {GridLayoutFormWidgetDecorator} widgetDecorator 决定控件切换的表达式/函数,经 useFnRun 执行,返回值作为 subWidgets 下标
+ * @param {GridLayoutFormSubWidget[]} [subWidgets=[]] 可切换的候选子控件列表
  * @param {FormInstance|null} [basicForm={}] 传给 widgetDecorator 执行上下文的表单实例
  * @returns {[string, Object]} `[实际渲染的控件路径, 当前生效的控件 props]`
  */
-declare function useWidgetDecorator(itemWidget: string, widgetDecorator: WidgetDecorator, subWidgets?: SubWidget[], basicForm?: FormInstance | null): [string, any];
+declare function useWidgetDecorator(itemWidget: string, widgetDecorator: GridLayoutFormWidgetDecorator, subWidgets?: GridLayoutFormSubWidget[], basicForm?: FormInstance | null): [string, any];
 /**
  * 把受控的 value/onChange 与 rc-field-form 表单实例双向桥接:外部 value 变化时同步进表单
  * (仅当与内部最近一次变更不同,避免循环),表单内部变化时回调 onChange;
@@ -289,8 +264,8 @@ declare function useFieldArray(value: any, onChange: (value: any[]) => void): Us
  * @param {Object} props
  * @param {string} [props.widget='Input'] 部件标识;以 `@` 或 `blob:` 开头时按原样使用,否则拼接 widgetPrefix 前缀
  * @param {string} [props.widgetPrefix='@pkg/ff/grid-layout-forms'] widget 非绝对标识时使用的前缀
- * @param {WidgetDecorator} [props.widgetDecorator] 决定控件切换的表达式/函数,详见 useWidgetDecorator
- * @param {SubWidget[]} [props.subWidgets=[]] widgetDecorator 命中时可切换的候选子控件列表
+ * @param {GridLayoutFormWidgetDecorator} [props.widgetDecorator] 决定控件切换的表达式/函数,详见 useWidgetDecorator
+ * @param {GridLayoutFormSubWidget[]} [props.subWidgets=[]] widgetDecorator 命中时可切换的候选子控件列表
  * @param {FormInstance|null} [props.basicForm] 表达式求值/字段联动用的外层表单实例
  * @param {string}  [props.code]          字段 name，对应 rc-field-form Field.name
  * @param {string}  [props.type]          字段值类型（string/number/boolean 等），用于取值归一化
@@ -300,7 +275,7 @@ declare function useFieldArray(value: any, onChange: (value: any[]) => void): Us
  * @param {boolean} [props.noStyle]       是否隐藏 FormItem 的 label/border 等样式
  * @param {Object}  [props.style]         FormItem 根节点行内样式
  * @param {string}  [props.help]          字段提示文字（tooltip）
- * @param {FieldValidators} [props.validators] 校验规则配置，合并到 rc-field-form rules
+ * @param {GridLayoutFormFieldValidators} [props.validators] 校验规则配置，合并到 rc-field-form rules
  * @param {Object}  [props.extras]        透传给 ItemWidget.$setting 的扩展配置（key 由 defaultProps.extras 定义）
  * @param {*}       [props.initialValue]  字段初始值
  * @param {string}  [props.initialValueLanguage] 初始值语言（用于特定类型的取值转换）
@@ -310,8 +285,8 @@ declare function useFieldArray(value: any, onChange: (value: any[]) => void): Us
 declare function GridLayoutFormWidget({ widget, widgetPrefix, widgetDecorator, subWidgets, basicForm, ...props }: {
     widget?: string;
     widgetPrefix?: string;
-    widgetDecorator?: WidgetDecorator;
-    subWidgets?: SubWidget[];
+    widgetDecorator?: GridLayoutFormWidgetDecorator;
+    subWidgets?: GridLayoutFormSubWidget[];
     basicForm?: FormInstance | null;
     code?: string;
     type?: string;
@@ -321,7 +296,7 @@ declare function GridLayoutFormWidget({ widget, widgetPrefix, widgetDecorator, s
     noStyle?: boolean;
     style?: any;
     help?: string;
-    validators?: FieldValidators;
+    validators?: GridLayoutFormFieldValidators;
     extras?: any;
     initialValue?: any;
     initialValueLanguage?: string;
@@ -360,17 +335,17 @@ declare function GridLayoutFormHelper({ $setting, $close, extras, code, primaryK
  * @param {number} [props.rowHeight=16] 栅格行高(px)
  * @param {[number, number]} [props.itemMargin=[8, 16]] 字段项间距 [横向, 纵向](px)
  * @param {[number, number]} [props.containerPadding=[0, 0]] 容器内边距 [纵向, 横向](px)
- * @param {FormItem[]} [props.fields=[]] 可见字段配置列表(位置、尺寸、部件类型等)
- * @param {FormField[]} [props.hides=[]] 隐藏字段配置列表,按 initialValueLanguage 求值后写入对应字段
+ * @param {GridLayoutFormItem[]} [props.fields=[]] 可见字段配置列表(位置、尺寸、部件类型等)
+ * @param {GridLayoutFormField[]} [props.hides=[]] 隐藏字段配置列表,按 initialValueLanguage 求值后写入对应字段
  * @param {string|number} [props.primaryKey=0] 记录主键,注入为 `__PRIMARY_KEY__` 字段值
  * @param {Record<string, unknown>} [props.formProps={}] 注入为 `__PROPS__` 字段值的表单级参数
- * @param {FormItem[]} [props.formFields=[]] 额外注入的表单字段(与 formProps/primaryKey 一并作为初始 fields)
+ * @param {GridLayoutFormItem[]} [props.formFields=[]] 额外注入的表单字段(与 formProps/primaryKey 一并作为初始 fields)
  * @param {string[]} [props.listenChangeFields] 触发联动表达式重新求值的字段列表
  * @param {*} [props.listenChangeFieldsFunc] 字段值变化时执行的联动表达式(经 func.exec 执行)
  * @param {(changedValues: Object, allValues: Object) => void} [props.onValuesChange] 表单值变化回调,先于联动表达式执行
  * @param {string} [props.theme] 主题组件标识,指定时通过 GridLayoutFramework 渲染主题外壳
  * @param {Object} [props.themeProps={}] 传给主题组件的额外参数
- * @param {FormGroup[]} [props.groups=[{key:'default',label:'默认'}]] 字段分组配置,用于主题多分组渲染
+ * @param {GridLayoutFormGroup[]} [props.groups=[{key:'default',label:'默认'}]] 字段分组配置,用于主题多分组渲染
  * @param {ReactNode} [props.children] 附加渲染在字段项之后的内容
  */
 declare function GridLayoutForm({ name, form: initForm, basicForm, style, className, cols, rowHeight, itemMargin, containerPadding, fields, hides, primaryKey, formProps, formFields, listenChangeFields, listenChangeFieldsFunc, onValuesChange, theme, themeProps, groups, children, ...props }: {
@@ -383,29 +358,19 @@ declare function GridLayoutForm({ name, form: initForm, basicForm, style, classN
     rowHeight?: number;
     itemMargin?: [number, number];
     containerPadding?: [number, number];
-    fields?: FormItem[];
-    hides?: FormField[];
+    fields?: GridLayoutFormItem[];
+    hides?: GridLayoutFormField[];
     primaryKey?: string | number;
     formProps?: Record<string, unknown>;
-    formFields?: FormItem[];
+    formFields?: GridLayoutFormItem[];
     listenChangeFields?: string[];
     listenChangeFieldsFunc?: any;
     onValuesChange?: (changedValues: any, allValues: any) => void;
     theme?: string;
     themeProps?: any;
-    groups?: FormGroup[];
+    groups?: GridLayoutFormGroup[];
     children?: React.ReactNode;
 }): React.JSX.Element;
-declare namespace GridLayoutForm {
-    namespace propTypes {
-        let fields: PropTypes.Requireable<any[]>;
-        let hides: PropTypes.Requireable<any[]>;
-    }
-}
-declare const _default: ({ code, isPreview, ...props }: {
-    [x: string]: any;
-    code: any;
-    isPreview?: boolean;
-}) => React.JSX.Element;
 
-export { GridLayoutForm, GridLayoutFormHelper, GridLayoutFormWidget, _default as default, useFieldArray, useFnRun, useFormAction, useFormData, useFormSubmit, useMergedFormValuesChange, useRules, useStructure, useWidgetDecorator };
+export { GridLayoutForm, GridLayoutFormHelper, GridLayoutFormWidget, useFieldArray, useFormAction, useFormData, useFormSubmit, useMergedFormValuesChange, useRules, useStructure, useWidgetDecorator };
+export type { EnhancedFormInstance, GridLayoutFormAPI, GridLayoutFormField, GridLayoutFormFieldValidators, GridLayoutFormGroup, GridLayoutFormItem, GridLayoutFormItemWidgetComponentProps, GridLayoutFormItemWidgetProps, GridLayoutFormSetting, GridLayoutFormStructure, GridLayoutFormSubWidget, GridLayoutFormWidgetDecorator, SubmitOptions, UseFieldArrayReturn };