docs: update doc for form and uploader

Change-Id: I7f40bc634ebf917ab9b154ad656f3751c5e508aa

Author: xiaodemen

one/docs/components/field.md

@@ -27,6 +27,7 @@
 | ``abstract`` | `boolean=` | `false` | 抽象表单项，抽象的项目没有标题，也不会展示校验信息。 |
 | ``withhold-validity`` | `boolean=` | `false` | 当设置为 `true` 时，该表单项内容中的输入组件（如 `veui-input` ）不会自动绑定校验事件，也不会自动进入 `invalid` 状态，使用方可以通过 `default` 插槽来自行定制。 |
 | ``validity-display`` | `'normal' | 'simple'` | `'simple'` | [^validity-display] |
+| ``required`` | `boolean` | `false` | 用来在没有 `required` 规则时是否显示必要性星号提示。 |
 
 ^^^ui
 预设样式。
@@ -76,16 +77,17 @@ let minLengthRule = {
 ^^^
 
 ^^^rules
-表单项校验规则，同步的单值校验。对于 `Array` 类型，项目的类型为 `{triggers, name, message, value, priority}`。
+表单项校验规则，同步的单值校验。对于 `Array` 类型，项目的类型为 `{triggers, name, message, value, validate, priority}`。
 
 +++字段详情
 | 名称 | 类型 | 描述 |
 | -- | -- | -- |
-| `triggers` | `string` | 触发校验的事件名称集合，逗号分隔。 |
+| `triggers` | `string` | 触发校验的事件名称集合，逗号分隔，支持 `<fieldName>:<eventName>` 表示当 `fieldName` 字段发生 `eventName` 事件时触发校验，可以参考示例[`内联规则校验`](./form#内联规则校验)。 |
 | `name` | `string` | 规则名称。 |
 | `value` | `*` | 规则要匹配的值。`boolean` 类型的规则，默认为 `true`。 |
 | `message` | `string | function` | [^message] |
 | `priority` | `number` | 规则优先级，可以覆盖规则默认优先级。 |
+| `validate` | `(value: unknown, ruleValue: unknown) => boolean` | 内联校验器，用来直接编写验证逻辑，可以参考示例[`内联规则校验`](./form#内联规则校验)。 |
 +++
 
 +++内置规则

one/docs/components/form.md

@@ -28,14 +28,14 @@
 
 [[ demo src="/demo/form/help.vue" ]]
 
-### 校验
-
-[[ demo src="/demo/form/validate.vue" ]]
-
 ### 规则校验
 
 [[ demo src="/demo/form/rule.vue" ]]
 
+### 内联规则校验
+
+[[ demo src="/demo/form/inline-rule.vue" ]]
+
 ### 异步联合校验
 
 [[ demo src="/demo/form/validator.vue" ]]
@@ -81,7 +81,7 @@
 | -- | -- | -- |
 | `fields` | `Array` | 对应 `Field` 的 `field` 描述的集合。事件会绑定到对应 `Field` 中的输入组件上。 |
 | `validate` | `function` | 自定义校验函数，传入参数为 `(data[fields[0]], data[fields[1]], ...)`，`data` 为表单 [`data`](#props-data) 属性值的引用。返回 `undefined` / `true` 代表校验成功，返回 `{[field]: message, ...}` 表示校验失败信息，详见[表单 › 表单校验逻辑](#表单校验逻辑)。 |
-| `triggers` | `string | Array<string>` | 事件名称集合。 |
+| `triggers` | `string | Array<string>` | 事件名称集合, 支持 `<fieldName>:<eventName>` 表示当 `fieldName` 字段发生 `eventName` 事件时触发校验。 |
 +++
 
 
@@ -92,6 +92,7 @@
 | `['a','b','c']` | `['change', 'blur,input,xxx', 'submit']` | a(change), b(blur,input,xxx), c(submit) |
 | `['a','b','c']` | `'blur'` | a(blur), b(submit), c(submit) |
 | `['a','b','c']` | `'blur,input'` | a(blur,input), b(blur,input), c(blur,input) |
+| `['a']` | `'blur,b:input'` | a(blur,b:input) |
 +++
 ^^^
 

one/docs/components/uploader.md

@@ -50,6 +50,17 @@
 
 [[ demo src="/demo/uploader/entries.vue" ]]
 
+### 自定义选择文件
+
+设置 [`pick`](#props-pick) 属性来自定义选择文件。
+
+[[ demo src="/demo/uploader/pick.vue" ]]
+
+### 帮助文案
+
+设置 [`help`](#props-help) 属性或[`help`](#slots-help) 插槽来指定帮助文案。
+
+[[ demo src="/demo/uploader/help.vue" ]]
 
 ## API
 
@@ -82,7 +93,7 @@
 | ``controls`` | `function(Object, Array<Object>): Array<Object>` | - | [^controls] |
 | ``multiple`` | `boolean` | `false` | 上传多个文件，当 `max-count` 是 `1`，`multiple` 是 `true`，那么 `value` 也是数组。 |
 | ``entries`` | `function(Array<Object>): Array<Object>` | - | [^entries] |
-| ``pick`` | `function(number): Promise<Object>` | - | [^pick] |
+| ``pick`` | `function({remainingCount: number}): Promise<Object>` | - | [^pick] |
 | ``after-pick`` | `function(Array<Object>): void` | - | 选择文件之后的回调。 |
 | ``sortable`` | `boolean` | `false` | 文件列表是否可以排序。 |
 | ``preview-options`` | `object` | `{wrap: true, indicator: 'number'}` | 传递给 [`Lightbox`](./lightbox) 的预览选项。 |
@@ -168,6 +179,7 @@
 | `name` | `string=` | 文件的名称。`success` 为 `true` 时必须。 |
 | `src` | `string=` | 文件的地址。`success` 为 `true` 时必须。 |
 | `message` | `string=` | 上传失败时的出错信息。`success` 为 `false` 时必须。 |
+| `preview` | `boolean` | 上传失败时，是否预览失败的上传项。 |
 
 还可以给返回结果加上其它自定义的属性，这些自定义属性会被包含在 [`value`](#props-value) 以及 [`change`](#events-change)、[`success`](#events-success)、[`failure`](#events-failure)、[`remove`](#events-remove)、[`progress`](#events-progress) 事件的回调参数 `file` 中 。可进行[全局统一配置](#configs-uploader-convert-response)。
 +++
@@ -201,7 +213,7 @@
 自定义选择文件逻辑， 返回的文件会被上传。
 
 ```ts
-function picker() : Promise<PickedFile | PickedFile[]>
+function picker({remainingCount: number}) : Promise<PickedFile | PickedFile[]>
 
 type PickedFile = {
   name: string
@@ -255,6 +267,7 @@ type PickedFile = {
 | -- | -- | -- |
 | `valid` | `boolean` | 是否通过校验。 |
 | `message` | `string=` | `valid` 为 `false` 时的错误提示信息。 |
+| `preview` | `boolean` | 当校验失败时，是否预览失败的上传项。 |
 
 支持异步校验，返回值可以是一个 resolve 上述返回结果的 `Promise`。
 

one/docs/demo/form/inline-rule.vue

@@ -0,0 +1,83 @@
+<template>
+<article class="veui-form-demo">
+  <veui-form
+    ref="form"
+    :data="data"
+  >
+    <veui-field
+      label="密码："
+      name="password"
+      :rules="[
+        { name: 'required', triggers: 'input,blur' },
+        { name: 'minLength', value: '6', triggers: 'blur' }
+      ]"
+    >
+      <veui-input
+        v-model="data.password"
+        type="password"
+      />
+    </veui-field>
+
+    <veui-field
+      label="确认密码："
+      name="password2"
+      :rules="p2Rules"
+    >
+      <veui-input
+        v-model="data.password2"
+        type="password"
+      />
+    </veui-field>
+  </veui-form>
+</article>
+</template>
+
+<script>
+import {
+  Form,
+  Field,
+  Input
+} from 'veui'
+
+export default {
+  name: 'demo-form',
+  components: {
+    'veui-input': Input,
+    'veui-form': Form,
+    'veui-field': Field
+  },
+  data () {
+    return {
+      data: {
+        password: '',
+        password2: ''
+      }
+    }
+  },
+  computed: {
+    p2Rules () {
+      return [
+        { name: 'required', triggers: 'input,blur' },
+        {
+          name: 'prefix',
+          value: this.data.password,
+          triggers: 'input',
+          message: '两次输入的密码不一致',
+          validate (val, ruleValue) {
+            return (ruleValue || '').indexOf(val || '') === 0
+          }
+        },
+        {
+          name: 'same',
+          value: this.data.password,
+          triggers: 'change,password:input',
+          message: '两次输入的密码不一致',
+          validate (val, ruleValue) {
+            return !val || (ruleValue || '') === val
+          }
+        }
+      ]
+    }
+  }
+}
+</script>

one/docs/demo/form/validator.vue

@@ -43,12 +43,14 @@ import {
   Fieldset,
   Field,
   Input,
-  Button
+  Button,
+  Span
 } from 'veui'
 
 export default {
   name: 'demo-form',
   components: {
+    'veui-span': Span,
     'veui-input': Input,
     'veui-button': Button,
     'veui-form': Form,

one/docs/demo/uploader/help.vue

@@ -0,0 +1,68 @@
+<template>
+<article>
+  <section>
+    <div>
+      helpPosition:
+      <veui-radio-button-group
+        v-model="helpPosition"
+        ui="s"
+        :items="availableHelpPositions"
+      />
+    </div>
+    <veui-uploader
+      v-model="files"
+      :help-position="helpPosition"
+      :help="'help text'"
+      action="https://app.fakejson.com/q/ELymQ7xh?token=AWFkjMICPSAB_bO_z-Lnog"
+    />
+    <veui-uploader
+      v-model="files"
+      :help-position="helpPosition"
+      action="https://app.fakejson.com/q/ELymQ7xh?token=AWFkjMICPSAB_bO_z-Lnog"
+    >
+      <template #help>Custom help text via `help` slot</template>
+    </veui-uploader>
+  </section>
+</article>
+</template>
+
+<script>
+import { Uploader, RadioButtonGroup } from 'veui'
+
+const mapper = (value) => ({ label: value, value })
+
+export default {
+  components: {
+    'veui-uploader': Uploader,
+    'veui-radio-button-group': RadioButtonGroup
+  },
+  data () {
+    let files = [
+      {
+        name: 'demo-file1.txt',
+        src: '/file/demo-file1.txt',
+        key: 0
+      }
+    ]
+    return {
+      files,
+      helpPosition: 'side',
+      availableHelpPositions: ['side', 'bottom'].map(mapper)
+    }
+  }
+}
+</script>
+
+<style lang="less" scoped>
+article {
+  display: flex;
+}
+
+.veui-uploader {
+  margin-top: 16px;
+}
+
+section {
+  width: 45%;
+}
+</style>

one/docs/demo/uploader/pick.vue

@@ -0,0 +1,34 @@
+<template>
+<article>
+  <section>
+    <veui-uploader
+      type="file"
+      :pick="pick"
+      action="https://app.fakejson.com/q/ELymQ7xh?token=AWFkjMICPSAB_bO_z-Lnog"
+    />
+  </section>
+</article>
+</template>
+
+<script>
+import { Uploader } from 'veui'
+import confirm from 'veui/plugins/confirm'
+import Vue from 'vue'
+
+Vue.use(confirm)
+
+export default {
+  components: {
+    'veui-uploader': Uploader
+  },
+  methods: {
+    pick ({ remainingCount }) {
+      return this.$confirm('模拟自定义选择文件', '确认').then((ready) => {
+        return ready
+          ? new File([`count: ${remainingCount}`], 'pick.txt', { type: 'text/plain' })
+          : null
+      })
+    }
+  }
+}
+</script>