格子表单：基于 GRID 布局的简单表单工具（包含可视化设计器、渲染器），默认组件库为 Naive UI，同时支持 .zip

<div align=center> <h1> 栅栏（格子）表单 / GRID-FORM </h1>    </div> 基于 GRID 布局的简单表单工具（包含可视化设计器、渲染器），默认组件库为 [Naive UI](https://www.naiveui.com)。 此工具仅适用于布局简单纯粹的表单场景 😄 包名|说明|进度|版本 -|-|-|- common|通用工具|✅| designer|可视化设计器（基于 Naive UI）|✅| render-naive|基于[Naive UI](https://www.naiveui.com)实现的渲染器|✅| render-element|基于[Element Plus](https://element-plus.org/zh-CN/)实现的渲染器|✅| render-vant|基于[Vant4](https://vant-ui.github.io)实现的渲染器|✅| **相关博文** * [基于 VUE3 可视化低代码表单设计器](https://blog.csdn.net/ssrc0604hx/article/details/128825163) * [嵌套子表单与自定义脚本交互](https://blog.csdn.net/ssrc0604hx/article/details/135828101) ## 1. 总览 / OVERVIEW  更多截图请看 [screenshot](docs/screenshot) ## 2. 开始使用 / GETTING STARTED ### 2.1 仅使用渲染器 1. 安装依赖 ```shell npm i -S @grid-form/render-naive ``` 2. 使用渲染器组件 ```html <FormRender :renders="RenderFuncs" :form="form" debug @submit="onSubmit" @failed="onFailed" /> ``` ```javascript import { FormRender, RenderFuncs } from "@grid-form/render-naive" // 如需扩展 RenderFuncs 请自行扩写 // 表单对象通常来自后端，详细数据结构请查看 packages/example/src/views/渲染器.vue let form = reactive({}) ``` **Props** 名称|类型|默认值|说明 -|-|-|- renders|Object|{}|组件渲染函数 gridGap|Number|10|可视化区域栅栏间隔，单位 px form|Object|undefined|表单对象 review|Boolean|false|是否在提交前对表单项做校验 debug|Boolean|false|开启debug 模式后，会在控制台输入各种信息 placeholder|String|`^\\${(.*)}$`|默认值占位符检测正则表达式 valueProvider|Object|{}|占位符内容计算函数，详见下一节的说明 on-inited|()=>void|undefined| on-submit|(formObj:Object,action="post")=>void|undefined|用户点击提交按钮后触发（如设置了 `review` 则自检成功后方触发） on-failed|(fails:Array[String])=>void|undefined|设置`review`后自检失败触发 #### 2.1.1 表单项默认值 > 我们可以通过`${xxxx}`的格式设置（注意，前后不能有其他字符）表单项的默认值，渲染过程中会将占位符替换为计算后的值 ```javascript //默认使用的计算函数 import { formValueProvider } from "@grid-form/common" import dayjs from 'dayjs' /* 扩展默认的表单默认值计算器 支持 Promise （未作异常捕获，慎用） */ formValueProvider["${date}"] = ()=> dayjs(new Date()).format("YYYY-MM-DD") formValueProvider["${username}"] = ()=> "集成显卡" //详见 packages\example\src\views\渲染器.vue ``` #### 2.1.2 内置组件 > 业务系统可自行扩展自定义组件 组件名称|说明|Naive UI|Element Plus|Vant4 -|-|-|-|- 文本输入|支持TEXTAREA|✅|✅|✅ 数值输入|仅限数字|✅|✅|✅ 动态标签|标签组输入（Array）|✅|✅| `按钮`|可用于交互操作|✅|✅|✅ 日期选择||✅|✅|✅ 下拉选择（Select）|支持多选|✅|✅|✅ 单选框（Radio）||✅|✅|✅ 开关（Switch）|布尔值|✅|✅|✅ 多选框（Checkbox）||✅|✅|✅ 星级评分（Rate）|数值|✅|✅|✅ 颜色选择器||✅|✅| 文件上传|按指定格式读取内容|✅|✅|✅ 静态文本|支持HTML|✅|✅|✅ 信息框|标题+正文，支持HTML|✅|✅|✅ 分割线||✅|✅|✅ `图片展示`||✅|✅|✅ 静态表格|简单的二维数据展示表格|✅|✅|✅ 子容器（Card）|嵌套容器|✅|✅|✅ 注意：上述组件`特殊标注`则表示支持自定义脚本 ### 2.2 使用设计器 > 设计器依赖 render-naive ```shell npm i -S @grid-form/designer @grid-form/render-naive ``` ```html <Designer :renders="RenderFuncs" :components="Components" :form="form" debug show-footer style="height: 100%;" /> ``` ```javascript import { reactive } from 'vue' import { Designer, Components } from "@grid-form/designer" import { RenderFuncs } from "@grid-form/render-naive" import { createForm } from "@grid-form/common" // 如需扩展 RenderFuncs、Components ，请自行扩写 let form = reactive(createForm()) ``` **Props** 名称|类型|默认值|说明 -|-|-|- components|Array|[]|组件库 renders|Object|{}|组件渲染函数 siderWidth|Number,String|360|左右侧边栏的宽度，支持 px、% 单位，建议直接传递数值 gridGap|Number|10|可视化区域栅栏间隔，单位 px review|Boolean|false|是否对表单项做校验（如id、名称不能为空，不允许重复 id），校验不通过则抛出异常 form|Object|undefined|表单对象 compact|Boolean|false|紧凑的布局，如果设置为true，则左右两侧的属性编辑行距缩短 headerHeight|Number|55|设计器头部高度 showFooter|Boolean|false|是否显示设计器底部 footerHeight|Number|50|设计器底部高度，单位 px contextMenu|Boolean|false|`SINCE 0.0.6`是否启用右键菜单（方便操控表单项） enableCtrlS|Boolean|false|`SINCE 0.0.8`是否启用 CTRL+S 保存快捷键 debug|Boolean|false|开启debug 模式后，会在控制台输入各种信息 **Slots** 名称|说明 -|- title|设计器头部标题内容 footer|设计器底部内容（需要设置 `show-footer` 为 true） 效果如下  ## 3. 数据结构 / DATA STRUCTURE ### 3.1 表单 属性|类型|默认值|说明 -|-|-|- id|String|undefined|表单ID（由业务系统自行填充） size|String|medium|整体表单尺寸，其他值：`small`、`large` width|String,Number|100%|表单宽度（支持 px、% 格式） grid|Number|3|栅栏格数（1 到 24 之间） labelWidth|Number|120|标签宽度（单位 px） labelShow|Boolean|true|全局设置标签是否显示 labelPlacement|String|top|标签位置，其他值：`left`（左边），`Vant`渲染器不适用 labelAlign|String|left|标签对齐方式，其他值：`right`（靠右） submitText|String|提交数据|默认按钮的文本（若为空，则不显示该按钮） okText|String||提交完成后回显文案（由业务系统进行回显） url|String||后端接口地址（由业务系统完成数据提交） onLoad|String|undefined|`JS 代码`表单初始化后调用 onSubmit|String|undefined|`JS 代码`表单提交前调用钩子，用于进行数据预处理，也可以中断表单（返回 Promise） onChange|String|undefined|`JS 代码`表单值变动时调用钩子，通常用于表单联动（`since v0.0.4`） afterSubmit|String|undefined|`JS 代码`表单提交完成后调用钩子（注意：需要由业务系统自行调用） hides|Array|[]|表单默认值（隐藏项），包含`id`、`value`两个属性 items|Array|[]|表单项 buttons|Array|[]|自定义按钮 ### 3.2 表单项 > 表单项属性分两类：控件属性、基本信息（以`_`开头），分别对应了组件渲染函数的两个参数：`props`、`attrs` 属性|类型|默认值|说明 -|-|-|- _uuid|String||表单项ID（对于显示类组件不存在该属性） _text|String||标签内容 _widget|String||组件编号（按此定位渲染函数） _col|Number|1|组件所占格子数 _value|String||默认值（支持占位符）