276 lines
13 KiB
TypeScript
276 lines
13 KiB
TypeScript
import { FormInstance } from 'rc-field-form/es/interface';
|
||
export { FormInstance } from 'rc-field-form/es/interface';
|
||
import React from 'react';
|
||
|
||
/** 布局分组配置，用于主题多分组渲染 */
|
||
interface GridLayoutGroup {
|
||
/** 分组唯一标识 */
|
||
key: string
|
||
/** 分组显示标签 */
|
||
label?: string
|
||
[key: string]: unknown
|
||
}
|
||
|
||
/** 字段项盒模型配置（margin / padding / align / autoHeight） */
|
||
interface BoxStyle {
|
||
/** 是否按内容自适应高度（不再固定跨行） */
|
||
autoHeight?: boolean
|
||
/** 对齐方式，写入 `--grid-layout-box-align-items` */
|
||
alignItems?: string
|
||
/** 主轴对齐方式，写入 `--grid-layout-box-justify-content` */
|
||
justifyContent?: string
|
||
/** 外边距 - 上（px） */
|
||
marginTop?: number
|
||
/** 外边距 - 右（px） */
|
||
marginRight?: number
|
||
/** 外边距 - 下（px） */
|
||
marginBottom?: number
|
||
/** 外边距 - 左（px） */
|
||
marginLeft?: number
|
||
/** 内边距 - 上（px） */
|
||
paddingTop?: number
|
||
/** 内边距 - 右（px） */
|
||
paddingRight?: number
|
||
/** 内边距 - 下（px） */
|
||
paddingBottom?: number
|
||
/** 内边距 - 左（px） */
|
||
paddingLeft?: number
|
||
}
|
||
|
||
/**
|
||
* 字段内容配置基础类型（ff-grid-layout 与 ff-grid-layout-form 共用）
|
||
*/
|
||
interface LayoutField {
|
||
/** 字段标识，对应 rc-field-form 的 name */
|
||
code?: string
|
||
/** 字段标签 */
|
||
label?: string
|
||
/** 传给控件 $setting 的扩展配置 key 集合（key 存在时从 props 拆分为 extraProps） */
|
||
extras?: Record<string, unknown>
|
||
/** 是否虚拟字段，为 true 时不绑定表单字段（name 传 null） */
|
||
isVirtual?: boolean
|
||
/** 初始值，或 initialValueLanguage 为 'javascript' 时的表达式源码 */
|
||
initialValue?: unknown
|
||
/** 初始值类型，'javascript' 时把 initialValue 当表达式执行 */
|
||
initialValueLanguage?: string
|
||
/** 字段值目标类型（string / number / boolean / array 等），用于 toPrimitive 转换 */
|
||
type?: string
|
||
/** 部件标识；以 `@` 或 `blob:` 开头时按原样使用，否则拼接 widgetPrefix */
|
||
widget?: string
|
||
/** widget 非绝对标识时使用的前缀 */
|
||
widgetPrefix?: string
|
||
/** 盒模型配置；getNormalizeFields 渲染时从 field 中提取，不传给 ItemWidget */
|
||
boxStyle?: BoxStyle
|
||
[key: string]: unknown
|
||
}
|
||
|
||
/**
|
||
* ff-grid-layout 字段内容配置（在 LayoutField 基础上增加展示值转换配置）
|
||
*/
|
||
interface GridLayoutField extends LayoutField {
|
||
/** 展示值转换表达式（交给 DataConverter 处理） */
|
||
convertJs?: unknown
|
||
/** convertJs 表达式的附加配置 */
|
||
convertJsSetting?: unknown
|
||
}
|
||
|
||
/** 布局字段项（网格坐标 + 字段内容），对应 getNormalizeFields 入参列表的每一项 */
|
||
interface GridLayoutItem {
|
||
/** 字段唯一标识，用作 React key；优先于数组下标 */
|
||
i?: unknown
|
||
/** 网格 x 坐标（起始列，0-indexed） */
|
||
x?: number
|
||
/** 网格 y 坐标（起始行，0-indexed） */
|
||
y?: number
|
||
/** 网格宽度（列数） */
|
||
w?: number
|
||
/** 网格高度（行数） */
|
||
h?: number
|
||
/** 所属分组的 key，缺省时归入 'default' 分组 */
|
||
group?: string
|
||
/** 字段内容配置；field.boxStyle 决定盒模型，其余字段传给 ItemWidget */
|
||
field?: GridLayoutField
|
||
[key: string]: unknown
|
||
}
|
||
|
||
/** GridLayout 组件的布局配置参数（不含 form/DOM 相关 props） */
|
||
interface GridLayoutProps {
|
||
/** 栅格列数，默认 12 */
|
||
cols?: number
|
||
/** 栅格行高（px），默认 21 */
|
||
rowHeight?: number
|
||
/** 容器内边距 [纵向, 横向]（px），默认 [0, 0] */
|
||
containerPadding?: [number, number]
|
||
/** 字段项间距 [纵向, 横向]（px），默认 [4, 0] */
|
||
itemMargin?: [number, number]
|
||
/** 布局字段配置列表 */
|
||
fields?: GridLayoutItem[]
|
||
/** 字段分组配置，用于主题多分组渲染 */
|
||
groups?: GridLayoutGroup[]
|
||
/** 主题组件标识，通过 core.getWidgetComponent 异步加载 */
|
||
theme?: string
|
||
/** 传给主题组件的 $setting 配置 */
|
||
themeProps?: Record<string, unknown>
|
||
}
|
||
|
||
/** useStructure 返回的布局结构数据，请求完成前为 `{ items: [] }` */
|
||
interface GridLayoutStructure extends GridLayoutProps {
|
||
/** 布局唯一标识 */
|
||
uuid?: string
|
||
/** 布局编码 */
|
||
code?: string
|
||
/** 布局名称 */
|
||
name?: string
|
||
/** 关联资源标识 */
|
||
resource?: string
|
||
/** 记录主键 */
|
||
primaryKey?: unknown
|
||
/** 布局字段配置列表（API 返回名，组件侧对应 GridLayoutProps.fields） */
|
||
items?: GridLayoutItem[]
|
||
}
|
||
|
||
/** useField 返回值：[经 convertJs 转换后的展示值（未配置时等于原值）, 原始字段值] */
|
||
/**
|
||
* useFnRun / useField 内 func.exec 脚本上下文中可调用的字段读取 API；
|
||
* 由 useFnRun 注入，包含当前表单与外层(basicForm)表单的只读接口
|
||
*/
|
||
type GridLayoutFieldAPI = Pick<FormInstance, 'getFieldValue' | 'isFieldTouched' | 'isFieldsTouched'> & {
|
||
/** 从外层(basicForm)表单获取字段值；无 basicForm 时返回 null */
|
||
getFieldValueForBasicForm: (name: Parameters<FormInstance['getFieldValue']>[0]) => unknown
|
||
}
|
||
|
||
type UseFieldReturn = [displayValue: unknown, rawValue: unknown]
|
||
|
||
/** useFnRun 返回值：[按 resultType 转换后的执行结果, 执行出错时的错误对象（null 表示无错误）] */
|
||
type UseFnRunReturn = [result: unknown, error: unknown]
|
||
|
||
/** rc-field-form 内部钩子的注册标识 */
|
||
declare const HOOK_MARK: "RC_FORM_INTERNAL_HOOKS";
|
||
/**
|
||
* 按布局 code 拉取布局结构定义(字段、主题、栅格设置等),code 变化时重新请求
|
||
* @param {string} code 布局的唯一编码
|
||
* @returns {GridLayoutStructure} 布局结构数据，请求完成前为 `{ items: [] }`
|
||
*/
|
||
declare function useStructure(code: string): GridLayoutStructure;
|
||
/**
|
||
* 关联表单字段值,支持初始值表达式求值、watch 联动更新以及经 DataConverter 转换后的展示值
|
||
* @param {string} name 字段名（rc-field-form 的字段路径）
|
||
* @param {Object} setting 字段取值相关配置
|
||
* @param {*} [setting.initialValue] 初始值，或语言为 javascript 时的表达式源码
|
||
* @param {string} [setting.initialValueLanguage] 初始值类型，'javascript' 时把 initialValue 当表达式执行
|
||
* @param {*} [setting.convertJs] 用于生成展示值的转换表达式（交给 DataConverter 处理）
|
||
* @param {*} [setting.convertJsSetting] convertJs 表达式的附加配置
|
||
* @param {string} [setting.type='string'] 字段值的目标类型，用于类型转换
|
||
* @param {*} [pContext] 表达式里 getFieldValueForBasicForm 取值用的外层表单实例
|
||
* @returns {UseFieldReturn}
|
||
*/
|
||
declare function useField(name: string, { initialValue, initialValueLanguage, convertJs, convertJsSetting, type, }: {
|
||
initialValue?: any;
|
||
initialValueLanguage?: string;
|
||
convertJs?: any;
|
||
convertJsSetting?: any;
|
||
type?: string;
|
||
}, pContext?: any): UseFieldReturn;
|
||
/**
|
||
* 按 (y, x) 排序将字段列表归一化为渲染项列表(每项已用给定的 ItemWidget 渲染成元素)
|
||
* @param {GridLayoutItem[]} fields 字段配置列表
|
||
* @param {Function} ItemWidget 用于渲染每个字段的组件
|
||
* @param {*} [basicForm] 传给每个字段渲染项的外层表单实例
|
||
* @returns {ReactNode[]} 已排序并渲染完成的元素列表
|
||
*/
|
||
declare function useGridLayoutFields(fields: GridLayoutItem[], ItemWidget: Function, basicForm?: any): React.ReactNode[];
|
||
/**
|
||
* 执行一段 JS 表达式/函数并跟踪其依赖的表单字段,依赖字段变化时自动重新执行
|
||
* @param {string} fn 要执行的表达式源码,为空时直接返回 initialValue
|
||
* @param {*} initialValue 初始值/执行出错时的回退值
|
||
* @param {Object} [params] 传给表达式的额外参数
|
||
* @param {Partial<GridLayoutFieldAPI>} [fns] 传给表达式的额外可调用函数（useFnRun 会在此基础上注入 getFieldValue/isFieldTouched 等）
|
||
* @param {*} [basicForm] 表达式里 getFieldValueForBasicForm 取值用的外层表单实例
|
||
* @param {string} [resultType] 结果值的目标类型,用于类型转换
|
||
* @returns {UseFnRunReturn}
|
||
*/
|
||
declare function useFnRun(fn: string, initialValue: any, params?: any, fns?: Partial<GridLayoutFieldAPI>, basicForm?: any, resultType?: string): UseFnRunReturn;
|
||
|
||
/**
|
||
* 按 widget 标识异步加载并渲染对应的部件组件,加载完成前不渲染任何内容;
|
||
* 加载出错时渲染错误信息文本
|
||
* @param {Object} props
|
||
* @param {string} [props.widget] 部件标识；以 `@` 或 `blob:` 开头时按原样使用，否则拼接 widgetPrefix 前缀
|
||
* @param {string} [props.widgetPrefix='@pkg/ff/grid-layouts'] widget 非绝对标识时使用的前缀
|
||
* @param {FormInstance} [props.basicForm] 表达式求值/字段联动用的外层表单实例
|
||
*/
|
||
declare function GridLayoutWidget({ widget, widgetPrefix, basicForm, ...props }: {
|
||
widget?: string;
|
||
widgetPrefix?: string;
|
||
basicForm?: FormInstance;
|
||
}): undefined;
|
||
|
||
/**
|
||
* 按 theme 标识异步加载主题外壳组件,并把每个分组(items)渲染成 itemRender 生成的内容后传给主题组件;
|
||
* theme 未指定时不渲染,加载出错时渲染错误信息文本
|
||
* @param {Object} props
|
||
* @param {string} [props.theme] 主题组件标识,通过 core.getWidgetComponent 加载
|
||
* @param {*} [props.basicForm] 传给主题组件及各分组内容的外层表单实例
|
||
* @param {GridLayoutGroup[]} [props.items=[{key:'default',label:'默认'}]] 分组配置列表
|
||
* @param {GridLayoutItem[]} [props.fields=[]] 全部布局字段，按分组 key 过滤后分给对应 items 项
|
||
* @param {(item: GridLayoutGroup, fields: GridLayoutItem[], children: *) => *} [props.itemRender] 生成单个分组渲染内容的函数
|
||
* @param {Array} [props.chunks=[]] 额外附加在 items 之后、不参与过滤的分组项
|
||
* @param {*} [props.children] 仅附加给 key 为 'default' 的分组的内容
|
||
* @param {Object} [props.$setting={}] 传给主题组件的基础设置,会与 themeSetting 合并
|
||
*/
|
||
declare function GridLayoutFramework({ theme, basicForm, items, fields, itemRender, chunks, children, $setting, ...themeSetting }: {
|
||
theme?: string;
|
||
basicForm?: any;
|
||
items?: GridLayoutGroup[];
|
||
fields?: GridLayoutItem[];
|
||
itemRender?: (item: GridLayoutGroup, fields: GridLayoutItem[], children: any) => any;
|
||
chunks?: any[];
|
||
children?: any;
|
||
$setting?: any;
|
||
}): undefined;
|
||
|
||
/**
|
||
* 栅格布局容器,按 fields 描述的位置/尺寸渲染各字段部件,并托管一个 rc-field-form 表单;
|
||
* 指定 theme 时委托 GridLayoutFramework 渲染主题外壳,否则直接渲染默认分组
|
||
* @param {Object} props
|
||
* @param {string} [props.name] 表单字段容器名(即 __LAYOUT_KEY__ 语义,由 GridLayoutHoc 传入)
|
||
* @param {FormInstance} [props.form] 外部传入的 rc-field-form 表单实例，不传时内部自建
|
||
* @param {FormInstance} [props.basicForm] 表达式求值/字段联动用的外层表单实例
|
||
* @param {Object} [props.style] 容器行内样式
|
||
* @param {string} [props.className] 容器额外 class 名
|
||
* @param {number} [props.cols=12] 栅格列数
|
||
* @param {number} [props.rowHeight=21] 栅格行高(px)
|
||
* @param {[number, number]} [props.containerPadding=[0, 0]] 容器内边距 [纵向, 横向](px)
|
||
* @param {[number, number]} [props.itemMargin=[4, 0]] 字段项间距 [纵向, 横向](px)
|
||
* @param {Object} [props.formProps={}] 注入为 `__PROPS__` 字段值的表单级参数
|
||
* @param {Array} [props.formFields=[]] 额外注入的表单字段(与 formProps 一并作为初始 fields)
|
||
* @param {GridLayoutItem[]} [props.fields=[]] 布局字段配置列表（位置、尺寸、部件类型等）
|
||
* @param {Object} [props.data] 初始化/回填表单的数据
|
||
* @param {string} [props.theme] 主题组件标识，指定时通过 GridLayoutFramework 渲染主题外壳
|
||
* @param {Object} [props.themeProps={}] 传给主题组件的额外参数
|
||
* @param {GridLayoutGroup[]} [props.groups=[{key:'default',label:'默认'}]] 字段分组配置，用于主题多分组渲染
|
||
* @param {*} [props.children] 附加渲染在字段项之后的内容
|
||
*/
|
||
declare function GridLayout({ name, form: initForm, basicForm, style, className, cols, rowHeight, containerPadding, itemMargin, formProps, formFields, fields, data, theme, themeProps, groups, children, ...props }: {
|
||
name?: string;
|
||
form?: FormInstance;
|
||
basicForm?: FormInstance;
|
||
style?: any;
|
||
className?: string;
|
||
cols?: number;
|
||
rowHeight?: number;
|
||
containerPadding?: [number, number];
|
||
itemMargin?: [number, number];
|
||
formProps?: any;
|
||
formFields?: any[];
|
||
fields?: GridLayoutItem[];
|
||
data?: any;
|
||
theme?: string;
|
||
themeProps?: any;
|
||
groups?: GridLayoutGroup[];
|
||
children?: any;
|
||
}): React.JSX.Element;
|
||
|
||
export { GridLayout, GridLayoutFramework, GridLayoutWidget, HOOK_MARK, useField, useFnRun, useGridLayoutFields, useStructure };
|
||
export type { BoxStyle, GridLayoutField, GridLayoutFieldAPI, GridLayoutGroup, GridLayoutItem, GridLayoutProps, GridLayoutStructure, LayoutField, UseFieldReturn, UseFnRunReturn };
|