From a6ef40d1deba76a6429cb3d385eeeb600df3ca9b Mon Sep 17 00:00:00 2001
From: Alan Wang <wp_scut@163.com>
Date: Tue, 4 Jan 2022 10:56:55 +0800
Subject: [PATCH] docs: [datetimePicker]add guide of value-format (#5082)

---
 docs/en-US/component/datetime-picker.md       | 21 +++++++
 .../datetime-picker/date-and-time-formats.vue | 57 +++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 docs/examples/datetime-picker/date-and-time-formats.vue

diff --git a/docs/en-US/component/datetime-picker.md b/docs/en-US/component/datetime-picker.md
index fd65918d2c..f8374df575 100644
--- a/docs/en-US/component/datetime-picker.md
+++ b/docs/en-US/component/datetime-picker.md
@@ -42,6 +42,26 @@ datetime-picker/date-and-time
 
 :::
 
+## DateTime Formats
+
+Use `format` to control displayed text's format in the input box. Use `value-format` to control binding value's format.
+
+By default, the component accepts and emits a `Date` object.
+
+Check the list [here](https://day.js.org/docs/en/display/format#list-of-all-available-formats) of all available formats of Day.js.
+
+:::warning
+
+Pay attention to capitalization
+
+:::
+
+:::demo
+
+datetime-picker/date-and-time-formats
+
+:::
+
 ## Date and time range
 
 :::demo You can select date and time range by setting `type` to `datetimerange`.
@@ -78,6 +98,7 @@ datetime-picker/default-time
 | range-separator       | range separator                                                                                       | string                                            | -                                                                                                                                                                               | '-'                 |
 | default-value         | optional, default date of the calendar                                                                | Date                                              | anything accepted by `new Date()`                                                                                                                                               | —                   |
 | default-time          | the default time value after picking a date                                                           | non-range: Date / range: Date[]                   | non-range: a Date object, range: array of two Date objects, and the first item is for the start date and second for the end date. Time `00:00:00` will be used if not specified | —                   |
+| value-format          | optional, format of binding value. If not specified, the binding value will be a Date object          | string                                            | see [date formats](https://day.js.org/docs/en/display/format)                                                                                                                   | —                   |
 | id                    | same as `id` in native input                                                                          | string / array(string)                            | String `id="my-datetime"` or array `:id="['my-range-start', 'my-range-end']"` for date range                                                                                    | -                   |
 | name                  | same as `name` in native input                                                                        | string                                            | —                                                                                                                                                                               | —                   |
 | unlink-panels         | unllink two date-panels in range-picker                                                               | boolean                                           | —                                                                                                                                                                               | false               |
diff --git a/docs/examples/datetime-picker/date-and-time-formats.vue b/docs/examples/datetime-picker/date-and-time-formats.vue
new file mode 100644
index 0000000000..ad261878ad
--- /dev/null
+++ b/docs/examples/datetime-picker/date-and-time-formats.vue
@@ -0,0 +1,57 @@
+<template>
+  <div class="demo-date-picker">
+    <div class="block">
+      <span class="demonstration">Emits Date object</span>
+      <div class="demonstration">Value: {{ value1 }}</div>
+      <el-date-picker
+        v-model="value1"
+        type="datetime"
+        placeholder="Pick a Date"
+        format="YYYY/MM/DD hh:mm:ss"
+      >
+      </el-date-picker>
+    </div>
+    <div class="block">
+      <span class="demonstration">Use value-format</span>
+      <div class="demonstration">Value：{{ value2 }}</div>
+      <el-date-picker
+        v-model="value2"
+        type="datetime"
+        placeholder="Pick a Date"
+        format="YYYY/MM/DD hh:mm:ss"
+        value-format="YYYY-MM-DD h:m:s a"
+      >
+      </el-date-picker>
+    </div>
+    <div class="block">
+      <span class="demonstration">Timestamp</span>
+      <div class="demonstration">Value：{{ value3 }}</div>
+      <el-date-picker
+        v-model="value3"
+        type="datetime"
+        placeholder="Pick a Date"
+        format="YYYY/MM/DD hh:mm:ss"
+        value-format="x"
+      >
+      </el-date-picker>
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent, ref } from 'vue'
+
+export default defineComponent({
+  setup() {
+    const value1 = ref('')
+    const value2 = ref('')
+    const value3 = ref('')
+
+    return {
+      value1,
+      value2,
+      value3,
+    }
+  },
+})
+</script>