From 74e718d57b8931a3bb9aaaea2a2a2fb0041d2852 Mon Sep 17 00:00:00 2001 From: mengxiong10 <15623530290@163.com> Date: Tue, 15 Jan 2019 22:51:44 +0800 Subject: [PATCH] docs: update docs --- README.md | 139 ++++++++++++++++++--------------------- README.zh-CN.md | 171 ++++++++++++++++++++++++------------------------ 2 files changed, 150 insertions(+), 160 deletions(-) diff --git a/README.md b/README.md index d790de8..2bce1ec 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,17 @@ export default { time1: '', time2: '', time3: '', + // custom lang + lang: { + days: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'], + months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], + pickers: ['next 7 days', 'next 30 days', 'previous 7 days', 'previous 30 days'], + placeholder: { + date: 'Select Date', + dateRange: 'Select Date Range' + } + }, + // custom range shortcuts shortcuts: [ { text: 'Today', @@ -64,38 +75,39 @@ export default { + ``` ### Props -| Prop | Type | Accepted Values | Default | Description | -|---------------------|---------------|-----------------|-------------|-----------------------------------------------------| -| type | String | date/datetime/year/month/time | 'date' | select date type | -| range | Boolean | — | false | if true, the type is daterange or datetimerange | -| format | String | — | YYYY-MM-DD | The parsing tokens are similar to the moment.js | -| value-type | String/Object | date/format/timestamp | 'date' | type of binding value. If not specified, the binding value will be a Date object(see [detail](#value-type)) | -| lang | String/Object | en/zh/es/pt-br/fr/ru/de/it/cs | zh | Translation (set [how to custom](#lang)) | -| clearable | Boolean | — | true | if false, don't show the clear icon | -| confirm | Boolean | — | false | if true, need click the button to change the value | -| editable | Boolean | — | true | if false, user cann't type it | -| disabled | Boolean | — | false | Disable the component | -| placeholder | String | — | | input placeholder text | -| width | String/Number | — | 210 | input size | -| append-to-body | Boolean | — | false | append the popup to body | -| popupStyle | Object | — | | popup style(override the top, left style) | -| not-before | String/Date | — | '' | Disable all dates before new Date(not-before) | -| not-after | String/Date | — | '' | Disable all dates after new Date(not-after) | -| disabled-days | Array/function| — | [] | Disable Days | -| shortcuts | Boolean/Array | — | true | the shortcuts for the range picker | -| time-picker-options | Object | — | {} | set timePickerOptions(start, step, end) | -| minute-step | Number | 0 - 60 | 0 | if > 0 don't show the second picker | -| first-day-of-week | Number | 1 - 7 | 7 | set the first day of week | -| input-class | String | — | 'mx-input' | the input class name | -| input-attr | Object | — | | the input attr(eg: { required: true, id: 'input'}) | -| confirm-text | String | — | 'OK' | the default text to display on confirm button | -| range-separator | String | — | '~' | the range separator text | -| date-format | String | — | '' | format the time header and tooltip | +| Prop | Description | Type | Default | +|------|--------------|-------|---------| +| type | select date type | 'date' \| 'datetime' \| 'year' \| 'month' \| 'time' | 'date' | +| range | if true, the type is daterange or datetimerange | `boolean` | false | +| format | format the Date. The parsing tokens are similar to the moment.js | [token](https://github.com/taylorhakes/fecha#formatting-tokens) | 'YYYY-MM-DD' | +| value-type | type of binding value. If not specified, the binding value will be a Date object | [value-type](#value-type) | 'date' | +| lang | Translation | [lang](#lang) | 'zh' | +| clearable | if false, don't show the clear icon | `boolean` | true | +| confirm | if true, need click the button to change the value | `boolean` | false | +| editable | if false, user cann't type it | `boolean` | true | +| disabled | Disable the component | `boolean` | false | +| placeholder | input placeholder text | `string` | — | +| width | input size | `string`\|`number` | 210 | +| append-to-body | append the popup to body | `boolean` | false | +| popupStyle | popup style(override the top, left style) | `object` | — | +| not-before | Disable all dates before new Date(not-before) | `string`\|`Date` | ''| +| not-after | Disable all dates after new Date(not-after) | `string`\|`Date`| '' | +| disabled-days | Disable Days | `(date) => boolean` | - | +| shortcuts | the shortcuts for the range picker | [shortcuts](#shortcuts) | true | +| time-picker-options | custom time-picker | [time-picker-options](#time-picker-options) | null | +| minute-step | if > 0 don't show the second picker | 0 - 60 | 0 | +| first-day-of-week | set the first day of week | 1 - 7 | 7 | +| input-class | the input class name | `string` | 'mx-input' | +| input-attr | the input attr(eg: { required: true, id: 'input'}) | `object` | — | +| confirm-text | the default text to display on confirm button | `string` | 'OK' | +| range-separator | the range separator text | `string` | '~' | +| date-format | format the time header and tooltip | `string` | '' | #### value-type set the format of binding value @@ -114,59 +126,29 @@ Advanced: You can also customize objects to implement two functions. } ``` - #### lang -* String (en/zh/es/pt-br/fr/ru/de/it/cs) -* Object (custom) -```html - - - - -``` +| Type | +|------| +| 'en'\|'zh'\|'es'\|'pt-br'\|'fr'\|'ru'\|'de'\|'it'\|'cs' | +| { days: string[]; months: string[]; picker: string[]; placeholder: { date: string; dateRange: string } } | #### shortcuts -* true - show the default shortcuts -* false - hide the shortcuts -* Object[] - custom shortcuts, [{text, start, end}] -* Object[] - custom shortcuts, [{text, onClick}] +the shortcuts for the range picker -| Prop | Type | Description | -|-----------------|---------------|------------------------| -| text | String | Text | -| start | Date | Start Date | -| end | Date | End Date | -| onClick | Function | click handler | +| Value | Description | +|-----------------|-------------| +| true | show the default shortcuts | +| false | hide the defaualt shortcuts | +| [{text: string, onClick: () => any }] | custom shortcuts | #### time-picker-options -* Object[] - custom time-picker, [{start, step, end}] - -| Prop | Type | Description | -|-----------------|---------------|------------------------| -| start | String | startTime (eg '00:00') | -| step | String | stepTime (eg '00:30') | -| end | String | endTime (eg '23:30') | +custom time-picker +| Type | +|------| +| {start: '00:00', step:'00:30' , end: '23:30'} | +| () => Array<{ label: string; values: { hours: number; minutes: number } }> | ### Events | Name | Description | Callback Arguments | @@ -176,11 +158,18 @@ export default { | confirm | When click 'confirm' button | the currentValue | | clear | When click 'clear' button | | | input-error | When user type a invalid Date | the input text | -| panel-change | When change the panel view(eg: from year to month view)| panel, oldPanel | +| panel-change | When change the panel view(eg: from year to month view)| [panel](#panel), [oldPanel](#panel) | | calendar-change | When calendar view year or month change | now(Date), oldNow(Date)| -#### panel value -`['NONE', 'DATE', 'YEAR', 'MONTH', 'TIME']` +#### panel + +| Value | Description | +|-------|----------------------| +| NONE | when panel is closed | +| DATE | when panel is date | +| YEAR | when panel is year | +| MONTH | when panel is month | +| TIME | when panel is time | ### Slots diff --git a/README.zh-CN.md b/README.zh-CN.md index ce17c23..14fa39e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -41,9 +41,20 @@ export default { time1: '', time2: '', time3: '', + // custom lang + lang: { + days: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'], + months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'], + pickers: ['next 7 days', 'next 30 days', 'previous 7 days', 'previous 30 days'], + placeholder: { + date: 'Select Date', + dateRange: 'Select Date Range' + } + }, + // custom range shortcuts shortcuts: [ { - text: '今天', + text: 'Today', onClick: () => { this.time3 = [ new Date(), new Date() ] } @@ -64,48 +75,48 @@ export default { + ``` -### Props - -| 属性 | 类型 | 可选值 | 默认值 | 描述 -|---------------------|---------------| ---------------------- |-------------| ----------- -| type | String | date,datetime,year,month,time | 'date' | 选择日期或日期时间 -| range | Boolean | - | false | 如果是true， 显示日历范围选择 -| format | String | - | YYYY-MM-DD | 格式化显示日期 api类似moment.js -| value-type | String/Object | date/format/timestamp | 'date' | 设置绑定值的格式([详情](#value-type)) | -| lang | String/Object | en/zh/es/pt-br/fr/ru/de/it/cs| zh | 选择语言或自定义 ([自定义](#lang)) -| clearable | Boolean | - | true | 如果设置false, 不显示清除图标 -| confirm | Boolean | - | false | 如果是true， 显示确认按钮且需要确认才更新时间 -| editable | Boolean | - | true | 如果是false, 用户不能手动输入更新日期 -| disabled | Boolean | - | false | 禁用组件 -| placeholder | String | - | | 输入框placeholder -| width | String/Number | - | 210 | 设置宽度 -| append-to-body | Boolean | - | false | 弹出层放到body下面 -| popup-style | Object | - | | 弹出层的样式(可以覆盖left,top样式) -| not-before | String/Date | - | '' | 禁止选择这个时间之前的时间 -| not-after | String/Date | - | '' | 禁止选择这个时间之前=后的时间 -| disabled-days | Array/function| - | [] | 自定义禁止的日期 -| shortcuts | Boolean/Array | - | true | 自定义范围选择的时候快捷选项(见下表) -| time-picker-options | Object | - | {} | 自定义时间选择的开始，结束，步进(见下表) -| minute-step | Number | 0 - 60 | 0 | 设置分钟的步进， 设置大于0不显示秒的选择(0-60) -| first-day-of-week | Number | 1 - 7 | 7 | 设置日历星期几开头 -| input-class | String | - | 'mx-input' | 自定义input元素的类名 -| input-attr | Object | — | | 自定义input元是的属性(eg: { required: true, id: 'input', name:'date'}) -| confirm-text | String | - | 'OK' | 确认按钮的名称 -| range-separator | String | - | '~' | range 分隔符 -| date-format | String | - | '' | 格式化时间组件头部和日历的tooltip,默认是format字段去除时间的格式化 +### 属性 +| 属性 | 描述 | 类型 | 默认值 | +|------|--------------|-------|---------| +| type | 选择日期类型 | 'date' \| 'datetime' \| 'year' \| 'month' \| 'time' | 'date' | +| range | 如果是true, 显示日历范围选择 | `boolean` | false | +| format | 格式化显示日期, 值类似moment.js | [token](https://github.com/taylorhakes/fecha#formatting-tokens) | 'YYYY-MM-DD' | +| value-type | 设置绑定值的格式, 默认返回日期对象 | [value-type](#value-type) | 'date' | +| lang | 选择语言或自定义 | [lang](#lang) | 'zh' | +| clearable | 如果设置false, 不显示清除图标 | `boolean` | true | +| confirm | 如果是true， 显示确认按钮且需要确认才更新时间 | `boolean` | false | +| editable | 如果是false, 用户不能手动输入更新日期 | `boolean` | true | +| disabled | 禁用组件 | `boolean` | false | +| placeholder | 输入框placeholder | `string` | — | +| width | 设置宽度 | `string`\|`number` | 210 | +| append-to-body | 弹出层元素插入body下面 | `boolean` | false | +| popupStyle | 弹出层的样式(可以覆盖left,top样式) | `object` | — | +| not-before | 禁止选择这个时间之前的时间 | `string`\|`Date` | ''| +| not-after | 禁止选择这个时间之前=后的时间 | `string`\|`Date`| '' | +| disabled-days | 自定义禁止的日期 | `(date) => boolean` | - | +| shortcuts | 自定义范围选择的时候快捷选项 | [shortcuts](#shortcuts) | true | +| time-picker-options | 自定义时间选择的开始，结束，步进 | [time-picker-options](#time-picker-options) | null | +| minute-step | 设置分钟的步进， 设置大于0不显示秒的选择(0-60) | 0 - 60 | 0 | +| first-day-of-week | 设置日历星期几开头 | 1 - 7 | 7 | +| input-class | 自定义input元素的类名 | `string` | 'mx-input' | +| input-attr | 自定义input元素的属性(eg: { required: true, id: 'input'}) | `object` | — | +| confirm-text | 确认按钮的名称 | `string` | 'OK' | +| range-separator | range 分隔符 | `string` | '~' | +| date-format | 格式化时间组件头部和日历的tooltip,默认是format字段去除时间的格式化 | `string` | '' | #### value-type 设置绑定值的格式 -| 可选值 | 描述 -|-----------------|--------------------------------------- -| date | 返回的绑定值是Date对象 -| timestamp | 返回的绑定值是时间戳数字 -| format | 返回的绑定值是通过`format`属性格式化的值 +| 可选值 | 描述 | +|-----------------|-------------------------------------------| +| date | 返回的绑定值是Date对象 | +| timestamp | 返回的绑定值是时间戳数字 | +| format | 返回的绑定值是通过`format`属性格式化的值 | 高级: 也可以传入一个自定义实现包含2个函数的对象 ```js @@ -115,72 +126,62 @@ export default { } ``` - #### lang -* String (en/zh/es/pt-br/fr/ru/de/it/cs) -* Object (自定义) -```html - - - - -``` +| 可选值 | +|------| +| 'en'\|'zh'\|'es'\|'pt-br'\|'fr'\|'ru'\|'de'\|'it'\|'cs' | +| { days: string[]; months: string[]; picker: string[]; placeholder: { date: string; dateRange: string } } | #### shortcuts -* true - 显示默认快捷选择 -* false - 隐藏快捷选择 -* Object[] - 自定义快捷选择, 格式：[{text, start, end}] -* Object[] - 自定义快捷选择, 格式：[{text, onClick}] -| 名称 | 类型 | 说明 | -|-----------------|---------------|----------------| -| text | String | 显示文字 | -| start | Date | 开始日期 | -| end | Date | 结束日期 | -| onClick | Function | 点击时候触发的函数 | +| 可选值 | 描述 | +|-----------------|-------------| +| true | 显示默认快捷选择 | +| false | 隐藏默认快捷选择 | +| [{text: string, onClick: () => any }] | 自定义快捷选择 | #### time-picker-options -* Object[] - 自定义时间选择, 格式：[{start, step, end}] +自定义时间选择 -| 名称 | 类型 | 说明 | -|-----------------|---------------|-----------------------| -| start | String | 开始时间 (eg '00:00') | -| step | String | 步进时间 (eg '00:30') | -| end | String | 结束时间 (eg '23:30') | +| 可选值 | +|------| +| {start: '00:00', step:'00:30' , end: '23:30'} | +| () => Array<{ label: string; values: { hours: number; minutes: number } }> | - -### Events +### 事件 | Name | 说明 | 回调参数 |-----------------|----------------------------- |---------------- | change | 日期改变的时候触发 | 选择的日期 | input | 日期改变的时候触发 | 选择的日期 -| confirm | 点击确认按钮触发的事件 | 选择的日期 +| confirm | 点击确认按钮触发的事件 | 选择的日期 +| clear | 清空时候触发 | | input-error | 当用户输入的值无效时候触发 | 用户输入的字符串 -| panel-change | 切换面板时触发 | 当前面板，过去的面板 +| panel-change | 切换面板时触发 | [panel](#panel), [oldPanel](#panel) | calendar-change | 日历的年或月改变时触发 | 当前日历时间，过去日历时间 -#### panel value -`['NONE', 'DATE', 'YEAR', 'MONTH', 'TIME']` +#### panel + +| 值 | 描述 | +|-------|----------------------| +| NONE | 当面板关闭时的值 | +| DATE | 当面板是日期选择时的值 | +| YEAR | 当面板是年选择时的值 | +| MONTH | 当面板是月选择时的值 | +| TIME | 当面板是时间选择时的值 | + +### Slots + +| 名称 | 描述 | +|-----------------|--------------------------| +| calendar-icon | 图标自定义 | +| header | 日历头部自定义 | +| footer | 日历尾部自定义 | + +## 日志 + +[CHANGELOG](CHANGELOG.md) + ## 许可证