[Carbon] *-Picker 重构

examples/docs/en-US/date-picker.md

@@ -57,7 +57,11 @@
         value4: '',
         value5: '',
         value6: '',
-        value7: ''
+        value7: '',
+        value8: '',
+        value9: '',
+        value10: '',
+        value11: ''
       };
     }
   };
@@ -275,25 +279,116 @@ Picking a date range is supported.
 
 :::
 
+###  Default Value
+
+If user hasn't picked a date, shows today's calendar by default. You can use `default-value` to set another date. Its value should be parsable by `new Date()`.
+
+If type is `daterange`, `default-value` sets the left side calendar.
+
+:::demo
+```html
+<template>
+  <div class="block">
+    <span class="demonstration">date</span>
+    <el-date-picker
+      v-model="value8"
+      type="date"
+      placeholder="Pick a date"
+      default-value="2010-10-01">
+    </el-date-picker>
+  </div>
+  <div class="block">
+    <span class="demonstration">daterange</span>
+    <el-date-picker
+      v-model="value9"
+      type="daterange"
+      start-placeholder="Start Date"
+      end-placeholder="End Date"
+      default-value="2010-10-01">
+    </el-date-picker>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        value8: '',
+        value9: ''
+      };
+    }
+  };
+</script>
+```
+:::
+
+###  Formatted Value
+
+By default, DatePicker emits `Date` object. You can use `value-format` to designate the format of emitted value, it accepts the same format string of `format` attribute.
+
+:::warning
+This feature is at alpha stage. Feedback welcome.
+:::
+
+:::demo
+```html
+<template>
+  <div class="block">
+    <span class="demonstration">Emits Date object</span>
+    <div class="demonstration">Value: {{ value10 }}</div>
+    <el-date-picker
+      v-model="value10"
+      type="date"
+      placeholder="Pick a Date"
+      format="yyyy/MM/dd">
+    </el-date-picker>
+  </div>
+  <div class="block">
+    <span class="demonstration">Emits formatted date</span>
+    <div class="demonstration">Value: {{ value11 }}</div>
+    <el-date-picker
+      v-model="value11"
+      type="date"
+      placeholder="Pick a Date"
+      format="yyyy/MM/dd"
+      value-format="yyyy-MM-dd">
+    </el-date-picker>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        value10: '',
+        value11: '',
+      };
+    }
+  };
+</script>
+```
+:::
+
 ### Attributes
 | Attribute      | Description          | Type      | Accepted Values       | Default  |
 |---------- |-------------- |---------- |--------------------------------  |-------- |
 | readonly | whether DatePicker is read only | boolean | — | false |
 | disabled | whether DatePicker is disabled | boolean | — | false |
-|size | size of Input | string | large/small/mini | — |
+| size | size of Input | string | large/small/mini | — |
 | editable | whether the input is editable | boolean | — | true |
 | clearable | Whether to show clear button | boolean | — | true |
 | placeholder | placeholder in non-range mode | string | — | — |
 | start-placeholder | placeholder for the start date in range mode | string | — | — |
 | end-placeholder | placeholder for the end date in range mode | string | — | — |
 | type | type of the picker | string | year/month/date/datetime/ week/datetimerange/daterange | date |
-| format | format of the picker | string | year `yyyy` month `MM` day `dd`, hour `HH`, minute `mm`, second `ss` | yyyy-MM-dd |
+| format | format of the input box | string | year `yyyy`, month `MM`, day `dd`, hour `HH`, minute `mm`, second `ss` | yyyy-MM-dd |
 | align | alignment | left/center/right | left |
 | popper-class | custom class name for DatePicker's dropdown | string | — | — |
 | picker-options | additional options, check the table below | object | — | {} |
-| range-separator | range separator | string | - | '-' |
-| default-value | optional default time of the picker | Date | anything accepted by `new Date()` | - |
-|name | same as `name` in native input | string | — | — |
+| range-separator | range separator | string | — | '-' |
+| default-value | optional, default date of the calendar | Date | anything accepted by `new Date()` | — |
+| value-format | optional, format of bounded value | string | year `yyyy`, month `MM`, day `dd`, hour `HH`, minute `mm`, second `ss` | — |
+| name | same as `name` in native input | string | — | — |
 
 ### Picker Options
 | Attribute      | Description          | Type      | Accepted Values       | Default  |
@@ -313,7 +408,7 @@ Picking a date range is supported.
 ### Events
 | Event Name | Description | Parameters |
 |---------|--------|---------|
-| change | triggers when input value changes | formatted value |
+| change | triggers when user confirms the value | component's bounded value |
 | blur | triggers when Input blurs | (event: Event) |
 | focus | triggers when Input focuses | (event: Event) |
 

examples/docs/en-US/datetime-picker.md

@@ -251,7 +251,9 @@ DateTimePicker is derived from DatePicker and TimePicker. For a more detailed ex
 | popper-class | custom class name for DateTimePicker's dropdown | string | — | — |
 | picker-options | additional options, check the table below | object | — | {} |
 | range-separator | range separator | string | - | '-' |
-|name | same as `name` in native input | string | — | — |
+| default-value | optional, default date of the calendar | Date | anything accepted by `new Date()` | — |
+| value-format | optional, format of bounded value | string | year `yyyy`, month `MM`, day `dd`, hour `HH`, minute `mm`, second `ss` | — |
+| name | same as `name` in native input | string | — | — |
 
 ### Picker Options
 | Attribute      | Description          | Type      | Accepted Values       | Default  |
@@ -269,7 +271,7 @@ DateTimePicker is derived from DatePicker and TimePicker. For a more detailed ex
 ### Events
 | Event Name | Description | Parameters |
 |---------|--------|---------|
-| change | triggers when input value changes | formatted value |
+| change | triggers when user confirms the value | component's bounded value |
 | blur | triggers when Input blurs | (event: Event) |
 | focus | triggers when Input focuses | (event: Event) |
 

examples/docs/en-US/time-picker.md

@@ -161,12 +161,14 @@ Can pick an arbitrary time range.
 | placeholder | placeholder in non-range mode | string | — | — |
 | start-placeholder | placeholder for the start time in range mode | string | — | — |
 | end-placeholder | placeholder for the end time in range mode | string | — | — |
-| value | value of the picker | date for Time Picker, and string for Time Select | hour `HH`, minute `mm`, second `ss` | HH:mm:ss |
+| value | value of the picker | Date for Time Picker, and string for Time Select | hour `HH`, minute `mm`, second `ss` | HH:mm:ss |
 | align | alignment | left / center / right | left |
 | popper-class | custom class name for TimePicker's dropdown | string | — | — |
 | picker-options | additional options, check the table below | object | — | {} |
 | range-separator | range separator | string | - | '-' |
-|name | same as `name` in native input | string | — | — |
+| default-value | optional, default date of the calendar | Date for TimePicker, string for TimeSelect | anything accepted by `new Date()` for TimePicker, selectable value for TimeSelect | — |
+| value-format | optional, only for TimePicker, format of bounded value | string | hour `HH`, minute `mm`, second `ss` | — |
+| name | same as `name` in native input | string | — | — |
 
 ### Time Select Options
 | Attribute      | Description          | Type      | Accepted Values       | Default  |
@@ -187,6 +189,6 @@ Can pick an arbitrary time range.
 ### Events
 | Event Name | Description | Parameters |
 |---------|--------|---------|
-| change | triggers when input value changes | formatted value |
+| change | triggers when user confirms the value | component's bounded value |
 | blur | triggers when Input blurs | (event: Event) |
 | focus | triggers when Input focuses | (event: Event) |

examples/docs/zh-CN/date-picker.md

@@ -65,7 +65,11 @@
         value4: '',
         value5: '',
         value6: '',
-        value7: ''
+        value7: '',
+        value8: '',
+        value9: '',
+        value10: '',
+        value11: ''
       };
     }
   };
@@ -285,6 +289,96 @@
 ```
 :::
 
+###  默认显示日期
+
+未选择日期时，默认显示今天的日历。使用`default-value`可以指定其他日期，该值需要能够被`new Date()`解析。
+类型为`daterange`时，指定左侧日历的日期。
+
+:::demo
+```html
+<template>
+  <div class="block">
+    <span class="demonstration">date</span>
+    <el-date-picker
+      v-model="value8"
+      type="date"
+      placeholder="选择日期"
+      default-value="2010-10-01">
+    </el-date-picker>
+  </div>
+  <div class="block">
+    <span class="demonstration">daterange</span>
+    <el-date-picker
+      v-model="value9"
+      type="daterange"
+      start-placeholder="开始日期"
+      end-placeholder="结束日期"
+      default-value="2010-10-01">
+    </el-date-picker>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        value8: '',
+        value9: ''
+      };
+    }
+  };
+</script>
+```
+:::
+
+###  返回值格式
+
+默认情况下，组件接受并返回`Date`对象。
+使用`value-format`指定返回值的格式，支持的格式与`format`相同。
+
+:::warning
+该功能处于测试阶段，欢迎提供反馈。
+:::
+
+:::demo
+```html
+<template>
+  <div class="block">
+    <span class="demonstration">默认为 Date 对象</span>
+    <div class="demonstration">组件值：{{ value10 }}</div>
+    <el-date-picker
+      v-model="value10"
+      type="date"
+      placeholder="选择日期"
+      format="yyyy 年 MM 月 dd 日">
+    </el-date-picker>
+  </div>
+  <div class="block">
+    <span class="demonstration">使用 value-format 进行格式化</span>
+    <div class="demonstration">组件值：{{ value11 }}</div>
+    <el-date-picker
+      v-model="value11"
+      type="date"
+      placeholder="选择日期"
+      format="yyyy 年 MM 月 dd 日"
+      value-format="yyyy-MM-dd">
+    </el-date-picker>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        value10: '',
+        value11: '',
+      };
+    }
+  };
+</script>
+```
+:::
+
 ### Attributes
 | 参数      | 说明          | 类型      | 可选值                           | 默认值  |
 |---------- |-------------- |---------- |--------------------------------  |-------- |
@@ -297,12 +391,13 @@
 | start-placeholder | 范围选择时开始日期的占位内容 | string | — | — |
 | end-placeholder | 范围选择时结束日期的占位内容 | string | — | — |
 | type | 显示类型 | string | year/month/date/week/ datetime/datetimerange/daterange | date |
-| format | 时间日期格式化 | string | 年 `yyyy`，月 `MM`，日 `dd`，小时 `HH`，分 `mm`，秒 `ss` | yyyy-MM-dd |
+| format | 输入框的时间日期格式 | string | 年 `yyyy`，月 `MM`，日 `dd`，小时 `HH`，分 `mm`，秒 `ss` | yyyy-MM-dd |
 | align | 对齐方式 | string | left, center, right | left |
 | popper-class | DatePicker 下拉框的类名 | string | — | — |
-|picker-options | 当前时间日期选择器特有的选项参考下表 | object |  — | {} |
-| range-separator | 选择范围时的分隔符 | string | - | '-' |
-| default-value | 可选，DatePicker打开时默认显示的时间 | Date | 可被new Date()解析 | - |
+| picker-options | 当前时间日期选择器特有的选项参考下表 | object |  — | {} |
+| range-separator | 选择范围时的分隔符 | string | — | '-' |
+| default-value | 可选，选择器打开时默认显示的时间 | Date | 可被`new Date()`解析 | — |
+| value-format | 可选，绑定值的格式 | string | 年 `yyyy`，月 `MM`，日 `dd`，小时 `HH`，分 `mm`，秒 `ss` | — |
 | name | 原生属性 | string | — | — |
 
 ### Picker Options
@@ -322,7 +417,7 @@
 ### Events
 | 事件名称      | 说明    | 回调参数      |
 |---------|--------|---------|
-| change | 当 input 的值改变时触发，返回值和文本框一致 | 格式化后的值 |
+| change | 用户确认选定的值时触发 | 组件绑定值 |
 | blur | 当 input 失去焦点时触发 | (event: Event) |
 | focus | 当 input 获得焦点时触发 | (event: Event) |
 

examples/docs/zh-CN/datetime-picker.md

@@ -250,6 +250,8 @@ DateTimePicker 由 DatePicker 和 TimePicker 派生，`Picker Options` 或者其
 | popper-class | DateTimePicker 下拉框的类名 | string | — | — |
 | picker-options | 当前时间日期选择器特有的选项参考下表 | object |  — | {} |
 | range-separator | 选择范围时的分隔符 | string | - | '-' |
+| default-value | 可选，选择器打开时默认显示的时间 | Date | 可被`new Date()`解析 | — |
+| value-format | 可选，绑定值的格式 | string | 年 `yyyy`，月 `MM`，日 `dd`，小时 `HH`，分 `mm`，秒 `ss` | — |
 | name | 原生属性 | string | — | — |
 
 ### Picker Options
@@ -268,7 +270,7 @@ DateTimePicker 由 DatePicker 和 TimePicker 派生，`Picker Options` 或者其
 ### Events
 | Event Name | Description | Parameters |
 |---------|--------|---------|
-| change | 当 input 的值改变时触发，返回值和文本框一致 | formatted value |
+| change | 用户确认选定的值时触发 | 组件绑定值 |
 | blur | 当 input 失去焦点时触发 | (event: Event) |
 | focus | 当 input 获得焦点时触发 | (event: Event) |
 

examples/docs/zh-CN/time-picker.md

@@ -166,6 +166,8 @@
 | popper-class | TimePicker 下拉框的类名 | string | — | — |
 | picker-options | 当前时间日期选择器特有的选项参考下表 | object | — | {} |
 | range-separator | 选择范围时的分隔符 | string | - | '-' |
+| value-format | 可选，仅TimePicker时可用，绑定值的格式，同DatePicker | string | 小时 `HH`，分 `mm`，秒 `ss` | — |
+| default-value | 可选，选择器打开时默认显示的时间 | Date(TimePicker) / string(TimeSelect) | 可被`new Date()`解析(TimePicker) / 可选值(TimeSelect) | — |
 | name | 原生属性 | string | — | — |
 
 ### Time Select Options
@@ -186,7 +188,7 @@
 ### Events
 | 事件名 | 说明 | 参数 |
 |---------|--------|---------|
-| change | 当 input 的值改变时触发，返回值和文本框一致 | formatted value |
+| change | 用户确认选定的值时触发 | 组件绑定值 |
 | blur | 当 input 失去焦点时触发 | (event: Event) |
 | focus | 当 input 获得焦点时触发 | (event: Event) |