mirror of
https://gitee.com/vant-contrib/vant-weapp.git
synced 2025-04-06 03:58:05 +08:00
350 lines
9.3 KiB
Markdown
350 lines
9.3 KiB
Markdown
# Calendar 日历
|
|
|
|
### 介绍
|
|
|
|
日历组件用于选择日期或日期区间。
|
|
|
|
### 引入
|
|
|
|
在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](#/quickstart#yin-ru-zu-jian)。
|
|
|
|
```json
|
|
"usingComponents": {
|
|
"van-calendar": "@vant/weapp/calendar/index"
|
|
}
|
|
```
|
|
|
|
## 代码演示
|
|
|
|
### 选择单个日期
|
|
|
|
下面演示了结合单元格来使用日历组件的用法，日期选择完成后会触发`confirm`事件。
|
|
|
|
```html
|
|
<van-cell title="选择单个日期" value="{{ date }}" bind:click="onDisplay" />
|
|
<van-calendar show="{{ show }}" bind:close="onClose" bind:confirm="onConfirm" />
|
|
```
|
|
|
|
```js
|
|
Page({
|
|
data: {
|
|
date: '',
|
|
show: false,
|
|
},
|
|
|
|
onDisplay() {
|
|
this.setData({ show: true });
|
|
},
|
|
onClose() {
|
|
this.setData({ show: false });
|
|
},
|
|
formatDate(date) {
|
|
date = new Date(date);
|
|
return `${date.getMonth() + 1}/${date.getDate()}`;
|
|
},
|
|
onConfirm(event) {
|
|
this.setData({
|
|
show: false,
|
|
date: this.formatDate(event.detail),
|
|
});
|
|
},
|
|
});
|
|
```
|
|
|
|
### 选择多个日期
|
|
|
|
设置`type`为`multiple`后可以选择多个日期，此时`confirm`事件返回的 date 为数组结构，数组包含若干个选中的日期。
|
|
|
|
```html
|
|
<van-cell title="选择多个日期" value="{{ text }}" bind:click="onDisplay" />
|
|
<van-calendar
|
|
show="{{ show }}"
|
|
type="multiple"
|
|
bind:close="onClose"
|
|
bind:confirm="onConfirm"
|
|
/>
|
|
```
|
|
|
|
```js
|
|
Page({
|
|
data: {
|
|
text: '',
|
|
show: false,
|
|
},
|
|
|
|
onDisplay() {
|
|
this.setData({ show: true });
|
|
},
|
|
onClose() {
|
|
this.setData({ show: false });
|
|
},
|
|
onConfirm(event) {
|
|
this.setData({
|
|
show: false,
|
|
date: `选择了 ${event.detail.length} 个日期`,
|
|
});
|
|
},
|
|
});
|
|
```
|
|
|
|
### 选择日期区间
|
|
|
|
设置`type`为`range`后可以选择日期区间，此时`confirm`事件返回的 date 为数组结构，数组第一项为开始时间，第二项为结束时间。
|
|
|
|
```html
|
|
<van-cell title="选择日期区间" value="{{ date }}" bind:click="onDisplay" />
|
|
<van-calendar
|
|
show="{{ show }}"
|
|
type="range"
|
|
bind:close="onClose"
|
|
bind:confirm="onConfirm"
|
|
/>
|
|
```
|
|
|
|
```js
|
|
Page({
|
|
data: {
|
|
date: '',
|
|
show: false,
|
|
},
|
|
|
|
onDisplay() {
|
|
this.setData({ show: true });
|
|
},
|
|
onClose() {
|
|
this.setData({ show: false });
|
|
},
|
|
formatDate(date) {
|
|
date = new Date(date);
|
|
return `${date.getMonth() + 1}/${date.getDate()}`;
|
|
},
|
|
onConfirm(event) {
|
|
const [start, end] = event.detail;
|
|
this.setData({
|
|
show: false,
|
|
date: `${this.formatDate(start)} - ${this.formatDate(end)}`,
|
|
});
|
|
},
|
|
});
|
|
```
|
|
|
|
> Tips: 默认情况下，日期区间的起止时间不能为同一天，可以通过设置 allow-same-day 属性来允许选择同一天。
|
|
|
|
### 快捷选择
|
|
|
|
将`show-confirm`设置为`false`可以隐藏确认按钮，这种情况下选择完成后会立即触发`confirm`事件。
|
|
|
|
```html
|
|
<van-calendar show="{{ show }}" show-confirm="{{ false }}" />
|
|
```
|
|
|
|
### 自定义颜色
|
|
|
|
通过`color`属性可以自定义日历的颜色，对选中日期和底部按钮生效。
|
|
|
|
```html
|
|
<van-calendar show="{{ show }}" color="#07c160" />
|
|
```
|
|
|
|
### 自定义日期范围
|
|
|
|
通过`min-date`和`max-date`定义日历的范围，需要注意的是`min-date`和`max-date`的区间不宜过大，否则会造成严重的性能问题。
|
|
|
|
```html
|
|
<van-calendar
|
|
show="{{ show }}"
|
|
min-date="{{ minDate }}"
|
|
max-date="{{ maxDate }}"
|
|
/>
|
|
```
|
|
|
|
```js
|
|
Page({
|
|
data: {
|
|
show: false,
|
|
minDate: new Date(2010, 0, 1).getTime(),
|
|
maxDate: new Date(2010, 0, 31).getTime(),
|
|
},
|
|
});
|
|
```
|
|
|
|
### 自定义按钮文字
|
|
|
|
通过`confirm-text`设置按钮文字，通过`confirm-disabled-text`设置按钮禁用时的文字。
|
|
|
|
```html
|
|
<van-calendar
|
|
show="{{ show }}"
|
|
type="range"
|
|
confirm-text="完成"
|
|
confirm-disabled-text="请选择结束时间"
|
|
/>
|
|
```
|
|
|
|
### 自定义日期文案
|
|
|
|
通过传入`formatter`函数来对日历上每一格的内容进行格式化
|
|
|
|
```html
|
|
<van-calendar show="{{ show }}" type="range" formatter="{{ formatter }}" />
|
|
```
|
|
|
|
```js
|
|
Page({
|
|
data: {
|
|
formatter(day) {
|
|
const month = day.date.getMonth() + 1;
|
|
const date = day.date.getDate();
|
|
|
|
if (month === 5) {
|
|
if (date === 1) {
|
|
day.topInfo = '劳动节';
|
|
} else if (date === 4) {
|
|
day.topInfo = '五四青年节';
|
|
} else if (date === 11) {
|
|
day.text = '今天';
|
|
}
|
|
}
|
|
|
|
if (day.type === 'start') {
|
|
day.bottomInfo = '入住';
|
|
} else if (day.type === 'end') {
|
|
day.bottomInfo = '离店';
|
|
}
|
|
|
|
return day;
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
### 自定义弹出位置
|
|
|
|
通过`position`属性自定义弹出层的弹出位置，可选值为`top`、`left`、`right`。
|
|
|
|
```html
|
|
<van-calendar show="{{ show }}" round="false" position="right" />
|
|
```
|
|
|
|
### 日期区间最大范围
|
|
|
|
选择日期区间时，可以通过`max-range`属性来指定最多可选天数，选择的范围超过最多可选天数时，会弹出相应的提示文案。
|
|
|
|
```html
|
|
<van-calendar type="range" max-range="{{ 3 }}" />
|
|
```
|
|
|
|
### 自定义周起始日
|
|
|
|
通过 `first-day-of-week` 属性设置一周从哪天开始。
|
|
|
|
```html
|
|
<van-calendar first-day-of-week="{{ 1 }}" />
|
|
```
|
|
|
|
### 平铺展示
|
|
|
|
将`poppable`设置为`false`，日历会直接展示在页面内，而不是以弹层的形式出现。
|
|
|
|
```html
|
|
<van-calendar
|
|
title="日历"
|
|
poppable="{{ false }}"
|
|
show-confirm="{{ false }}"
|
|
class="calendar"
|
|
/>
|
|
```
|
|
|
|
```css
|
|
.calendar {
|
|
--calendar-height: 500px;
|
|
}
|
|
```
|
|
|
|
## API
|
|
|
|
### Props
|
|
|
|
| 参数 | 说明 | 类型 | 默认值 |
|
|
| --- | --- | --- | --- |
|
|
| type | 选择类型:<br>`single`表示选择单个日期，<br>`multiple`表示选择多个日期，<br>`range`表示选择日期区间 | _string_ | `single` |
|
|
| title | 日历标题 | _string_ | `日期选择` |
|
|
| color | 主题色，对底部按钮和选中日期生效 | _string_ | `#ee0a24` |
|
|
| min-date | 可选择的最小日期 | _timestamp_ | 当前日期 |
|
|
| max-date | 可选择的最大日期 | _timestamp_ | 当前日期的六个月后 |
|
|
| default-date | 默认选中的日期，`type`为`multiple`或`range`时为数组 | _timestamp \| timestamp[]_ | 今天 |
|
|
| row-height | 日期行高 | _number \| string_ | `64` |
|
|
| formatter | 日期格式化函数 | _(day: Day) => Day_ | - |
|
|
| poppable | 是否以弹层的形式展示日历 | _boolean_ | `true` |
|
|
| show-mark | 是否显示月份背景水印 | _boolean_ | `true` |
|
|
| show-title | 是否展示日历标题 | _boolean_ | `true` |
|
|
| show-subtitle | 是否展示日历副标题（年月） | _boolean_ | `true` |
|
|
| show-confirm | 是否展示确认按钮 | _boolean_ | `true` |
|
|
| confirm-text | 确认按钮的文字 | _string_ | `确定` |
|
|
| confirm-disabled-text | 确认按钮处于禁用状态时的文字 | _string_ | `确定` |
|
|
| first-day-of-week | 设置周起始日 | _0~6_ | `0` |
|
|
|
|
### Poppable Props
|
|
|
|
当 Calendar 的 `poppable` 为 `true` 时，支持以下 props:
|
|
|
|
| 参数 | 说明 | 类型 | 默认值 |
|
|
| --- | --- | --- | --- |
|
|
| show | 是否显示日历弹窗 | _boolean_ | `false` |
|
|
| position | 弹出位置，可选值为 `top` `right` `left` | _string_ | `bottom` |
|
|
| round | 是否显示圆角弹窗 | _boolean_ | `true` |
|
|
| close-on-click-overlay | 是否在点击遮罩层后关闭 | _boolean_ | `true` |
|
|
| safe-area-inset-bottom | 是否开启底部安全区适配 | _boolean_ | `true` |
|
|
|
|
### Range Props
|
|
|
|
当 Calendar 的 `type` 为 `range` 时，支持以下 props:
|
|
|
|
| 参数 | 说明 | 类型 | 默认值 |
|
|
| --- | --- | --- | --- |
|
|
| max-range | 日期区间最多可选天数，默认无限制 | _number \| string_ | - |
|
|
| range-prompt | 范围选择超过最多可选天数时的提示文案 | _string \| null_ | `选择天数不能超过 xx 天` |
|
|
| show-range-prompt | 范围选择超过最多可选天数时，是否展示提示文案 | _boolean_ | `true` |
|
|
| allow-same-day | 是否允许日期范围的起止时间为同一天 | _boolean_ | `false` |
|
|
|
|
### Day 数据结构
|
|
|
|
日历中的每个日期都对应一个 Day 对象，通过`formatter`属性可以自定义 Day 对象的内容。
|
|
|
|
| 键名 | 说明 | 类型 |
|
|
| --- | --- | --- |
|
|
| date | 日期对应的 Date 对象 | _Date_ |
|
|
| type | 日期类型，可选值为`selected`、`start`、`middle`、`end`、`disabled` | _string_ |
|
|
| text | 中间显示的文字 | _string_ |
|
|
| topInfo | 上方的提示信息 | _string_ |
|
|
| bottomInfo | 下方的提示信息 | _string_ |
|
|
|
|
### Events
|
|
|
|
| 事件名 | 说明 | 回调参数 |
|
|
| --- | --- | --- |
|
|
| select | 点击任意日期时触发 | _value: Date \| Date[]_ |
|
|
| unselect | 当 Calendar 的 `type` 为 `multiple` 时,点击已选中的日期时触发 | _value: Date_ |
|
|
| confirm | 日期选择完成后触发，若`show-confirm`为`true`，则点击确认按钮后触发 | _value: Date \| Date[]_ |
|
|
| open | 打开弹出层时触发 | - |
|
|
| close | 关闭弹出层时触发 | - |
|
|
| opened | 打开弹出层且动画结束后触发 | - |
|
|
| closed | 关闭弹出层且动画结束后触发 | - |
|
|
| over-range | 范围选择超过最多可选天数时触发 | - |
|
|
| click-subtitle `v1.8.1` | 点击日历副标题时触发 | _WechatMiniprogram.TouchEvent_ |
|
|
|
|
### Slots
|
|
|
|
| 名称 | 说明 |
|
|
| ------ | ------------------ |
|
|
| title | 自定义标题 |
|
|
| footer | 自定义底部区域内容 |
|
|
|
|
### 方法
|
|
|
|
通过 selectComponent 可以获取到 Calendar 实例并调用实例方法。
|
|
|
|
| 方法名 | 说明 | 参数 | 返回值 |
|
|
| ------ | ---------------------- | ---- | ------ |
|
|
| reset | 重置选中的日期到默认值 | - | - |
|