feat: support custom component

re chenquincy#5

Author: chenquincy

README.md

@@ -83,16 +83,15 @@ export default {
 - Support **multi-level form** for `Object `/ `Array` / `Hashmap` 
 - Support data **validation**
 - **Multi-Languages** support
+- Support **custom component**
 
 ## Todo
 
 **vue-dynamic-form-component** can do more. There are a few things that it currently doesn't support but are planned:
 
 - [x] Custom component props
-- [ ] Custom component event
-- [ ] Support more component
-  - [x] textarea
-  - [ ] file upload
+- [x] Custom component event
+- [x] Custom component
 - [ ] Custom theme
 - [ ] Value change event
 

docs/.vuepress/components/custom-component.vue

@@ -0,0 +1,35 @@
+<template>
+  <dynamic-form
+    v-model="data"
+    :descriptors="descriptors">
+  </dynamic-form>
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      descriptors: {
+        image: {
+          type: 'url',
+          required: true,
+          message: 'please upload an image',
+          component: {
+            name: 'el-upload',
+            children: [
+              { name: 'el-button', children: 'click to upload', props: { type: 'primary', plain: true, size: 'small' } }
+            ],
+            props: {
+              action: 'https://jsonplaceholder.typicode.com/posts/',
+              onError: function (error, file, fileList) {
+                console.log('upload error ==> ', error)
+              }
+            }
+          }
+        }
+      },
+      data: {}
+    }
+  }
+}
+</script>

docs/.vuepress/components/home-demo.vue

@@ -2,7 +2,8 @@
   <dynamic-form
     ref="dynamic-form"
     v-model="data"
-    :descriptors="descriptors">
+    :descriptors="descriptors"
+    :showOuterError="false">
     <template slot="operations">
       <el-button @click="reset">Reset</el-button>
       <el-button type="primary" @click="validate" plain>Validate</el-button>

docs/.vuepress/config.js

@@ -6,12 +6,12 @@ module.exports = {
     '/': {
       lang: 'en-US',
       title: 'vue-dynamic-form-component',
-      description: 'Vue dynamic nested form component. Support nested Object/Hashmap/Array.'
+      description: 'Vue dynamic nested form component. Support nested Object/Hashmap/Array. Can custom component yourself.'
     },
     '/zh/': {
       lang: 'zh-CN',
       title: 'vue-dynamic-form-component',
-      description: 'Vue动态嵌套表单组件，支持嵌套对象/Hashmap/数组'
+      description: 'Vue动态嵌套表单组件，支持嵌套对象/Hashmap/数组, 可自定义表单组件'
     }
   },
   themeConfig: {

docs/README.md

@@ -9,7 +9,7 @@ meta:
   - name: google-site-verification
     content: -lX8u-MYYDkf5y6QhZWJqZoDxVkmAu004XwR3ynRwFg
 features:
-- title: Generate form by descriptors
+- title: Generate form by descriptors Or custom component
   details: Write only data's descriptor(extend from async-validate), then automatically generate form(use element-ui)
 - title: Support almost all data type with validation
   details: Support almost all data type and normal data validation(email, url, ... etc)

docs/api/descriptors/README.md

@@ -9,13 +9,18 @@
 ## descriptor
 
 ::: tip Warm Prompt
-**descriptor** can be `object` or `array`, but the `fields`, `defaultFields`, `label`, `placeholder`, `hidden`, `disabled`, `options`, `autocomplete`  props should be brother props with `type`. In addition, there is only one object include `type` prop in array.
+**descriptor** can be `object` or `array`, but the `fields`, `defaultFields`, `label`, `hidden`, `disabled`, `options`, `component`  props should be brother props with `type`. In addition, there is only one object include `type` prop in array.
 :::
 
 ### type
 
 `string`, declare the type of data's field, include common data type.
 
+::: warning 注意
+
+Note that [descriptor.component.name](/zh/api/descriptors/#props) has higher priority, the follow rules are invalid if `descriptor.component.name` is not null.
+:::
+
 | Value     | Description                                                  | Component           |
 | --------- | ------------------------------------------------------------ | ------------------- |
 | `string`  | Must be a string                                             | `el-input`          |
@@ -36,10 +41,6 @@
 
 `string`, field's label in form, should be declared with `type` in the same object.
 
-### props
-
-`object` type, it will be the value of input component's `v-bind` prop(input component refer to [descriptor.type](/api/descriptors/#type)). You can custom the component with this option, there are some common prop like: `placeholder`, `disabled`, ... , etc. Other props of component refer to [element-ui](https://element.faas.ele.me/#/en-US/component/installation).
-
 ### hidden
 
 `boolean` , whether hidden the input component of value, should be declared with `type` in the same object. Note that the hidden value still will be validated while validating.
@@ -206,3 +207,43 @@ const descriptors = {
 }
 ```
 
+### component
+
+Provided for user to custom the component easily, it can custom the component's content, props and events.
+
+``` js
+// component demo
+{
+  name: 'el-button',
+  props: {
+    type: 'primary',
+    size: 'small'
+  },
+  events: {
+    click () {
+      console.log('button click')
+    }
+  }
+}
+```
+
+#### name
+
+`string` type, custom to use which element or component.
+
+#### props
+
+`object` type, it will be the value of input component's `v-bind` prop(input component refer to [descriptor.type](/api/descriptors/#type)). You can custom the component props with this option, there are some common props like: `placeholder`, `disabled`, ... , etc. Other props of component refer to [element-ui](https://element.faas.ele.me/#/en-US/component/installation). Note that it will be the  value of the custom component's `v-bind` prop, if `component.name` is not null.
+
+#### events
+
+`object` type, it will be the value of input component's `v-on` prop(input component refer to [descriptor.type](/api/descriptors/#type)). You can custom the component props with this option, there are some common prop like: `placeholder`, `disabled`, ... , etc. Other props of component refer to [element-ui](https://element.faas.ele.me/#/en-US/component/installation). Note that it will be the  value of the custom component's `v-on` prop, if `component.name` is not null.
+
+#### children
+
+`children` is used to custom the content of component. It has two types:
+
+- `string` : the content is plain text. It will be inserted with `span` element
+- `array[component | string]` : the content has more than one element, the array item has two types:
+  - `component` : same structure with [component](/api/descriptors/#component) 
+  - `string` : the item is plain text. It will be inserted with `span` element

docs/getting-started/README.md

@@ -125,6 +125,19 @@ Special prop `label`, `fields`, `defaultField` , ...etc should be used with `typ
 
 <<<@/docs/.vuepress/components/custom-validator.vue
 
+### Custom Component
+
+::: tip Warm Prompt
+
+To custom component, you should ensure `version >= 2.5.0`
+:::
+
+**vue-dynamic-form-component** has components for common data type inside, so you don't need to custom the component generally. But sometimes, we need to custom the component, such as upload a file. To meet these scenes, I provide a way to custom the component. Usage like this:
+
+<code-demo name="custom-component" lang="en_US"></code-demo>
+
+<<<@/docs/.vuepress/components/custom-component.vue
+
 ### Form Operations
 
 **vue-dynamic-form-component** provides some common methods to operate form, you can use them with `operations` slot.

docs/guide/README.md

@@ -9,6 +9,7 @@
 - Support **nested form** for `Object `/ `Array` / `Hashmap` 
 - Support data **validation**
 - **Multi-Languages** support
+- Support **custom component**
 
 ## Question
 

docs/zh/README.md

@@ -7,7 +7,7 @@ meta:
 - name: keywords
   content: vue 动态 嵌套 表单 多级 组件  vue-dynamic-form vue-dynamic-form-component
 features:
-- title: 使用descriptors生成表单
+- title: 使用descriptors生成表单或自定义组件
   details: 只需要提供目标数据的descriptor(基于async-validator扩展)，就可以自动生成对应的表单元素(基于element-ui)
 - title: 支持绝大部分数据类型及其校验
   details: 支持绝大部分数据类型、常见类型校验（如：email、url等）

docs/zh/api/descriptors/README.md

@@ -7,13 +7,17 @@
 ## descriptor
 
 ::: warning 注意
-**descriptor** 可以是对象或者数组，但是，当 **descriptor** 为数组时，与数据类型定义有关的属性（ `fields`、`defaultFields`）和扩展属性（`label`、`placeholder`、`hidden`、`disabled`、`options`、`autocomplete`） 需和 `type` 属性在同一对象中，并且数组中有且仅有一个包含 `type` 属性的对象。
+**descriptor** 可以是对象或者数组，但是，当 **descriptor** 为数组时，与数据类型定义有关的属性（ `fields`、`defaultFields`）和扩展属性（`label`、`hidden`、`disabled`、`options`、`component`） 需和 `type` 属性在同一对象中，并且数组中有且仅有一个包含 `type` 属性的对象。
 :::
 
 ### type
 
 `string` 类型，表示字段类型，包含常见的数据类型
 
+::: warning 注意
+[descriptor.component.name](/zh/api/descriptors/#props) 优先级更高，当 `descriptor.component.name` 不为空时，以下规则不生效
+:::
+
 | 值        | 说明                                                         | 对应组件            |
 | --------- | ------------------------------------------------------------ | ------------------- |
 | `string`  | 字符串类型                                                   | `el-input`          |
@@ -34,10 +38,6 @@
 
 `string` 类型，表单中对应字段的label值，需和 `type` 在同一个对象中
 
-### props
-
-`object` 类型，通过 `v-bind` 绑定到对应的 element-ui 输入组件（对应组件查阅 [descriptor.type](/zh/api/descriptors/#type)），可以通过该选项进行一些自定义操作，常见的属性有：`placeholder`、`disabled` 等，其他属性请查阅 [element-ui](https://element.faas.ele.me/#/zh-CN/component/installation) 对应组件文档
-
 ### hidden
 
 `boolean` 类型，是否隐藏对应的输入组件，需和 `type` 在同一个对象中。需要注意的是，触发校验时，被隐藏的组件值依然会进行校验。
@@ -187,16 +187,56 @@ const descriptors = {
     { type: 'string', required: true },
     {
       validator: function (rule, value, callback) {
-      	if (value.length < 5) {
-    			return callback(new Error('name should logger than 5'))
-    		}
+        if (value.length < 5) {
+          return callback(new Error('name should logger than 5'))
+        }
         if (value.indexOf('/%$') !== -1) {
           return callback(new Error('name can not include /%$'))
         }
-				return callback()
-    	}
+        return callback()
+      }
     }
   ]
 }
 ```
 
+### component
+
+为了方便使用者自定义组件提供的选项，可以自定义组件内容、属性和事件。
+
+``` js
+// component 示例
+{
+  name: 'el-button',
+  props: {
+    type: 'primary',
+    size: 'small'
+  },
+  events: {
+    click () {
+      console.log('button click')
+    }
+  }
+}
+```
+
+#### name
+
+`string` 类型，自定义组件名或元素名
+
+#### props
+
+`object` 类型，当 `component.name` 为空时，通过 `v-bind` 绑定到对应的组件（对应组件查阅 [descriptor.type](/zh/api/descriptors/#type)），可以通过该选项进行属性自定义，常见的属性有：`placeholder`、`disabled` 等，其他对应组件属性请查阅 [element-ui](https://element.faas.ele.me/#/zh-CN/component/installation) 对应组件文档；当 `component.name` 不为空时，通过 `v-bind` 绑定到声明的组件上。
+
+#### events
+
+`object` 类型，当 `component.name` 为空时，通过 `v-on` 绑定到对应的组件（对应组件查阅 [descriptor.type](/zh/api/descriptors/#type)），可以通过该选项进行事件自定义，例如：`click`、`focus` 等，其他对应组件事件请查阅 [element-ui](https://element.faas.ele.me/#/zh-CN/component/installation) 对应组件文档；当 `component.name` 不为空时，通过 `v-on` 绑定到声明的组件上。
+
+#### children
+
+`children` 用于自定义组件内容，它有两种类型：
+
+- `string` ：表示内容为纯文本，使用 `span` 标签插入
+- `array[component | string]` : 表示组件内容有多个元素，数组元素有两种类型：
+  - `component` : 结构和 [component](/zh/api/descriptors/#component) 相同
+  - `string` ： 表示纯文本元素，使用 `span` 标签插入