Merge branch 'dev'

levy · levy · commit d8b578c7bc31 · 2019-07-09T17:42:52.000+08:00
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -55,6 +55,17 @@
         "doc",
         "example"
       ]
+    },
+    {
+      "login": "colmugx",
+      "name": "ColMugX",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/21327913?v=4",
+      "profile": "https://colmugx.github.io",
+      "contributions": [
+        "code",
+        "test",
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7
diff --git a/README-en.md b/README-en.md
@@ -37,6 +37,7 @@ In our daily development, there are lots page with form, and usually the form st
 ## Demo
 
 * [Doc and online demo](https://femessage.github.io/el-form-renderer/)
+* [custom component guide](https://github.com/femessage/el-form-renderer/blob/master/docs/guide-custom-component.md)
 
 **[⬆Back to Top](#table-of-contents)**
 
diff --git a/README.md b/README.md
@@ -44,6 +44,7 @@
 ## Demo
 
 * [doc and online demo](https://femessage.github.io/el-form-renderer/)
+* [自定义组件接入指南](https://github.com/femessage/el-form-renderer/blob/master/docs/guide-custom-component.md)
 
 **[⬆ Back to Top](#table-of-contents)**
 
@@ -94,7 +95,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 
 <!-- prettier-ignore -->
-<table><tr><td align="center"><a href="https://github.com/Alvin-Liu"><img src="https://avatars0.githubusercontent.com/u/11909145?v=4" width="100px;" alt="Alvin"/><br /><sub><b>Alvin</b></sub></a><br /><a href="https://github.com/FEMessage/el-form-renderer/commits?author=Alvin-Liu" title="Code">💻</a> <a href="#review-Alvin-Liu" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/FEMessage/el-form-renderer/issues?q=author%3AAlvin-Liu" title="Bug reports">🐛</a> <a href="#blog-Alvin-Liu" title="Blogposts">📝</a> <a href="#ideas-Alvin-Liu" title="Ideas, Planning, & Feedback">🤔</a></td><td align="center"><a href="http://levy.work"><img src="https://avatars3.githubusercontent.com/u/9384365?v=4" width="100px;" alt="levy"/><br /><sub><b>levy</b></sub></a><br /><a href="#review-levy9527" title="Reviewed Pull Requests">👀</a> <a href="#infra-levy9527" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#ideas-levy9527" title="Ideas, Planning, & Feedback">🤔</a></td><td align="center"><a href="https://evila.me"><img src="https://avatars3.githubusercontent.com/u/19513289?v=4" width="100px;" alt="EVILLT"/><br /><sub><b>EVILLT</b></sub></a><br /><a href="https://github.com/FEMessage/el-form-renderer/commits?author=evillt" title="Code">💻</a> <a href="https://github.com/FEMessage/el-form-renderer/issues?q=author%3Aevillt" title="Bug reports">🐛</a> <a href="#blog-evillt" title="Blogposts">📝</a> <a href="#ideas-evillt" title="Ideas, Planning, & Feedback">🤔</a></td><td align="center"><a href="https://donaldshen.github.io/portfolio"><img src="https://avatars3.githubusercontent.com/u/19591950?v=4" width="100px;" alt="Donald Shen"/><br /><sub><b>Donald Shen</b></sub></a><br /><a href="https://github.com/FEMessage/el-form-renderer/commits?author=donaldshen" title="Documentation">📖</a> <a href="#example-donaldshen" title="Examples">💡</a></td></tr></table>
+<table><tr><td align="center"><a href="https://github.com/Alvin-Liu"><img src="https://avatars0.githubusercontent.com/u/11909145?v=4" width="100px;" alt="Alvin"/><br /><sub><b>Alvin</b></sub></a><br /><a href="https://github.com/FEMessage/el-form-renderer/commits?author=Alvin-Liu" title="Code">💻</a> <a href="#review-Alvin-Liu" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/FEMessage/el-form-renderer/issues?q=author%3AAlvin-Liu" title="Bug reports">🐛</a> <a href="#blog-Alvin-Liu" title="Blogposts">📝</a> <a href="#ideas-Alvin-Liu" title="Ideas, Planning, & Feedback">🤔</a></td><td align="center"><a href="http://levy.work"><img src="https://avatars3.githubusercontent.com/u/9384365?v=4" width="100px;" alt="levy"/><br /><sub><b>levy</b></sub></a><br /><a href="#review-levy9527" title="Reviewed Pull Requests">👀</a> <a href="#infra-levy9527" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#ideas-levy9527" title="Ideas, Planning, & Feedback">🤔</a></td><td align="center"><a href="https://evila.me"><img src="https://avatars3.githubusercontent.com/u/19513289?v=4" width="100px;" alt="EVILLT"/><br /><sub><b>EVILLT</b></sub></a><br /><a href="https://github.com/FEMessage/el-form-renderer/commits?author=evillt" title="Code">💻</a> <a href="https://github.com/FEMessage/el-form-renderer/issues?q=author%3Aevillt" title="Bug reports">🐛</a> <a href="#blog-evillt" title="Blogposts">📝</a> <a href="#ideas-evillt" title="Ideas, Planning, & Feedback">🤔</a></td><td align="center"><a href="https://donaldshen.github.io/portfolio"><img src="https://avatars3.githubusercontent.com/u/19591950?v=4" width="100px;" alt="Donald Shen"/><br /><sub><b>Donald Shen</b></sub></a><br /><a href="https://github.com/FEMessage/el-form-renderer/commits?author=donaldshen" title="Documentation">📖</a> <a href="#example-donaldshen" title="Examples">💡</a></td><td align="center"><a href="https://colmugx.github.io"><img src="https://avatars1.githubusercontent.com/u/21327913?v=4" width="100px;" alt="ColMugX"/><br /><sub><b>ColMugX</b></sub></a><br /><a href="https://github.com/FEMessage/el-form-renderer/commits?author=colmugx" title="Code">💻</a> <a href="https://github.com/FEMessage/el-form-renderer/commits?author=colmugx" title="Tests">⚠️</a> <a href="https://github.com/FEMessage/el-form-renderer/commits?author=colmugx" title="Documentation">📖</a></td></tr></table>
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
diff --git a/docs/guide-custom-component.md b/docs/guide-custom-component.md
@@ -0,0 +1,76 @@
+# 自定义组件接入指南
+
+## 前言
+
+[el-form-renderer](https://github.com/femessage/el-form-renderer) 的 `type` 有限, 默认只能渲染普通的表单项, 假如现在要渲染一个上传组件, `type` 就不够用了, 那怎么办呢? 这时候 component 选项就派上用场了
+
+本文将介绍如何开发符合 [el-form-renderer](https://github.com/femessage/el-form-renderer) 接入标准的自定义组件, 实现对自定义组件的渲染
+
+## 接入标准
+
+自定义组件接入的关键是在组件内部实现 v-model
+
+[el-form-renderer](https://github.com/femessage/el-form-renderer) 对 v-model 的要求是:
+
+- 有一个 props 为 value
+- 对外触发 input 事件
+
+下面是一个简单的例子
+
+```html
+<!-- 自定义组件 my-input -->
+<input :value="value" @input="onInput">
+
+<script>
+export default {
+  props: {
+    value: String
+  },
+  methods: {
+    onInput(val) {
+      this.$emit('input', 'my-input: ' + val)
+    }
+  }
+}
+</script>
+```
+
+则可以用 component 属性让 [el-form-renderer](https://github.com/femessage/el-form-renderer) 渲染此自定义组件
+
+```html
+<template>
+  <el-form-renderer :content="content"/>
+</template>
+
+<script>
+import MyInput from '@/components/my-input.vue'
+export default {
+  data() {
+    return {
+      content: [
+        {
+          component: MyInput,
+          id: 'myInput',
+          label: 'label'
+        }
+      ]
+    }
+  },
+}
+</script>
+```
+
+## 实际案例
+
+目前团队对常见的表单扩展组件都按 [el-form-renderer](https://github.com/femessage/el-form-renderer) 的标准实现了 v-model, 因此都可以不写 template, 由 [el-form-renderer](https://github.com/femessage/el-form-renderer) 实现数据驱动渲染
+
+- 上传组件 [https://github.com/FEMessage/upload-to-ali](https://github.com/FEMessage/upload-to-ali)
+- 富文本编辑器 [https://github.com/FEMessage/v-editor](https://github.com/FEMessage/v-editor)
+- 省市区选择器 [https://github.com/FEMessage/el-select-area](https://github.com/FEMessage/el-select-area)
+- 范围输入框 [https://github.com/FEMessage/el-number-range](https://github.com/FEMessage/el-number-range)
+- 版本号输入框 [https://github.com/FEMessage/el-semver-input](https://github.com/FEMessage/el-semver-input)
+
+## 拓展阅读
+
+- [v-model基础](https://cn.vuejs.org/v2/guide/forms.html#%E5%9F%BA%E7%A1%80%E7%94%A8%E6%B3%95)
+- [在组件上使用v-model](https://cn.vuejs.org/v2/guide/components.html#%E5%9C%A8%E7%BB%84%E4%BB%B6%E4%B8%8A%E4%BD%BF%E7%94%A8-v-model)
diff --git a/docs/hidden.md b/docs/hidden.md
@@ -0,0 +1,51 @@
+可以对表单项进行隐藏
+
+```vue
+<template>
+  <el-form-renderer ref="form" :content="content" />
+</template>
+
+<script>
+export default {
+  name: 'at-change',
+  data() {
+    return {
+      content: [
+        {
+          type: 'select',
+          id: 'hobby',
+          label: '爱好',
+          options: [
+            {
+              label: '足球',
+              value: 'football'
+            },
+            {
+              label: '篮球',
+              value: 'basketball'
+            }
+          ]
+        },
+        {
+          label: '原因',
+          type: 'input',
+          id: 'reason',
+          el: {
+            placeholder: '喜欢的原因？'
+          }
+        },
+        {
+          label: '偶像',
+          type: 'input',
+          id: 'idol',
+          el: {
+            placeholder: '您最喜欢的篮球明星？'
+          },
+          hidden: form => form.hobby !== 'basketball' // 通过 hidden 控制显示状态
+        },
+      ]
+    }
+  }
+}
+</script>
+```
diff --git a/src/el-form-renderer.md b/src/el-form-renderer.md
@@ -51,12 +51,20 @@ interface Content {
   default?: any // 默认值，可选
 
   /**
+   * @deprecated
+   *
    * 传入一个对象，key为属性路径，value为指定值，校验通过则显示该表单项
    * 比如当前表单项值为{a: {b: 1}}，enableWhen={'a.b': 1}， 则校验通过
    * 也可以只传入属性路径，此时该属性非空就通过校验
    */
   enableWhen?: object | string
 
+  /**
+   * 传入一个方法，并返回 boolean，返回 true 时则隐藏该表单项
+   * form 为当前 form 的值，item 为当前表单项的定义
+   */
+  hidden?: (form: Object, item: Content) => boolean
+
   /**
    * 具有选择功能的原子表单可用此定义可选项
    * 例如: select, radio-group, radio-button, checkbox-group, checkbox-button
diff --git a/src/mixins/enable-when.js b/src/mixins/enable-when.js
diff --git a/src/mixins/hidden.js b/src/mixins/hidden.js
@@ -0,0 +1,17 @@
+export default {
+  methods: {
+    /**
+     * 处理 hidden
+     *
+     */
+    getHiddenStatus(hidden = this.data && this.data.hidden) {
+      if (hidden) {
+        const newData = {...this.data}
+        delete newData.hidden
+
+        // 给 hidden 方法传递 form 值与当前 item 信息
+        return hidden(this.value, newData)
+      }
+    }
+  }
+}
diff --git a/src/mixins/package-option.js b/src/mixins/package-option.js
diff --git a/src/render-form-item.js b/src/render-form-item.js
@@ -1,5 +1,6 @@
-import mixinOptionExtensions from './mixin-package-option'
-import mixinEnableWhen from './mixin-enable-when'
+import mixinOptionExtensions from './mixins/package-option'
+import mixinEnableWhen from './mixins/enable-when'
+import mixinHidden from './mixins/hidden'
 import {toCamelCase, isObject} from './utils'
 
 function validator(data) {
@@ -13,7 +14,7 @@ function validator(data) {
 }
 
 export default {
-  mixins: [mixinOptionExtensions, mixinEnableWhen],
+  mixins: [mixinOptionExtensions, mixinEnableWhen, mixinHidden],
   props: {
     data: Object,
     prop: {
@@ -30,7 +31,9 @@ export default {
   computed: {
     // 是否显示
     _show() {
-      return this.getEnableWhenSatatus()
+      // 当存在 hidden 时优先响应
+      const isHidden = this.getHiddenStatus()
+      return isHidden !== undefined ? !isHidden : this.getEnableWhenSatatus()
     }
   },
   render(h) {
diff --git a/styleguide.config.js b/styleguide.config.js
@@ -2,36 +2,47 @@ const {VueLoaderPlugin} = require('vue-loader')
 const path = require('path')
 const glob = require('glob')
 
-const demos = glob.sync('docs/!(basic).md')
-const demoSections = [
-  {
-    name: 'basic',
-    content: 'docs/basic.md'
-  }
-].concat(
-  demos.map(filePath => ({
-    name: path.basename(filePath, '.md'),
-    content: filePath
-  }))
-)
-
-module.exports = {
-  styleguideDir: 'docs',
-  pagePerSection: true,
-  ribbon: {
-    url: 'https://github.com/FEMessage/el-form-renderer'
-  },
-  sections: [
+const sections = (() => {
+  const docs = glob
+    .sync('docs/*.md')
+    .map(p => ({name: path.basename(p, '.md'), content: p}))
+  const demos = []
+  let faq = '' // 约定至多只有一个faq.md
+  const guides = []
+  docs.forEach(d => {
+    if (/^faq$/.test(d.name)) {
+      faq = d
+    } else if (/^guide-/.test(d.name)) {
+      guides.push(d)
+    } else {
+      demos.push(d)
+    }
+  })
+  return [
     {
       name: 'Components',
       components: 'src/el-form-renderer.js',
       usageMode: 'expand'
     },
     {
       name: 'Demo',
-      sections: demoSections
+      sections: demos
+    },
+    ...(faq ? [faq] : []),
+    {
+      name: 'Guide',
+      sections: guides
     }
-  ],
+  ]
+})()
+
+module.exports = {
+  styleguideDir: 'docs',
+  pagePerSection: true,
+  ribbon: {
+    url: 'https://github.com/FEMessage/el-form-renderer'
+  },
+  sections,
   require: ['./styleguide/element.js', './styleguide/upload-to-ali.js'],
   webpackConfig: {
     module: {
diff --git a/test/mixin-hidden.test.js b/test/mixin-hidden.test.js
@@ -0,0 +1,82 @@
+import Vue from 'vue'
+import renderFormItem from '../src/render-form-item'
+
+const testOrigin = {
+  type: 'input',
+  id: 'name'
+}
+
+const testValue = {
+  name: 'hello'
+}
+
+describe('mixin-hidden.js', () => {
+  let Constructor
+  beforeEach(() => {
+    Constructor = Vue.extend(renderFormItem)
+  })
+
+  describe('enableWhen 与 hidden', () => {
+    test('没有使用 enableWhen 与 hidden', () => {
+      const vm = new Constructor({
+        propsData: {data: testOrigin, value: testValue}
+      })
+
+      expect(vm._show).toBe(true)
+    })
+
+    test('使用 enableWhen，不被 hidden 干扰', () => {
+      const data = {...testOrigin, enableWhen: {name: false}}
+      const vm = new Constructor({propsData: {data, value: testValue}})
+
+      expect(vm.getHiddenStatus()).toBe(undefined)
+      expect(vm._show).toBe(false)
+    })
+
+    test('同时使用 hidden 与 enableWhen，仅响应 hidden', () => {
+      const data = {
+        ...testOrigin,
+        hidden: () => false,
+        enableWhen: {name: false}
+      }
+      const vm = new Constructor({propsData: {data, value: testValue}})
+
+      expect(vm.getHiddenStatus()).toBe(false)
+      expect(vm._show).toBe(true)
+    })
+  })
+
+  describe('使用 hidden', () => {
+    test('使用 hidden，返回 true，不显示', () => {
+      const data = {...testOrigin, hidden: () => true}
+      const vm = new Constructor({propsData: {data, value: testValue}})
+
+      expect(vm._show).toBe(false)
+    })
+
+    test('使用 hidden，返回 false，显示', () => {
+      const data = {...testOrigin, hidden: () => false}
+      const vm = new Constructor({propsData: {data, value: testValue}})
+
+      expect(vm._show).toBe(true)
+    })
+  })
+
+  describe('hidden 可以使用 form 与当前 item 值', () => {
+    test('hidden 可以获取 form 值', () => {
+      const data = {...testOrigin, hidden: form => form.name === 'hello'}
+      const vm = new Constructor({propsData: {data, value: testValue}})
+
+      expect(vm.getHiddenStatus()).toBe(true)
+      expect(vm._show).toBe(false)
+    })
+
+    test('hidden 可以获取 item 信息', () => {
+      const data = {...testOrigin, hidden: (_, item) => item.id === 'name'}
+      const vm = new Constructor({propsData: {data, value: testValue}})
+
+      expect(vm.getHiddenStatus()).toBe(true)
+      expect(vm._show).toBe(false)
+    })
+  })
+})
