开发指南

功能介绍

作为 DIY 页面装修的核心交互组件，支持用户通过「可视化拖拽 + 字段配置 + 规则自定义」的方式，零代码快速搭建个性化表单（如报名表单、问卷调研、信息收集、预约申请等），覆盖多场景数据采集需求，同时提供表单提交、数据管理、权限控制等全流程能力，确保数据采集高效、安全、可追溯。

左侧展示组件库，中间实时预览，右侧可以编辑组件的属性设置等

自定义表单装修效果图

框架开发的自定义表单功能目录位置说明

框架开发的自定义功能代码位置：niucloud-core/src/main/resources/core/loader/diy_form/

如需了解核心原理，开发者可以自行阅读

component.json 框架开发的自定义表单组件，以及加载插件的自定义表单组件

template.json 自定义扁担模板，以及加载插件的表单模板

type.json 表单类型，以及加载插件的表单类型

框架开发的自定义表单装修

自定义表单装修的核心原理

如需了解自定义表单装修的核心原理，开发者可以自行阅读

文件位置：：admin\src\app\views\diy_form\edit.vue

页面装修 store 状态管理代码

与自定义页面装修共用，万能表单页可以使用自定义组件

文件位置：admin\src\stores\modules\diy.ts

装修数据最终存储到数据表中的结构主要包含两大部分：

global： global 对象为整体页面的数据结构，后续还会持续完善，实现更加灵活的自定义装修

value：value 为组件集合，在装修时添加自定义组件会变化

uni-app 手机端渲染自定义组件 diy-group 组件

在移动端（uni-app）中，自定义页面通过 diy-group 组件进行渲染。该组件负责解析和展示装修数据中的所有组件

文件位置：uni-app/src/addon/components/diy/group/

自定义表单组件渲染管理代码

文件位置：uni-app/src/hooks/useDiyForm.ts

自定义表单组件

功能介绍

在装修自定义表单时，可以使用表单组件，也可以使用自定义组件，两者都可以搭配使用

框架定义的表单组件

系统框架以及定义好了一些基础的通用组件（不包含业务），若无业务需求，开发者可以正常使用，无需重复开发

文件位置：niucloud-core/src/main/resources/core/loader/diy_form/component.json

前端定义表单组件的编辑属性组件

框架定义的自定义表单组件目录为：admin/src/app/views/diy_form/components

uni-app 手机端渲染自定义表单组件

框架定义的自定义组件目录为：uni-app/src/app/components/diy（与自定义组件都在一个目录下）

开发自定义表单组件步骤

若框架定义的表单组件无法满足需求，可以自行开发表单组件

新建 component.json 文件

文件位置：niucloud-addon/shop/src/main/resources/shop/loader/poster/component.json

关键代码

{
  "CSSHOP_FORM_COMPONENT": {     // 组件分类关键字key，建议大写
    "title": "商城表单组件",    // 组件分类名称
    "support": [],
    "list": {    // 组件列表
      "FormSubmit": {   // 组件关键字key
        "title": "商城表单提交",    // 组件名称
        "icon": "iconfont icona-biaodantijiaopc30", // 组件图标
        "path": "edit-form-submit", // 组编辑组件属性名称
        "uses": 1,  // 最大添加数量，0为不限制
        "support": [],
        "sort": 10001,  // 排序号，从小到大
        "position": "bottom_fixed",  // 组件置顶标识，不能拖拽，可选值：fixed、top_fixed、right_fixed、bottom_fixed、left_fixed
        "template": {   // 组件属性
          "textColor": "#303133",    // 组件字体颜色
          "pageStartBgColor": "",    // 组件背景颜色
          "pageEndBgColor": "",    // 组件背景颜色
          "pageGradientAngle": "to bottom",  // 组件背景渐变角度
          "componentBgUrl": "",  // 组件背景图片
          "componentBgAlpha": 2,  // 组件背景图片透明度
          "componentStartBgColor": "",  // 组件背景颜色
          "componentEndBgColor": "",  // 组件背景颜色
          "componentGradientAngle": "to bottom",  // 组件背景渐变角度
          "topRounded": 0,  // 组件顶部圆角
          "bottomRounded": 0,  // 组件底部圆角
          "elementBgColor": "",  // 组件元素背景颜色
          "topElementRounded": 50,  // 组件元素顶部圆角
          "bottomElementRounded": 50,  // 组件元素底部圆角  
          "margin": {
            "top": 8,    // 组件顶部外边距
            "bottom": 0,  // 组件底部外边距
            "both": 10    // 组件左右外边距
          }
        },
        "value": {
          "btnPosition": "follow_content",
          "submitBtn": {
            "text": "提交",
            "color": "#ffffff",
            "bgColor": "#409EFF"
          },
          "resetBtn": {
            "control": true,
            "text": "重置",
            "color": "",
            "bgColor": ""
          }
        },
        "componentType": "diy_form"
      }
    }
  }
}

前端定义编辑属性组件

代码位置：admin/src/addon/shop/views/diy_form/components

根据 component.json 定义的 path 路径，需要在前端定义编辑属性组件

edit 编辑属性组件

框架封装好了表单组件公共设置和样式

组件忽略属性

每个组件可以根据自身业务情况，设置忽略组件样式，防止出现不可控效果

关键代码，为空时表示不忽略

目前可忽略的属性如下：

属性名	说明
pageBgColor	底部背景颜色
componentBgUrl	组件背景图
componentBgColor	组件背景颜色
marginTop	上边距
marginBottom	下边距
marginBoth	左右边距
topRounded	上圆角
bottomRounded	下圆角

uni-app 手机端定义渲染组件

目录位置：uni-app/src/addon/shop/components/diy

根据 component.json 定义的组件关键字 key，需要在 uni-app 手机端定义渲染组件

例如：组件关键字 key 为 FormSubmit。渲染组件名称就是：form-submit，将驼峰命名改成横杠-分割即可。注意：组件文件名称是小写

自定义表单类型

功能介绍

开发者可以根据自身业务需求，开发表单类型。后续开发表单模板、渲染表单、初始化站点数据都会用到

框架定义的表单类型

系统框架开发的表单类型：自定义表单、个人资料

文件位置：niucloud-core/src/main/resources/core/loader/diy_form/type.json

插件开发表单类型

文件位置：niucloud-addon/shop/src/main/resources/shop/loader/diy_form/type.json

关键代码

{
  "DIY_FORM_GOODS_DETAIL": {        // 表单类型关键字key
    "title": "商品详情",        // 表单类型名称
    "preview": "addon/shop/diy_form/goods_detail_preview.png",        // 预览图
    "sort": 10005,  // 排序号，从小到大
    "addon": "shop" // 所属插件标识key
  },
  "DIY_FROM_ORDER_PAYMENT": {
    "title": "订单付款",
    "preview": "addon/shop/diy_form/order_payment_preview.png",
    "sort": 10006,
    "addon": "shop"
  }
}

自定义表单模板

功能介绍

每种表单类型可以定义 N 个表单模板，维护好表单模板后，可以在装修的时候快速创建，然后进行调整

框架定义的表单模板

文件位置：niucloud-core/src/main/resources/core/loader/diy_form/template.json

插件开发表单模板

文件位置：niucloud-addon/shop/src/main/resources/shop/loader/diy_form/template.json

关键代码说明

{
  "DIY_FORM_GOODS_DETAIL": {    // 表单类型关键字key
    "shop_goods_detail_form_data": {    // 表单模板名称
      "title": "商品表单",      
      "cover": "",  // 表单模板封面图
      "preview": "",  // 表单模板预览图
      "desc": "",  // 表单模板描述
      "data": {
            // todo 自定义表单数据结构
      }
    }
  }
}

form-submit 表单提交组件

注意：若前端以嵌入形式调用表单，提交按钮组件将不显示，相关业务由该页面自行处理

uni-app 表单渲染与详情组件

diy-form uni-app 表单渲染组件

开发完表单组件后，需要在uni-app手机端进行调用展示

根据业务需求，自行开发，在需要的地方调用 diy-form 表单组件

用户填写的表单信息会缓存起来，不用担心跳转页面、刷新页面导致数据丢失的情况

如需了解自定义表单组件渲染的核心原理，开发者可任意自行阅读

文件位置：uni-app/src/addon/components/diy-form/index.vue

效果图

关键代码

<diy-form ref="diyFormRef" :form_id="form_id" :storage_name="'diyFormStorageByGoodsDetail_' + sku_id" />

import diyForm from '@/addon/components/diy-form/index.vue'

const diyFormRef: any = ref(null)

const confirm = () => {
    // 表单验证
    if (!diyFormRef.value.verify()) return;
    // todo 执行后续业务逻辑代码
}

// 获取填写的表单信息
diyFormRef.value.getData()

// 清除填写的表单信息
diyFormRef.value.clearStorage()

diy-form-detail uni-app 表单详情组件

用户填写完表单信息后，开发者根据自身业务需求，自行开发，在需要的地方调用

diy-form-detail 表单详情组件

如需了解自定义表单详情渲染的核心原理，开发者可以自行阅读

文件位置：uni-app/src/addon/components/diy-form-detail/index.vue

效果图

关键代码

<diy-form-detail :record_id="form_record_id" completeLayout="style-2" @callback="getDiyFormDetailCallback" />

import diyFormDetail from '@/addon/components/diy-form-detail/index.vue'

const getDiyFormDetailCallback = (data: any) => {
    // todo data为填写的表单信息
}