add date-picker doc

2024-12-01 03:28:42 +08:00 · 2018-03-20 09:10:56 +08:00 · 2018-03-20 09:10:56 +08:00 · cef16b096f
commit cef16b096f
parent def0f5678f
9 changed files with 199 additions and 121 deletions
--- 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,
        },
--- a/components/date-picker/demo/index.vue
+++ b/components/date-picker/demo/index.vue
@ -0,0 +1,63 @@
+<script>
+import Basic from './basic'
+import DateRender from './date-render'
+import DisabledDate from './disabled-date'
+import Disabled from './disabled'
+import ExtraFooter from './extra-footer'
+import Format from './format'
+import Mode from './mode'
+import PresettedRanges from './presetted-ranges'
+import Size from './size'
+import StartEnd from './start-end'
+import Time from './time'
+import CN from '../index.zh-CN.md'
+import US from '../index.en-US.md'
+const md = {
+  cn: `# DatePicker 日期选择框
+          输入或选择日期的控件。
+## 何时使用
+当用户需要输入一个日期，可以点击标准输入框，弹出日期面板进行选择。
+          ## 代码演示`,
+  us: `# DatePicker
+          To select or input a date.
+## When To Use
+By clicking the input box, you can select a date from a popup calendar.
+## Examples
+          `,
+}
+export default {
+  category: 'Components',
+  type: 'Data Entry',
+  title: 'DatePicker',
+  subtitle: '日期选择框',
+  render () {
+    return (
+      <div id='components-date-picker-demo'>
+        <md cn={md.cn} us={md.us}/>
+        <Basic/>
+        <DateRender/>
+        <DisabledDate/>
+        <Disabled/>
+        <ExtraFooter/>
+        <Format/>
+        <Mode/>
+        <PresettedRanges/>
+        <Size/>
+        <StartEnd/>
+        <Time/>
+
+        <api>
+          <CN slot='cn' />
+          <US/>
+        </api>
+      </div>
+    )
+  },
+}
+</script>
+<style>
+#components-date-picker-demo .ant-calendar-picker {
+  margin: 0 8px 12px 0;
+}
+
+</style>
--- a/components/date-picker/demo/start-end.md
+++ b/components/date-picker/demo/start-end.md
@ -2,15 +2,15 @@
 <cn>
 #### 自定义日期范围选择
 当 `RangePicker` 无法满足业务需求时，可以使用两个 `DatePicker` 实现类似的功能。
- 通过设置 `disabledDate` 方法，来约束开始和结束日期。
-  通过 `open` `onOpenChange` 来优化交互。
+> * 通过设置 `disabledDate` 方法，来约束开始和结束日期。
+> * 通过 `open` `onOpenChange` 来优化交互。
 </cn>

 <us>
 #### 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`.
 </us>

 ```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;
    },
  },
 }
--- 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

+<cn>
+#### 日期时间选择
 增加选择时间功能，当 `showTime` 为一个对象时，其属性会传递给内建的 `TimePicker`。
+</cn>

-## en-US
-
+<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`.
+</us>

-````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
+<template>
  <div>
-    <DatePicker
+    <a-date-picker
      showTime
      format="YYYY-MM-DD HH:mm:ss"
      placeholder="Select Time"
-      onChange={onChange}
-      onOk={onOk}
+      @change="onChange"
+      @ok="onOk"
    />
    <br />
-    <RangePicker
-      showTime={{ format: 'HH:mm' }}
+    <a-range-picker
+      :showTime="{ format: 'HH:mm' }"
      format="YYYY-MM-DD HH:mm"
-      placeholder={['Start Time', 'End Time']}
-      onChange={onChange}
-      onOk={onOk}
+      :placeholder="['Start Time', 'End Time']"
+      @change="onChange"
+      @ok="onOk"
    />
  </div>
-, mountNode);
-````
+</template>
+<script>
+export default {
+  methods: {
+    onChange(value, dateString) {
+      console.log('Selected Time: ', value);
+      console.log('Formatted Selected Time: ', dateString);
+    },
+    onOk(value) {
+      console.log('onOk: ', value);
+    }
+  }
+}
+</script>
+```
+
--- 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');

-<DatePicker defaultValue={moment('2015-01-01', 'YYYY-MM-DD')} />
-```
+<a-date-picker :defaultValue="moment('2015-01-01', 'YYYY-MM-DD')" />
+````

 ### 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\]&#x3A; [moment](http://momentjs.com/)\[] } \| () => { \[range: string\]&#x3A; [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() | - |

-<style>
-.code-box-demo .ant-calendar-picker {
-  margin: 0 8px 12px 0;
-}
-</style>
+### 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() |
+
--- 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');

-<DatePicker defaultValue={moment('2015-01-01', 'YYYY-MM-DD')} />
-```
+<a-date-picker :defaultValue="moment('2015-01-01', 'YYYY-MM-DD')" />
+````

 ### 共同的 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\]&#x3A; [moment](http://momentjs.com/)\[] } \| () => { \[range: string\]&#x3A; [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() | - |

-<style>
-.code-box-demo .ant-calendar-picker {
-  margin: 0 8px 12px 0;
-}
-</style>
+### RangePicker事件
+
+| 事件名称 | 说明 | 回调参数 |
+| --- | --- | --- |
+| calendarChange | 待选日期发生变化的回调 | function(dates: [moment, moment], dateStrings: [string, string]) |
+| change | 日期范围发生变化的回调 | function(dates: [moment, moment], dateStrings: [string, string]) | 无 |
+| ok | 点击确定按钮的回调 | function() |
+
--- 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
--- 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'
--- 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 {