简介

通过js对象创建form (适用于ElementPlus + TypeScript + Vue3)

安装

npm i element-form-render

使用

1. 首先在您的项目全局的 main.ts 中设置表单生成器axios的baseURL(主要是避免每个页面都设置)

import { setAxiosConfig, setConfig, setAxios } from "element-form-render";

//设置内部使用的请求实例
setAxios(request);
//设置axios的配置，调用了setAxios的情况下无效
setAxiosConfig({
  timeout: 50000,
  baseURL: "https://domain.com", // 如果想在表单组件使用相对URL，需要设置 baseURL
  headers: { // 根据自己的需求设置headers，如无特殊需求可不设置
    "Authorization": "token",
    "Content-Type": "application/json"
  }
});
setConfig({
  static_url: "https://domain.com/static", // 静态资源地址，上传组件用到
  base_url: "https://domain.com", // 上传表单提交地址，上传组件
});

2. 通过本组件约定的结构定义编写JSON结构,创建表单

<template>
  <div>
    <form-render :json="json" @on-submit="handleSubmit" />
  </div>
</template>
<script lang="ts" setup>
  import { type FormStructure } from 'element-form-render'
  import { ref } from 'vue'

  const json = ref<FormStructure>({
    type: 'create',
    config: {
      cols: 3 //列数，默认为1
    },
    title: 'title', //设置为空则不显示标题
    api: '/api/form/create',// 不设置的话可以使用 @on-submit 获取表单提交的数据
    elements: [
      //会根据设置的列数自动分布，当前行剩余列数不足时只会占满剩余列数
      {
        type: 'input',
        name: 'title',
        label: '网站名称',
        validator: ['required']
      },
      {
        type: 'input',
        name: 'website',
        label: '网站网址',
        width: '300px',
        prefix: 'https://www',
        suffix: '.com',
        validator: ['required']
      },
      {
        type: 'radio',
        name: 'type',
        label: '网站类型',
        source: {
          type: 'static',
          options: [
            { label: '门户站', value: 'portal' },
            { label: '资源站', value: 'source' }
          ]
        }
      },
      {
        type: 'checkbox',
        name: 'tags',
        label: '网站类型',
        source: {
          type: 'ajax',
          options: {
            api: '/api/dict',
            params: { section: 'site_tag' },
            labelField: 'name',
            valueField: 'id'
          }
        }
      }
    ]
  })

  // 当表单 api 不设置时 定义获取数据的函数
  function handleSubmit(data: Record<string, any>) {
    console.log(data)
  }
</script>

3. FormStructure 类型定义

type FormStructure = {
  type: 'create' | 'update' | 'customer',// 当值为”update“时，表单将会自动请求api获取需要修改的数据
  title: string,
  elements: FormElementField[], // 字段布局
  api?: string,// 表单数据提交URL
  primary_key?: string, // 修改数据时数据主键名
  primary_value?: string | number,// 修改数据时数据主键值
  axios?: RequestInterface,//覆盖全局配置的请求实例
  base_url?: string,//覆盖全局配置的base_url
  static_url?: string,//覆盖全局配置的static_url
  config?: { // 表单设置项
    size?: '' | 'default' | 'large' | 'small',
    gutter?: number,
    cols?: number,
    labelWidth?: number,
    labelPosition?: 'left' | 'right' | 'top',
    showSubmit?: boolean,
    submitText?: string,
    showReset?: boolean,
    resetText?: string,
  },
}

API

1. 属性

| 属性 | 类型 | 备注 | |----------------|-----------------------------------|--------------------------------------| | modelValue | Record<string, any> | 表单数据 | | json | FormStructure | 参见类型定义 | | :beforeSubmit | () => Promise | boolean | 提交前回调，函数返回false阻止提交 | | :afterValidate | () => Promise | boolean | 表单验证后回调，返回false阻止提交，在beforeSubmit后执行 |

2. 事件方法

| 名称 | 类型 | 备注 | |--------------------|--------------------------------------------|----------------------------------------------------------| | @on-data | (data:Record<string, any>) => void | 当编辑数据加载完毕时触发 | | @on-submit | (data:Record<string, any>) => void | 仅当未设置json.api时，点击提交按钮时触发，在beforeSubmit和afterValidate之后 | | @after-submit | (data:Record<string, any>,res:any) => void | 仅当设置了json.api时，提交接口响应后触发 | | @update:modelValue | (data:Record<string, any>) => void | 表单数据变化时触发 | | @on-cancel | () => void | 重设表单点击事件 |

3. 实例方法

| 名称 | 类型 | 备注 | |-----------|---------------------|----------------------| | doSubmit | () => Promise | 手动提交数据,适用于不显示提交按钮的场景 | | resetForm | () => void | 清空表单数据 |

4. 支持的字段类型，详细配置见类型声明文件

| 类型标识 | 类型 | 备注 | 是否实现 | 后台接收处理说明 | |-------------|--------|---------------------|------|---------------------------------------------------| | input | 小输入框 | input[type="text"] | yes | | | password | 密码框 | password field | yes | | | number | 数字输入框 | number field | yes | | | select | 单选框 | select field | yes | | | radio | 单选按钮组 | radio | yes | | | checkbox | 多选按钮组 | checkbox | yes | | | switch | 开关 | 开是1 关 0 | yes | | | color | 颜色选择器 | 16进制颜色 | yes | '#ffffff' | | date | 日期选择 | YYYY-MM-DD | yes | | | date_range | 日期范围选择 | YYYY-MM-DD | yes | | | year | 年份选择 | YYYY | yes | | | month | 月份选择 | YYYY-MM | yes | | | datetime | 日期时间选择 | YYYY-MM-DD HH:mm | yes | | | time | 时间选择 | HH:mm:ss | yes | | | textarea | 多行纯文本 | textarea | yes | | | rich_text | 富文本 | richtext web editor | yes | | | image | 图片上传 | single image | yes | 图片地址字符串 | | images | 图片上传 | multiple images | yes | 图片地址数组 | | file | 附件上传 | single file | yes | 文件地址 | | files | 附件上传 | multiple files | yes | 文件地址数组 | | cascader | 联动选择 | cascader | yes | | | tree_select | 树状单选 | tree_select | yes | 数据项配置参考select radio checkbox | | empty | 占位空元素 | | yes | 空白占位 | | split | 表单分组标题 | | yes | 横线加标题 分割表单字段 | | slot | slot组件 | | yes | name 指定 slot 名称后,<template #name>自定义内容 |

4. 支持的validator

type Validators =
  | 'required'
  | 'string'
  | 'integer'
  | 'float'
  | 'alpha'
  | 'number'
  | 'upper'
  | 'lower'
  | 'alphaNum'
  | 'alphaDash'
  | 'url'
  | 'email'
  | 'mobile' // 中国国内手机号码
  | 'idcard' // 中国身份证号码
  | 'age'
  | 'date'
  | 'datetime'
  | 'phone' // 座机号码
  | 'telephone' // 国内固话+国内手机号(不含400 800电话)
  | 'license_code' // 企业统一信用代码
  | 'bank_code' // 银行账号 (非严谨)
  | 'amount' // 金额
  | 'chinese' // 汉字
  | `length:${number}` // 固定长度
  | `length:${number},${number}` // 长度区间
  | `regexp:${string}` // 正则表达式
  | `between:${number},${number}` // 区间
  | `gt:${number}` // 大于
  | `>:${number}` // 大于
  | `lt:${number}` // 小于
  | `<:${number}` // 小于
  | `gte:${number}` // 大于等于
  | `>=:${number}` // 大于等于
  | `lte:${number}` // 小于等于
  | `<=:${number}` // 小于等于
  | Required<FormItemRule>['validator'] // 自定义验证函数