Introduction

Create Vue Form by JSON (for ElementPlus + TypeScript + Vue3)

Install

npm i element-form-render

Usage

1. Add below code to main.ts to initialize axios params which used in form render

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

// set your axios instance that must be implements 'RequestInterface' interface if you don't want to use the buildin request library
setAxios(request);
// It you want to use the buildin request lib,
// you should config the axios parameters like bellow
setAxiosConfig({
  timeout: 50000,
  baseURL: "https://domain.com", //
  headers: { // set headers when you need
    "Authorization": "token",
  }
});
setConfig({
  static_url: "https://static.domain.com", // Static resource host domain
  base_url: "https://api.domain.com", // Api data, File Upload domain
});

2. Follow the JSON struct rules to create form

<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', // create OR update OR customer
    config: {
      cols: 3 // Cols number, Default is 1
    },
    title: 'title', // Form title, Leave empty to hide title
    api: '/form/create',// Leave empty that can use @on-submit to catch form data
    elements: [
      // Element layout will follow the config.cols with fill mode
      {
        type: 'input',
        name: 'title',
        label: 'Site Name',
        validator: ['required']
      },
      {
        type: 'input',
        name: 'website',
        label: 'Site URL',
        width: '300px',
        prefix: 'https://www',
        suffix: '.com',
        validator: ['required']
      },
      {
        type: 'radio',
        name: 'type',
        label: 'Type',
        source: {
          type: 'static',
          options: [
            { label: 'Portal', value: 'portal' },
            { label: 'Software', value: 'source' }
          ]
        }
      },
      {
        type: 'checkbox',
        name: 'tags',
        label: 'Tags',
        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 definition

type FormStructure = {
  type: 'create' | 'update' | 'customer',// If type is update, the form will load data automatily
  title: string,
  elements: FormElementField[], // Form Elements
  api?: string,// form action
  primary_key?: string, // Primary key name
  primary_value?: string | number,// primary key valye
  axios?: RequestInterface,// Overwrite the buildin request instance
  base_url?: string,// Overwrite global config: base_url
  static_url?: string,// Overwrite global config: static_url
  config?: { // Form 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> | formData | | 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. Supported validators

type Validators =
  | 'required'
  | 'string'
  | 'integer'
  | 'float'
  | 'alpha'
  | 'number'
  | 'upper'
  | 'lower'
  | 'alphaNum'
  | 'alphaDash'
  | 'url'
  | 'email'
  | 'mobile' // China mobile phone number rule
  | 'idcard' // China idcard rule
  | 'age'
  | 'date'
  | 'datetime'
  | 'phone' // 座机号码
  | 'telephone' // 国内固话+国内手机号(不含400 800电话)
  | 'license_code' // 企业统一信用代码
  | 'bank_code' // 银行账号 (非严谨)
  | 'amount' // Amount
  | 'chinese' // Chinese
  | `length:${number}` // static length
  | `length:${number},${number}` // length range
  | `regexp:${string}` // RegExp
  | `between:${number},${number}` // Number range
  | `gt:${number}` // 大于
  | `>:${number}` // 大于
  | `lt:${number}` // 小于
  | `<:${number}` // 小于
  | `gte:${number}` // 大于等于
  | `>=:${number}` // 大于等于
  | `lte:${number}` // 小于等于
  | `<=:${number}` // 小于等于
  | Required<FormItemRule>['validator'] // 自定义验证函数