From bb50ac5736539f059df8f95c79e17f25462b8353 Mon Sep 17 00:00:00 2001 From: tjz <415800467@qq.com> Date: Tue, 20 Mar 2018 09:10:56 +0800 Subject: [PATCH] add date-picker doc --- components/date-picker/createPicker.js | 3 +- components/date-picker/demo/index.vue | 63 +++++++++++++++++++ components/date-picker/demo/start-end.md | 26 ++++---- components/date-picker/demo/time.md | 66 ++++++++++---------- components/date-picker/index.en-US.md | 73 +++++++++++----------- components/date-picker/index.zh-CN.md | 79 +++++++++++++----------- contributors.md | 4 +- examples/demo.js | 1 + examples/index.less | 5 ++ 9 files changed, 199 insertions(+), 121 deletions(-) create mode 100644 components/date-picker/demo/index.vue diff --git a/components/date-picker/createPicker.js b/components/date-picker/createPicker.js index c95b9024a..aaa348741 100644 --- a/components/date-picker/createPicker.js +++ b/components/date-picker/createPicker.js @@ -95,6 +95,7 @@ export default function createPicker (TheCalendar, props) { const props = getOptionProps(this) const { prefixCls, locale, localeCode } = props const dateRender = props.dateRender || $scopedSlots.dateRender + const monthCellContentRender = props.monthCellContentRender || $scopedSlots.monthCellContentRender const placeholder = ('placeholder' in props) ? props.placeholder : locale.lang.placeholder @@ -132,7 +133,7 @@ export default function createPicker (TheCalendar, props) { dateRender, format: props.format, showToday: props.showToday, - monthCellContentRender: props.monthCellContentRender, + monthCellContentRender, renderFooter: this.renderFooter, value: showDate, }, diff --git a/components/date-picker/demo/index.vue b/components/date-picker/demo/index.vue new file mode 100644 index 000000000..5930018f0 --- /dev/null +++ b/components/date-picker/demo/index.vue @@ -0,0 +1,63 @@ + + diff --git a/components/date-picker/demo/start-end.md b/components/date-picker/demo/start-end.md index c9389c053..ca1133e87 100644 --- a/components/date-picker/demo/start-end.md +++ b/components/date-picker/demo/start-end.md @@ -2,15 +2,15 @@ #### 自定义日期范围选择 当 `RangePicker` 无法满足业务需求时，可以使用两个 `DatePicker` 实现类似的功能。 - 通过设置 `disabledDate` 方法，来约束开始和结束日期。 - 通过 `open` `onOpenChange` 来优化交互。 +> * 通过设置 `disabledDate` 方法，来约束开始和结束日期。 +> * 通过 `open` `onOpenChange` 来优化交互。 #### Customized Range Picker When `RangePicker` does not satisfied your requirements, try to implement similar functionality with two `DatePicker`. - Use the `disabledDate` property to limit the start and end dates. - Improve user experience with `open` and `onOpenChange`. +> * Use the `disabledDate` property to limit the start and end dates. +> * Improve user experience with `open` and `onOpenChange`. ```html @@ -48,32 +48,32 @@ export default { }, methods: { disabledStartDate (startValue) { - const endValue = this.endValue + const endValue = this.endValue; if (!startValue || !endValue) { - return false + return false; } - return startValue.valueOf() > endValue.valueOf() + return startValue.valueOf() > endValue.valueOf(); }, disabledEndDate (endValue) { - const startValue = this.startValue + const startValue = this.startValue; if (!endValue || !startValue) { - return false + return false; } - return endValue.valueOf() <= startValue.valueOf() + return startValue.valueOf() >= endValue.valueOf(); }, onStartChange (value) { - this.startValue = value + this.startValue = value; }, onEndChange (value) { this.endValue = value }, handleStartOpenChange (open) { if (!open) { - this.endOpen = true + this.endOpen = true; } }, handleEndOpenChange (open) { - this.endOpen = open + this.endOpen = open; }, }, } diff --git a/components/date-picker/demo/time.md b/components/date-picker/demo/time.md index 1e02d1db6..95ba85529 100644 --- a/components/date-picker/demo/time.md +++ b/components/date-picker/demo/time.md @@ -1,48 +1,46 @@ ---- -order: 3 -title: - zh-CN: 日期时间选择 - en-US: Choose Time ---- - -## zh-CN + +#### 日期时间选择 增加选择时间功能，当 `showTime` 为一个对象时，其属性会传递给内建的 `TimePicker`。 + -## en-US - + +#### Choose Time This property provide an additional time selection. When `showTime` is an Object, its properties will be passed on to built-in `TimePicker`. + -````jsx -import { DatePicker } from 'antd'; -const { RangePicker } = DatePicker; - -function onChange(value, dateString) { - console.log('Selected Time: ', value); - console.log('Formatted Selected Time: ', dateString); -} - -function onOk(value) { - console.log('onOk: ', value); -} - -ReactDOM.render( +```html + + +``` + diff --git a/components/date-picker/index.en-US.md b/components/date-picker/index.en-US.md index 2b44407e3..19967de83 100644 --- a/components/date-picker/index.en-US.md +++ b/components/date-picker/index.en-US.md @@ -1,14 +1,3 @@ ---- -category: Components -type: Data Entry -title: DatePicker ---- - -To select or input a date. - -## When To Use - -By clicking the input box, you can select a date from a popup calendar. ## API @@ -21,14 +10,14 @@ There are four kinds of picker: **Note:** Part of locale of DatePicker, MonthPicker, RangePicker, WeekPicker is read from value. So, please set the locale of moment correctly. -```jsx +````html // The default locale is en-US, if you want to use other locale, just set locale in entry file globaly. // import moment from 'moment'; // import 'moment/locale/zh-cn'; // moment.locale('zh-cn'); - -``` + +```` ### Common API @@ -39,17 +28,20 @@ The following APIs are shared by DatePicker, MonthPicker, RangePicker, WeekPicke | allowClear | Whether to show clear button | boolean | true | | autoFocus | get focus when component mounted | boolean | false | | className | picker className | string | '' | -| dateRender | custom rendering function for date cells | function(currentDate: moment, today: moment) => React.ReactNode | - | +| dateRender | custom rendering function for date cells by setting a scoped slot | slot="dateRender" slot-scope="current, today" | - | | disabled | determine whether the DatePicker is disabled | boolean | false | | disabledDate | specify the date that cannot be selected | (currentDate: moment) => boolean | - | | getCalendarContainer | to set the container of the floating layer, while the default is to create a `div` element in `body` | function(trigger) | - | -| locale | localization configuration | object | [default](https://github.com/ant-design/ant-design/blob/master/components/date-picker/locale/example.json) | +| locale | localization configuration | object | [default](https://github.com/vueComponent/ant-design/blob/master/components/date-picker/locale/example.json) | | open | open state of picker | boolean | - | | placeholder | placeholder of date input | string\|RangePicker\[] | - | | popupStyle | to customize the style of the popup calendar | object | {} | | size | determine the size of the input box, the height of `large` and `small`, are 40px and 24px respectively, while default size is 32px | string | - | -| style | to customize the style of the input box | object | {} | -| onOpenChange | a callback function, can be executed whether the popup calendar is popped up or closed | function(status) | - | + +### Common Events +| Events Name | Description | Arguments | +| --- | --- | --- | +| openChange | a callback function, can be executed whether the popup calendar is popped up or closed | function(status) | ### Common Methods @@ -65,14 +57,18 @@ The following APIs are shared by DatePicker, MonthPicker, RangePicker, WeekPicke | defaultValue | to set default date | [moment](http://momentjs.com/) | - | | disabledTime | to specify the time that cannot be selected | function(date) | - | | format | to set the date format, refer to [moment.js](http://momentjs.com/) | string | "YYYY-MM-DD" | -| renderExtraFooter | render extra footer in panel | () => React.ReactNode | - | +| renderExtraFooter | render extra footer in panel by setting a scoped slot | slot="renderExtraFooter" | - | | showTime | to provide an additional time selection | object\|boolean | [TimePicker Options](/components/time-picker/#API) | -| showTime.defaultValue | to set default time of selected date, [demo](https://ant.design/components/date-picker/#components-date-picker-demo-disabled-date) | [moment](http://momentjs.com/) | moment() | +| showTime.defaultValue | to set default time of selected date | [moment](http://momentjs.com/) | moment() | | showToday | whether to show "Today" button | boolean | true | | value | to set date | [moment](http://momentjs.com/) | - | -| onCalendarChange | a callback function, can be executed when the start time or the end time of the range is changing | function(dates: [moment, moment], dateStrings: [string, string]) | 无 | -| onChange | a callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | - | -| onOk | callback when click ok button | function() | - | + +### DatePicker Events +| Events Name | Description | Arguments | +| --- | --- | --- | +| calendarChange | a callback function, can be executed when the start time or the end time of the range is changing | function(dates: [moment, moment], dateStrings: [string, string]) | +| change | a callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | +| ok | callback when click ok button | function() | ### MonthPicker @@ -80,10 +76,14 @@ The following APIs are shared by DatePicker, MonthPicker, RangePicker, WeekPicke | -------- | ----------- | ---- | ------- | | defaultValue | to set default date | [moment](http://momentjs.com/) | - | | format | to set the date format, refer to [moment.js](http://momentjs.com/) | string | "YYYY-MM" | -| monthCellContentRender | Custom month cell content render method | function(date, locale): ReactNode | - | -| renderExtraFooter | render extra footer in panel | () => React.ReactNode | - | +| monthCellContentRender | Custom month cell content render method by setting a scoped slot | slot="monthCellContentRender" slot-scope="date, locale" | - | +| renderExtraFooter | render extra footer in panel by setting a scoped slot | slot="renderExtraFooter" | - | | value | to set date | [moment](http://momentjs.com/) | - | -| onChange | a callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | - | + +### MonthPicker Events +| Events Name | Description | Arguments | +| --- | --- | --- | +| change | a callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | ### WeekPicker @@ -92,7 +92,11 @@ The following APIs are shared by DatePicker, MonthPicker, RangePicker, WeekPicke | defaultValue | to set default date | [moment](http://momentjs.com/) | - | | format | to set the date format, refer to [moment.js](http://momentjs.com/) | string | "YYYY-wo" | | value | to set date | [moment](http://momentjs.com/) | - | -| onChange | a callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | - | + +### WeekPicker Events +| Events Name | Description | Arguments | +| --- | --- | --- | +| change | a callback function, can be executed when the selected time is changing | function(date: moment, dateString: string) | ### RangePicker @@ -102,15 +106,14 @@ The following APIs are shared by DatePicker, MonthPicker, RangePicker, WeekPicke | disabledTime | to specify the time that cannot be selected | function(dates: [moment, moment], partial: `'start'|'end'`) | - | | format | to set the date format | string | "YYYY-MM-DD HH:mm:ss" | | ranges | preseted ranges for quick selection | { \[range: string\]: [moment](http://momentjs.com/)\[] } \| () => { \[range: string\]: [moment](http://momentjs.com/)\[] } | - | -| renderExtraFooter | render extra footer in panel | () => React.ReactNode | - | +| renderExtraFooter | render extra footer in panel by setting a scoped slot| slot="renderExtraFooter" | - | | showTime | to provide an additional time selection | object\|boolean | [TimePicker Options](/components/time-picker/#API) | | showTime.defaultValue | to set default time of selected date, [demo](https://ant.design/components/date-picker/#components-date-picker-demo-disabled-date) | [moment](http://momentjs.com/)\[] | [moment(), moment()] | | value | to set date | \[[moment](http://momentjs.com/), [moment](http://momentjs.com/)] | - | -| onChange | a callback function, can be executed when the selected time is changing | function(dates: [moment, moment], dateStrings: [string, string]) | - | -| onOk | callback when click ok button | function() | - | - +### RangePicker Events +| Events Name | Description | Arguments | +| --- | --- | --- | +| change | a callback function, can be executed when the selected time is changing | function(dates: [moment, moment], dateStrings: [string, string]) | +| ok | callback when click ok button | function() | + diff --git a/components/date-picker/index.zh-CN.md b/components/date-picker/index.zh-CN.md index 8f412fe44..cac1b6458 100644 --- a/components/date-picker/index.zh-CN.md +++ b/components/date-picker/index.zh-CN.md @@ -1,15 +1,3 @@ ---- -category: Components -type: Data Entry -title: DatePicker -subtitle: 日期选择框 ---- - -输入或选择日期的控件。 - -## 何时使用 - -当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择。 ## API @@ -22,14 +10,14 @@ subtitle: 日期选择框 **注意：**DatePicker、MonthPicker、RangePicker、WeekPicker 部分 locale 是从 value 中读取，所以请先正确设置 moment 的 locale。 -```jsx +````html // 默认语言为 en-US，如果你需要设置其他语言，推荐在入口文件全局设置 locale // import moment from 'moment'; // import 'moment/locale/zh-cn'; // moment.locale('zh-cn'); - -``` + +```` ### 共同的 API @@ -40,17 +28,21 @@ subtitle: 日期选择框 | allowClear | 是否显示清除按钮 | boolean | true | | autoFocus | 自动获取焦点 | boolean | false | | className | 选择器 className | string | '' | -| dateRender | 自定义日期单元格的内容 | function(currentDate: moment, today: moment) => React.ReactNode | - | +| dateRender | 作用域插槽，自定义日期单元格的内容 | slot="dateRender" slot-scope="current, today" | - | | disabled | 禁用 | boolean | false | | disabledDate | 不可选择的日期 | (currentDate: moment) => boolean | 无 | | getCalendarContainer | 定义浮层的容器，默认为 body 上新建 div | function(trigger) | 无 | -| locale | 国际化配置 | object | [默认配置](https://github.com/ant-design/ant-design/blob/master/components/date-picker/locale/example.json) | +| locale | 国际化配置 | object | [默认配置](https://github.com/vueComponent/ant-design/blob/master/components/date-picker/locale/example.json) | | open | 控制弹层是否展开 | boolean | - | | placeholder | 输入框提示文字 | string\|RangePicker\[] | - | | popupStyle | 格外的弹出日历样式 | object | {} | | size | 输入框大小，`large` 高度为 40px，`small` 为 24px，默认是 32px | string | 无 | -| style | 自定义输入框样式 | object | {} | -| onOpenChange | 弹出日历和关闭日历的回调 | function(status) | 无 | + +### 共有的事件 + +| 事件名称 | 说明 | 回调参数 | +| --- | --- | --- | +| openChange | 弹出日历和关闭日历的回调 | function(status) | ### 共同的方法 @@ -66,13 +58,18 @@ subtitle: 日期选择框 | defaultValue | 默认日期 | [moment](http://momentjs.com/) | 无 | | disabledTime | 不可选择的时间 | function(date) | 无 | | format | 展示的日期格式，配置参考 [moment.js](http://momentjs.com/) | string | "YYYY-MM-DD" | -| renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | +| renderExtraFooter | 在面板中添加额外的页脚 | slot="renderExtraFooter" | - | | showTime | 增加时间选择功能 | Object\|boolean | [TimePicker Options](/components/time-picker/#API) | -| showTime.defaultValue | 设置用户选择日期时默认的时分秒，[例子](https://ant.design/components/date-picker/#components-date-picker-demo-disabled-date) | [moment](http://momentjs.com/) | moment() | +| showTime.defaultValue | 设置用户选择日期时默认的时分秒 | [moment](http://momentjs.com/) | moment() | | showToday | 是否展示“今天”按钮 | boolean | true | | value | 日期 | [moment](http://momentjs.com/) | 无 | -| onChange | 时间发生变化的回调 | function(date: moment, dateString: string) | 无 | -| onOk | 点击确定按钮的回调 | function() | - | + +### DatePicker事件 + +| 事件名称 | 说明 | 回调参数 | +| --- | --- | --- | +| change | 时间发生变化的回调 | function(date: moment, dateString: string) | +| ok | 点击确定按钮的回调 | function() | ### MonthPicker @@ -80,10 +77,15 @@ subtitle: 日期选择框 | --- | --- | --- | --- | | defaultValue | 默认日期 | [moment](http://momentjs.com/) | 无 | | format | 展示的日期格式，配置参考 [moment.js](http://momentjs.com/) | string | "YYYY-MM" | -| monthCellContentRender | 自定义的月份内容渲染方法 | function(date, locale): ReactNode | - | -| renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | +| monthCellContentRender | 自定义的月份内容渲染方法 | slot="monthCellContentRender" slot-scope="date, locale" | - | +| renderExtraFooter | 在面板中添加额外的页脚 | slot="renderExtraFooter" | - | | value | 日期 | [moment](http://momentjs.com/) | 无 | -| onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: moment, dateString: string) | - | + +### MonthPicker事件 + +| 事件名称 | 说明 | 回调参数 | +| --- | --- | --- | +| change | 时间发生变化的回调，发生在用户选择时间时 | function(date: moment, dateString: string) | ### WeekPicker @@ -92,7 +94,12 @@ subtitle: 日期选择框 | defaultValue | 默认日期 | [moment](http://momentjs.com/) | - | | format | 展示的日期格式，配置参考 [moment.js](http://momentjs.com/) | string | "YYYY-wo" | | value | 日期 | [moment](http://momentjs.com/) | - | -| onChange | 时间发生变化的回调，发生在用户选择时间时 | function(date: moment, dateString: string) | - | + +### WeekPicker事件 + +| 事件名称 | 说明 | 回调参数 | +| --- | --- | --- | +| change | 时间发生变化的回调，发生在用户选择时间时 | function(date: moment, dateString: string) | ### RangePicker @@ -102,16 +109,16 @@ subtitle: 日期选择框 | disabledTime | 不可选择的时间 | function(dates: [moment, moment], partial: `'start'|'end'`) | 无 | | format | 展示的日期格式 | string | "YYYY-MM-DD HH:mm:ss" | | ranges       | 预设时间范围快捷选择 | { \[range: string\]: [moment](http://momentjs.com/)\[] } \| () => { \[range: string\]: [moment](http://momentjs.com/)\[] } | 无 | -| renderExtraFooter | 在面板中添加额外的页脚 | () => React.ReactNode | - | +| renderExtraFooter | 在面板中添加额外的页脚 | slot="renderExtraFooter" | - | | showTime | 增加时间选择功能 | Object\|boolean | [TimePicker Options](/components/time-picker/#API) | | showTime.defaultValue | 设置用户选择日期时默认的时分秒，[例子](https://ant.design/components/date-picker/#components-date-picker-demo-disabled-date) | [moment](http://momentjs.com/)\[] | [moment(), moment()] | | value | 日期 | [moment](http://momentjs.com/)\[] | 无 | -| onCalendarChange | 待选日期发生变化的回调 | function(dates: [moment, moment], dateStrings: [string, string]) | 无 | -| onChange | 日期范围发生变化的回调 | function(dates: [moment, moment], dateStrings: [string, string]) | 无 | -| onOk | 点击确定按钮的回调 | function() | - | - +### RangePicker事件 + +| 事件名称 | 说明 | 回调参数 | +| --- | --- | --- | +| calendarChange | 待选日期发生变化的回调 | function(dates: [moment, moment], dateStrings: [string, string]) | +| change | 日期范围发生变化的回调 | function(dates: [moment, moment], dateStrings: [string, string]) | 无 | +| ok | 点击确定按钮的回调 | function() | + diff --git a/contributors.md b/contributors.md index 36a3f2161..49cda4dac 100644 --- a/contributors.md +++ b/contributors.md @@ -24,8 +24,8 @@ Cascader | done BackTop | done Modal | done Alert | done -Calendar -DatePicker +Calendar | done +DatePicker | done TimePicker | done Upload Form diff --git a/examples/demo.js b/examples/demo.js index 25a5639d7..41772c75f 100644 --- a/examples/demo.js +++ b/examples/demo.js @@ -33,3 +33,4 @@ export { default as alert } from 'antd/alert/demo/index.vue' export { default as timePicker } from 'antd/time-picker/demo/index.vue' export { default as steps } from 'antd/steps/demo/index.vue' export { default as calendar } from 'antd/calendar/demo/index.vue' +export { default as datePicker } from 'antd/date-picker/demo/index.vue' diff --git a/examples/index.less b/examples/index.less index d99ea1a2c..3626d7e9b 100644 --- a/examples/index.less +++ b/examples/index.less @@ -32,6 +32,11 @@ font-weight: 500; background: rgba(0, 0, 0, 0.02); } +.api-container pre code { + padding: 12px 20px; + margin: 16px 0; + overflow: auto; +} .api-container table th, .api-container table td {