feat: update docs

2020-09-22 11:06:13 +08:00
parent d64014f3b4
commit 468f6995c3
32 changed files with 1032 additions and 548 deletions
--- a/one/docs/components/autocomplete.md
+++ b/one/docs/components/autocomplete.md
@@ -12,7 +12,7 @@
 | -- | -- | -- | -- |
 | `datasource` | `Array<string|Object>=` | `[]` | [^datasource] |
 | `value` | `*` | - | [^prop-value] |
-| `match` | `function(string|Object, string)=: boolean` | - | 自定义搜索逻辑。 |
+| `match` | `function(string|Object, string): boolean=` | - | 自定义搜索逻辑。 |
 | `strict` | `boolean=` | `false` | 建议下拉面板关闭时，若输入值没有完全匹配建议值，那么会清空输入值。 |
 | `suggest-trigger` | `string|Array<string>=` | `'input'` | 触发建议下拉面板的时机，可用值有：`'input'`、`'focus'`。 |
 | `placeholder` | `string=` |  | 输入占位符。 |
--- a/one/docs/components/button-group.md
+++ b/one/docs/components/button-group.md
@@ -4,7 +4,7 @@

 ### 风格

-可选的 `ui` 属性值：`primary`/`strong`。
+可选的 `ui` 属性值：`primary`/`strong`/`basic`。

 [[ demo src="/demo/button-group/style.vue" ]]

@@ -44,6 +44,7 @@
 | -- | -- |
 | `primary` | 主要按钮，背景显示为主题色。 |
 | `strong` | 加强样式。 |
+| `basic` | 基础样式。 |
 | `xs` | 超小尺寸样式。 |
 | `s` | 小尺寸样式。 |
 | `m` | 中尺寸样式。 |
--- a/one/docs/components/calendar.md
+++ b/one/docs/components/calendar.md
@@ -35,7 +35,7 @@
 | `week-start` | `number=` | `calendar.weekStart` | 一周的起始。可进行[全局配置](#全局配置)。 |
 | `fill-month` | `boolean=` | `true` | 当只有一个面板时，是否要在当前月份面板显示非本月日期。 |
 | `date-class` | `string|Array|Object|function=` | `{}` | 特定日期的自定义 HTML `class`。传非函数时，数据格式为所有 [Vue 支持的 `class` 表达式](https://cn.vuejs.org/v2/guide/class-and-style.html#%E7%BB%91%E5%AE%9A-HTML-Class)；传函数时，签名为 `function(Date): string|Array<string>|Object<string, boolean>`，返回值格式亦为所有 Vue 支持的 `class` 表达式。 |
-| `disabled-date` | `function(Date)=: boolean` | `() => false` | 特定日期是否禁用。 |
+| `disabled-date` | `function(Date, Date=): boolean=` | `() => false` | 第一个参数为需要判断是否禁用的日期。当处于范围选择过程中且已经选择了一个日期，会作为第二个参数传入。 |
 | `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
 | `readonly` | `boolean=` | `false` | 是否为只读状态。 |

--- a/one/docs/components/check-button-group.md
+++ b/one/docs/components/check-button-group.md
@@ -8,6 +8,12 @@

 [[ demo src="/demo/check-button-group/default.vue" ]]

+### 单复选共存
+
+可以使用 `exclusive` 选项与 `empty-value` 实现一些单复选共存的场景。
+
+[[ demo src="/demo/check-button-group/exclusive.vue" ]]
+
 ## API

 ### 属性
@@ -19,6 +25,7 @@
 | `value` | `Array` | `[]` | [^value] |
 | `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
 | `readonly` | `boolean=` | `false` | 是否为只读状态。 |
+| `empty-value` | `*` | - | 当取消所有选择时组件需要默认选中的值，通常用于存在 `exclusive` 选项的场景。 |

 ^^^ui
 预设样式。
@@ -31,7 +38,7 @@
 ^^^

 ^^^items
-复选按钮组数据源，项目类型为 `{label, value, disabled, ...}`。
+复选按钮组数据源，项目类型为 `{label, value, disabled, exclusive, ...}`。

 +++字段详情
 | 名称 | 类型 | 描述 |
@@ -39,6 +46,7 @@
 | `label` | `string` | 选项的文字说明。 |
 | `value` | `*` | 选项对应的值。 |
 | `disabled` | `boolean=` | 选项是否为禁用。 |
+| `exclusive` | `boolean=` | 选项是否为排它项。当选项为排它项时，选中该项将取消选中其它所有选项。 |
 +++
 ^^^

@@ -86,3 +94,9 @@

 选中状态变化后触发，回调参数为 `(value: Array)`。`value` 为当前按钮组已选项内 `value` 字段组成的数组。
 ^^^
+
+### 图标
+
+| 名称 | 描述 |
+| -- | -- |
+| `check` | 已选标志。 |
--- a/one/docs/components/checkbox-group.md
+++ b/one/docs/components/checkbox-group.md
@@ -8,6 +8,12 @@

 [[ demo src="/demo/checkbox-group/default.vue" ]]

+### 单复选共存
+
+可以使用 `exclusive` 选项与 `empty-value` 实现一些单复选共存的场景。
+
+[[ demo src="/demo/checkbox-group/exclusive.vue" ]]
+
 ## API

 ### 属性
@@ -19,6 +25,7 @@
 | `value` | `Array` | `[]` | [^value] |
 | `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
 | `readonly` | `boolean=` | `false` | 是否为只读状态。 |
+| `empty-value` | `*` | - | 当取消所有选择时组件需要默认选中的值，通常用于存在 `exclusive` 选项的场景。 |

 ^^^ui
 预设样式。
@@ -26,12 +33,12 @@
 +++枚举值
 | 值 | 描述 |
 | -- | -- |
-| `m` | 中尺寸样式。 |
 | `s` | 小尺寸样式。 |
+| `m` | 中尺寸样式。 |
 ^^^

 ^^^items
-复选框组数据源，项目类型为 `{label, value, disabled, ...}`。
+复选框组数据源，项目类型为 `{label, value, disabled, exclusive, ...}`。

 +++字段详情
 | 名称 | 类型 | 描述 |
@@ -39,6 +46,7 @@
 | `label` | `string` | 选项的文字说明。 |
 | `value` | `*` | 选项对应的值。 |
 | `disabled` | `boolean=` | 选项是否为禁用。 |
+| `exclusive` | `boolean=` | 选项是否为排它项。 |
 +++
 ^^^

--- a/one/docs/components/column.md
+++ b/one/docs/components/column.md
@@ -19,7 +19,7 @@
 | `width` | `string=|number=` | - | 列宽，值为像素值。 |
 | `sortable` | `boolean=` | `false` | [^sortable] |
 | `align` | `string=` | - | 内容对齐方式，支持 `left`/`center`/`right`。 |
-| `span` | `function(number)=: Object` | | [^span] |
+| `span` | `function(number): Object=` | | [^span] |

 ^^^sortable
 本列是否支持排序。
--- a/one/docs/components/date-picker.md
+++ b/one/docs/components/date-picker.md
@@ -33,10 +33,11 @@
 | `week-start` | `number` | `calendar.weekStart` | 一周的起始。可进行[全局配置](./calendar#全局配置)。 |
 | `fill-month` | `boolean` | `true` | 当只有一个面板时，是否要在当前月份面板显示非本月日期。 |
 | `date-class` | `string|Array|Object|function` | `{}` | 特定日期的自定义 HTML `class`。传非函数时，数据格式为所有 Vue 支持的 `class` 表达式；传函数时，签名为 `function(Date): string|Array<string>|Object<string, boolean>`，返回值格式亦为所有 Vue 支持的 `class` 表达式。 |
-| `disabled-date` | `function(Date): boolean` | `() => false` | 特定日期是否禁用。 |
+| `disabled-date` | `function(Date, Date=): boolean=` | `() => false` | 用于自定义指定日期是否禁用。第一个参数为需要判断是否禁用的日期。当处于范围选择过程中且已经选择了一个日期，会作为第二个参数传入。 |
 | `clearable` | `boolean` | `false` | 已选值是否可以清除。 |
 | `placeholder` | `string` | `range ? datepicker.rangePlaceholder : datepicker.placeholder` | 未选择时的占位文本。可进行[全局配置](#全局配置)。 |
-| `format` | `string` | `'yyyy-MM-dd'`/`'yyyy-MM'`/`'yyyy'` | 用于格式化的字符串表达式，具体格式可以参见 [date-fns 的文档](https://date-fns.org/v2.12.0/docs/format)。 |
+| `format` | `string|function(Date): string=` | `'yyyy-MM-dd'`/`'yyyy-MM'`/`'yyyy'` | 使用字符串时，表示用于格式化/解析的字符串表达式，具体格式可以参见 [date-fns 的文档](https://date-fns.org/v2.12.0/docs/format)。传入函数可自定义格式化逻辑。 |
+| `parse` | `function(string): Date=` | - | 自定义将输入字符串解析为 `Date` 对象的函数。 |
 | `shortcuts` | `Array<Object>` | `datepicker.shortcuts` | [^shortcuts] |
 | `disabled` | `boolean=` | `false` | 是否为禁用状态。 |
 | `readonly` | `boolean=` | `false` | 是否为只读状态。 |
@@ -181,6 +182,8 @@
 | 名称 | 描述 |
 | -- | -- |
 | `select` | [^event-select] |
+| `selectstart` | 选择日期范围时，选择完起始日期时触发，回调参数 `(picking: Date)`，表示已选的起始项日期。 |
+| `selectprogress` | [^event-selectprogress] |

 ^^^event-select
 :::badges
@@ -190,6 +193,17 @@
 选择修改后触发，回调参数为 `(selected)`。数据类型和 `selected` 属性一致。
 ^^^

+^^^event-selectprogress
+选择日期范围时，在已经选择开始日期后，通过鼠标或键盘交互标记到的结束日期变更时触发。回调参数为 `(picking)`，表示当前标记的日期范围，类型取决于 `multiple` 属性的值。
+
+++参数详请
+| `multiple` | 类型 |
+| -- | -- |
+| `false` | `[Date, Date]` |
+| `true` | `Array<[Date, Date]>` |
+++
+^^^
+
 ### 全局配置

 | 配置项 | 类型 | 默认值 | 描述 |
--- a/one/docs/components/dialog.md
+++ b/one/docs/components/dialog.md
@@ -40,7 +40,7 @@
 | `footless` | `boolean=` | `false` | 是否不显示默认的底部操作栏。 |
 | `loading` | `boolean=` | `false` | 是否处于加载状态。处于加载状态时确定按钮也将进入加载状态，无法点击。 |
 | `priority` | `number=` | - | 对话框浮层层叠权重，参考 [`Overlay`](./overlay) 组件的 [`priority`](./overlay#props) 属性。 |
-| `before-close` | `function(string)=: boolean=|Promise<boolean=>` | - | [^before-close] |
+| `before-close` | `function(string): boolean=|Promise<boolean=>` | - | [^before-close] |
 | `overlay-class` | `string|Object=` | - | 对话框浮层根元素类名，参考 [`Overlay`](./overlay) 组件的 [`overlay-class`](./overlay#props) 属性。 |

 ^^^ui
--- a/one/docs/components/embedded.md
+++ b/one/docs/components/embedded.md
@@ -21,7 +21,7 @@
 | `footless` | `boolean=` | `false` | 是否不显示默认的底部操作栏。 |
 | `loading` | `boolean=` | `false` | 是否处于加载状态。处于加载状态时确定按钮也将进入加载状态，无法点击。 |
 | `priority` | `number=` | - | 折叠式面板浮层层叠权重，参考 [`Overlay`](./overlay) 组件的 [`priority`](./overlay#props) 属性。 |
-| `before-close` | `function(string)=: boolean=|Promise<boolean=>` | - | 在将触发折叠式面板关闭的操作发生后执行，参考 [`Dialog`](./dialog) 组件的 [`before-close`](./dialog#props) 属性。 |
+| `before-close` | `function(string): boolean=|Promise<boolean=>` | - | 在将触发折叠式面板关闭的操作发生后执行，参考 [`Dialog`](./dialog) 组件的 [`before-close`](./dialog#props) 属性。 |
 | `overlay-class` | `string|Object=` | - | 折叠式面板浮层根元素类名，参考 [`Overlay`](./overlay) 组件的 [`overlay-class`](./overlay#props) 属性。 |

 ^^^ui
--- a/one/docs/components/input.md
+++ b/one/docs/components/input.md
@@ -35,6 +35,7 @@
 | `clearable` | `boolean=` | `false` | 是否显示清除按钮。 |
 | `composition` | `boolean=` | `false` | 是否感知输入法输入过程的值。 |
 | `select-on-focus` | `boolean=` | `false` | 聚焦时是否自动选中输入框文本。 |
+| `get-length` | `function(string): number=` | 自定义的字符长度计算函数。 |

 ^^^ui
 预设样式。
--- a/one/docs/components/textarea.md
+++ b/one/docs/components/textarea.md
@@ -36,6 +36,7 @@
 | `composition` | `boolean` | `false` | 是否感知输入法输入过程的值。 |
 | `select-on-focus` | `boolean` | `false` | 聚焦时是否自动选中文本域文本。 |
 | `autoresize` | `boolean` | `false` | 高度是否会被内容撑开。 |
+| `get-length` | `function(string): number=` | 自定义的字符长度计算函数。 |

 ^^^ui
 预设样式。
--- a/one/docs/components/uploader.md
+++ b/one/docs/components/uploader.md
@@ -168,15 +168,15 @@
 | 字段 | 类型 | 描述 |
 | -- | -- | -- |
 | `onload` | `function` | 上传完成的回调函数，参数内容与 `convert-response` prop 返回值相同。 |
-| `onprogress` | `function` | 上传进度发生变化的回调函数，参数为 `{ loaded: number, total: number }`，`loaded` 为已上传部分大小，`total` 为文件总大小。 |
+| `onprogress` | `function` | 上传进度发生变化的回调函数，参数为 `{ loaded: number, total: number }`，`loaded` 为已上传部分字节数，`total` 为文件总字节数。 |
+| `oncancel` | `function` | 自定义上传主动取消时对组件进行的回调，无参数。 |
 | `onerror` | `function` | 上传出错的回调函数，参数为 `{ message: string }`，`message` 为错误提示信息。 |

-该方法如果返回一个函数，该函数将在用户操作取消或上传组件销毁时被调用，用来中断自定义上传过程。
-
+如果 `upload` 返回一个函数，该函数将在用户操作取消或上传组件销毁时被调用，用来中断自定义上传过程。
 ^^^

 ^^^controls
-图片上传模式下，自定义配置图片遮罩浮层上的操作项，参数为 `(file: Object, defaultControls: Array<Object>)`，`file` 为文件相关信息，`defaultControls` 为包含默认的操作项的数组。该方法可根据文件状态的不同，返回包含不同的操作项的数组。每个操作项的具体字段如下：
+图片上传模式下，用来自定义配置图片遮罩浮层上的操作项，参数为 `(file: Object, defaultControls: Array<Object>)`，`file` 为文件相关信息，`defaultControls` 为包含默认的操作项的数组。可根据文件状态的不同，返回包含不同的操作项的数组。每个操作项的具体字段如下：

 +++字段详情
 | 字段 | 类型 | 描述 |
@@ -184,7 +184,6 @@
 | `name` | `string` | 操作项的名称，点击该按钮后会抛出同名的事件，事件的回调参数为 `(file: Object, index: number)`， `file` 为触发事件的文件对象，`index` 为文件在列表中的序号。 |
 | `icon` | `string` | 操作项使用的图标。 |
 | `disabled` | `boolean=` | 操作项是否被禁用。如果该字段为空，则该操作项的禁用状态跟随组件整体的禁用状态。 |
-
 ^^^

 ### 插槽
@@ -201,9 +200,9 @@
 | `failure` | 图片上传模式下，上传失败的单个图片的区域。作用域参数与 `file` 作用域插槽相同。 |

 ^^^button-label
-上传文件的按钮里的内容。
+上传按钮里的内容。

-默认内容：提示选择文件。
+默认内容：文件上传为提示选择文件，图片上传则为上传图片图标。
 ^^^

 ^^^file
@@ -263,10 +262,9 @@
 ^^^

 ^^^event-invalid
-文件校验失败时触发，回调参数为 `(invalidInfo: Object)`。
+文件校验失败时触发，回调参数为 `(validity: Object)`。

 +++参数字段详情
-
 | 名称 | 类型 | 描述 |
 | -- | -- | -- |
 | `file` | `Object` | 没有通过校验的文件信息，与 `remove` 事件的回调参数中的 `file` 相同。如果校验失败的原因是选择的文件数量超过最大数量 `max-count` 限制，则这个字段为空。 |
@@ -274,24 +272,21 @@
 +++

 +++校验失败信息字段详情
-
 | 名称 | 类型 | 描述 |
 | -- | -- | -- |
-| `type` | `string` | 校验失败的类型，类型可从 `Uploader` 组件 `export` 的 `(errors: Object)` 对象获取。 |
-| `value` | `number|string|Object` | 没有通过校验的值，根绝 `type` 的不同有不同的类型。 |
+| `type` | `string` | 校验失败的类型，类型枚举值可从 `Uploader.errors` 对象获取，如 `Uploader.errors.SIZE_INVALID`。 |
+| `value` | `number|string|Object` | 没有通过校验的值，根据 `type` 的不同有不同的类型。 |
 | `message` | `string` | 检验失败的提示信息。 |
 +++

-+++校验失败信息 type 和 value 对应关系
-
-| 失败类型 | 失败描述 | value 的类型 | value 描述 |
+++校验失败类型与参数关系
+| 类型 | 描述 | `value` 类型 | `value` 描述 |
 | -- | -- | -- | -- |
 | `TYPE_INVALID` | 文件类型校验失败。 | `string` | 文件名称。 |
-| `SIZE_INVALID` | 文件大小校验失败。 | `number` | 文件大小。 |
-| `TOO_MANY_FILES` | 选择的文件数量超过最大数量 `max-count` 限制。 | `number` | 已选择的文件数量。 |
-| `CUSTOM_INVALID` | `validator` 自定义校验失败。 | `Object` | 文件对象。 |
+| `SIZE_INVALID` | 文件大小校验失败。 | `number` | 文件大小字节数。 |
+| `TOO_MANY_FILES` | 选择的文件数超过 `max-count` 限制。 | `number` | 已选择的文件数。 |
+| `CUSTOM_INVALID` | `validator` 自定义校验失败。 | `Object` | 文件对象，字段同 `remove` 事件回调参数。 |
 +++
-
 ^^^

 ^^^event-statuschange