element-plus/website/docs/zh-CN/date-picker.md
zazzaz 0b6c862f44
fix: correct locale name (#628)
* fix: correct locale name

* chore: update

* fix: add name

* fix: set correct dayjs locale

* chore: update
2020-11-19 15:58:25 +08:00

432 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

## DatePicker 日期选择器
用于选择或输入日期
### 选择日
以「日」为基本单位,基础的日期选择控件
:::demo 基本单位由`type`属性指定。快捷选项需配置`picker-options`对象中的`shortcuts`,禁用日期通过 `disabledDate` 设置,传入函数
```html
<template>
<div class="block">
<span class="demonstration">默认</span>
<el-date-picker
v-model="value1"
type="date"
placeholder="选择日期">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">带快捷选项</span>
<el-date-picker
v-model="value2"
align="right"
type="date"
placeholder="选择日期"
:disabled-date="disabledDate"
:shortcuts="shortcuts"
>
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
disabledDate(time) {
return time.getTime() > Date.now()
},
shortcuts: [{
text: 'Today',
value: new Date(),
}, {
text: 'Yesterday',
value: (() => {
const date = new Date()
date.setTime(date.getTime() - 3600 * 1000 * 24)
return date
})(),
}, {
text: 'A week ago',
value: (() => {
const date = new Date()
date.setTime(date.getTime() - 3600 * 1000 * 24 * 7)
return date
})(),
}],
value1: '',
value2: '',
};
}
};
</script>
```
:::
### 其他日期单位
通过扩展基础的日期选择,可以选择周、月、年或多个日期
:::demo
```html
<div class="container">
<div class="block">
<span class="demonstration"></span>
<el-date-picker
v-model="value1"
type="week"
format="gggg 第 ww 周"
placeholder="选择周">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration"></span>
<el-date-picker
v-model="value2"
type="month"
placeholder="选择月">
</el-date-picker>
</div>
</div>
<div class="container">
<div class="block">
<span class="demonstration"></span>
<el-date-picker
v-model="value3"
type="year"
placeholder="选择年">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">多个日期</span>
<el-date-picker
type="dates"
v-model="value4"
placeholder="选择一个或多个日期">
</el-date-picker>
</div>
</div>
<script>
export default {
data() {
return {
value1: '',
value2: '',
value3: '',
value4: ''
};
}
};
</script>
```
:::
### 选择日期范围
可在一个选择器中便捷地选择一个时间范围
:::demo 在选择日期范围时,默认情况下左右面板会联动。如果希望两个面板各自独立切换当前月份,可以使用`unlink-panels`属性解除联动。
```html
<template>
<div class="block">
<span class="demonstration">默认</span>
<el-date-picker
v-model="value1"
type="daterange"
range-separator="至"
start-placeholder="开始日期"
end-placeholder="结束日期">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">带快捷选项</span>
<el-date-picker
v-model="value2"
type="daterange"
align="right"
unlink-panels
range-separator="至"
start-placeholder="开始日期"
end-placeholder="结束日期"
:shortcuts="shortcuts"
>
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
shortcuts: [{
text: '最近一周',
value: (() => {
const end = new Date()
const start = new Date()
start.setTime(start.getTime() - 3600 * 1000 * 24 * 7)
return [start, end]
})(),
}, {
text: '最近一个月',
value: (() => {
const end = new Date()
const start = new Date()
start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
return [start, end]
})(),
}, {
text: '最近三个月',
value: (() => {
const end = new Date()
const start = new Date()
start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
return [start, end]
})(),
}],
value1: '',
value2: ''
};
}
};
</script>
```
:::
### 选择月份范围
可在一个选择器中便捷地选择一个月份范围
:::demo 在选择月份范围时,默认情况下左右面板会联动。如果希望两个面板各自独立切换当前年份,可以使用`unlink-panels`属性解除联动。
```html
<template>
<div class="block">
<span class="demonstration">默认</span>
<el-date-picker
v-model="value1"
type="monthrange"
range-separator="至"
start-placeholder="开始月份"
end-placeholder="结束月份">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">带快捷选项</span>
<el-date-picker
v-model="value2"
type="monthrange"
align="right"
unlink-panels
range-separator="至"
start-placeholder="开始月份"
end-placeholder="结束月份"
:shortcuts="shortcuts"
>
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
shortcuts: [{
text: '本月',
value: [new Date(), new Date()],
}, {
text: '今年至今',
value: (() => {
const end = new Date()
const start = new Date(new Date().getFullYear(), 0)
return [start, end]
})(),
}, {
text: '最近六个月',
value: (() => {
const end = new Date()
const start = new Date()
start.setMonth(start.getMonth() - 6)
return [start, end]
})(),
}],
value1: '',
value2: ''
};
}
};
</script>
```
:::
### 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="value1"
type="date"
placeholder="Pick a date"
:default-value="new Date(2010, 9, 1)">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">daterange</span>
<el-date-picker
v-model="value2"
type="daterange"
align="right"
start-placeholder="Start Date"
end-placeholder="End Date"
:default-value="[new Date(2010, 9, 1), new Date(2010, 10, 1)]">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
value1: '',
value2: ''
};
}
};
</script>
```
:::
### 日期格式
使用`format`指定输入框的格式。
默认情况下,组件接受并返回`Date`对象。
在 [这里](https://day.js.org/docs/zh-CN/display/format) 查看 Day.js 支持的 format 参数。
:::warning
请注意大小写
:::
:::demo
```html
<template>
<div class="block">
<span class="demonstration">默认为 Date 对象</span>
<div class="demonstration">值:{{ value1 }}</div>
<el-date-picker
v-model="value1"
type="date"
placeholder="选择日期"
format="YYYY 年 MM 月 DD 日">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
value1: '',
value2: '',
value3: ''
};
}
};
</script>
```
:::
### 默认显示日期
在选择日期范围时,指定起始日期和结束日期的默认时刻。
:::demo 选择日期范围时,默认情况下,起始日期和结束日期的时间部分均为当天的 0 点 0 分 0 秒。通过`default-time`可以分别指定二者的具体时刻。`default-time`接受一个数组,其中的值为形如`12:00:00`的字符串,第一个值控制起始日期的时刻,第二个值控制结束日期的时刻。
```html
<template>
<div class="block">
<p>组件值:{{ value }}</p>
<el-date-picker
v-model="value"
type="daterange"
start-placeholder="开始日期"
end-placeholder="结束日期"
:default-time="[new Date(2000, 1, 1, 0 , 0,0), new Date(2000, 2, 1, 23 , 59,59)]">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
value: ''
};
}
};
</script>
```
:::
### Attributes
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---------- |-------------- |---------- |-------------------------------- |-------- |
| value / v-model | 绑定值 | date(DatePicker) / array(DateRangePicker) | — | — |
| readonly | 完全只读 | boolean | — | false |
| disabled | 禁用 | boolean | — | false |
| editable | 文本框可输入 | boolean | — | true |
| clearable | 是否显示清除按钮 | boolean | — | true |
| size | 输入框尺寸 | string | large/medium/small/mini | large |
| placeholder | 非范围选择时的占位内容 | string | — | — |
| start-placeholder | 范围选择时开始日期的占位内容 | string | — | — |
| end-placeholder | 范围选择时结束日期的占位内容 | string | — | — |
| type | 显示类型 | string | year/month/date/dates/ week/datetime/datetimerange/ daterange/monthrange | date |
| format | 显示在输入框中的格式 | string | 见[日期格式](#/zh-CN/component/date-picker#ri-qi-ge-shi) | yyyy-MM-dd |
| align | 对齐方式 | string | left, center, right | left |
| popper-class | DatePicker 下拉框的类名 | string | — | — |
| range-separator | 选择范围时的分隔符 | string | — | '-' |
| default-value | 可选,选择器打开时默认显示的时间 | Date | 可被`new Date()`解析 | — |
| default-time | 范围选择时选中日期所使用的当日内具体时刻 | string[] | 数组,长度为 2每项值为字符串形如`12:00:00`,第一项指定开始日期的时刻,第二项指定结束日期的时刻,不指定会使用时刻 `00:00:00` | — |
| name | 原生属性 | string | — | — |
| unlink-panels | 在范围选择器里取消两个日期面板之间的联动 | boolean | — | false |
| prefix-icon | 自定义头部图标的类名 | string | — | el-icon-date |
| clear-icon | 自定义清空图标的类名 | string | — | el-icon-circle-close |
| validate-event | 输入时是否触发表单的校验 | boolean | - | true |
### Picker Options
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---------- |-------------- |---------- |-------------------------------- |-------- |
| shortcuts | 设置快捷选项,需要传入 { text, onClick } 对象用法参考 demo 或下表 | Object[] | — | — |
| disabledDate | 设置禁用状态,参数为当前日期,要求返回 Boolean | Function | — | — |
| cellClassName | 设置日期的 className | Function(Date) | — | — |
| firstDayOfWeek | 周起始日 | Number | 1 到 7 | 7 |
| onPick | 选中日期后会执行的回调,只有当 `daterange``datetimerange` 才生效 | Function({ maxDate, minDate }) | — | — |
### Shortcuts
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---------- |-------------- |---------- |-------------------------------- |-------- |
| text | 标题文本 | string | — | — |
| onClick | 选中后的回调函数,参数是 vm可通过触发 'pick' 事件设置选择器的值。例如 vm.$emit('pick', new Date()) | function | — | — |
### Events
| 事件名称 | 说明 | 回调参数 |
|---------|--------|---------|
| change | 用户确认选定的值时触发 | 组件绑定值 |
| blur | 当 input 失去焦点时触发 | 组件实例 |
| focus | 当 input 获得焦点时触发 | 组件实例 |
### Methods
| 方法名 | 说明 | 参数 |
| ---- | ---- | ---- |
| focus | 使 input 获取焦点 | — |