uv-ui

# Calendar 日历

✈

组件名：uv-calendar

点击下载&安装 (opens new window)

此组件用于单个选择日期，范围选择日期等，日历被包裹在底部弹起的容器中。

注意： 此组件与Picker 选择器的日期选择模式有一定的重合之处，区别在于本组件为更专业的日期选择场景，能选择日期范围等。 另外Picker组件的日期模式可以配置更多的参数，如时、分、秒等，可以根据不同的使用场景进行选择。

# 平台兼容性

App（vue） App（nvue） H5 小程序 VUE2 VUE3
√ √ √ √ √ √

# 基本使用

  • 通过ref调用open()和close()控制日历的打开和关闭
  • 通过mode参数指定选择日期模式，包含单选 / 多选 / 范围选择。
<template>
	<view>
		<uv-calendar ref="calendar" @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	export default {
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：',e)
			}
		}
	}
</script>

# 日历模式

  • mode为single只能选择单个日期
  • mode为multiple可以选择多个日期
  • mode为range可以选择日期范围

# 单个日期模式

选择日期后，需要点击底部的确定按钮才能触发回调事件，回调参数为一个数组，有如下属性：

["2021-07-01"]

示例代码：

<template>
	<view>
		<uv-calendar ref="calendar" mode="single" @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	export default {
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：',e)
			}
		}
	}
</script>

# 多个日期模式

选择日期后，需要点击底部的确定按钮才能触发回调事件，回调参数为一个数组，有如下属性：

 ["2021-07-27", "2021-07-29", "2021-07-30"]

示例代码：

<template>
	<view>
		<uv-calendar ref="calendar" mode="multiple" @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	export default {
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：',e)
			}
		}
	}
</script>

# 日期范围模式

此模式用于选择一个日期范围，比如住酒店的入住到离店的日期范围，

此模式的返回参数如下：

["2021-07-27", "2021-07-28", "2021-07-29", "2021-07-30", "2021-07-31"]

示例代码：

<template>
	<view>
		<uv-calendar ref="calendar" mode="range" @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	export default {
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：',e)
			}
		}
	}
</script>

# 自定义主题颜色

组件可传入color参数，更改组件主题色

示例代码：

<template>
	<view>
		<uv-calendar ref="calendar" mode="range" color="#f56c6c" @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	export default {
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：',e)
			}
		}
	}
</script>

# 自定义文案

  • 组件可以通过formatter以函数的方式定义日期文案

  • 可以通过setFormatter返回的day参数，进行当天的日期参数设置，比如设置日期下方提示bottomInfo，禁止点击disabled等，具体根据day返回的值进行配置，如下示例：

	day: {
		bottomInfo: "打8折",
		date: Sat Jul 22 2023 08:00:00 GMT+0800 (中国标准时间) {},
		day: 22,
		disabled: true,
		dot: true,
		month: 7,
		topInfo: "",
		week: 6
	}

注意：

注意在页面的onReady生命周期获取ref再操作。

<template>
	<view>
		<uv-calendar
			ref="calendar"
			mode="range"
			startText="住店"
			endText="离店"
			confirmDisabledText="请选择离店日期"
		></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	export default {
		onReady() {
			this.$refs.calendar.setFormatter(this.formatter);
		},
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：', e)
			},
			formatter(day) {
				const d = new Date();
				let month = d.getMonth() + 1;
				const date = d.getDate();
				if (day.month == month && day.day == date + 3) {
					day.bottomInfo = '打8折';
					day.dot = true;
					day.disabled = true;
					console.log(day)
				}
				return day;
			}
		}
	}
</script>

# 日期最大范围

组件可以通过maxDate定义日期文案

<template>
	<view>
		<uv-calendar ref="calendar" :maxDate="maxDate" @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	const d = new Date()
	const year = d.getFullYear()
	let month = d.getMonth() + 1
	month = month < 10 ? `0${month}` : month
	const date = d.getDate()
	export default {
		data() {
			return {
				maxDate: `${year}-${month}-${date + 10}`,
			}
		},
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：',e)
			}
		}
	}
</script>

# 是否显示农历

组件可以通过showLunar定义是否显示农历

<template>
	<view>
		<uv-calendar ref="calendar" showLunar @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	export default {
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：',e)
			}
		}
	}
</script>

# 默认日期

组件可以通过defaultDate定义默认日期

<template>
	<view>
		<uv-calendar ref="calendar" mode="multiple" :defaultDate="defaultDateMultiple" @confirm="confirm"></uv-calendar>
		<button @click="open">打开</button>
	</view>
</template>
<script>
	const d = new Date()
	const year = d.getFullYear()
	let month = d.getMonth() + 1
	month = month < 10 ? `0${month}` : month
	const date = d.getDate()
	export default {
		data() {
			return {
				defaultDateMultiple: [`${year}-${month}-${date}`, `${year}-${month}-${date + 1}`, `${year}-${month}-${date + 2}`]
			}
		},
		methods: {
			open() {
				this.$refs.calendar.open();
			},
			confirm(e) {
				console.log('日历选择：', e)
			}
		}
	}
</script>

# 完整示例

完整示例下载地址

https://ext.dcloud.net.cn/plugin?name=uv-ui (opens new window)

# API

# Calendar Props

参数 说明 类型 默认值 可选值
title 标题内容 String 日期选择 -
showTitle 是否显示标题 Boolean true true | false
showSubtitle 是否显示副标题 Boolean true true | false
mode 日期类型选择 String single multiple-可以选择多个日期，range-选择日期范围（多个月需配合monthNum属性使用）
startText mode=range时，第一个日期底部的提示文字 String 开始 -
endText mode=range时，最后一个日期底部的提示文字 String 结束 -
customList 自定义列表 Array [] []
color 主题色，对底部按钮和选中日期有效 String #3c9cff -
minDate 最小的可选日期 Number | String 0 -
maxDate 最大可选日期 Number | String 0 -
defaultDate 默认选中的日期，mode为multiple或range是必须为数组格式 Array | String | Date null -
maxCount mode=multiple时，最多可选多少个日期 Number | String Number.MAX_SAFE_INTEGER -
rowHeight 日期行高 Number |String 56 -
showLunar 是否显示农历 Boolean false true | false
showMark 是否显示月份背景色 Boolean true true | false
confirmText 确定按钮的文字 String 确定 -
confirmDisabledText 确认按钮处于禁用状态时的文字 String 确定 -
closeOnClickOverlay 是否允许点击遮罩关闭日历 （注意：关闭事件需要自行处理，只会在开启closeOnClickOverlay后点击遮罩层执行close回调） Boolean false true | false
closeOnClickConfirm 是否允许点击确认按钮关闭日历，设置为false不影响confirm事件返回 Boolean true true | false
readonly 是否为只读状态，只读状态下禁止选择日期 Boolean false true | false
maxRange 日期区间最多可选天数，默认无限制，mode = range时有效 Number | String 无限制 -
rangePrompt 范围选择超过最多可选天数时的提示文案，mode = range时有效 String | null 选择天数不能超过 xx 天 -
showRangePrompt 范围选择超过最多可选天数时，是否展示提示文案，mode = range时有效 Boolean true true | false
allowSameDay 是否允许日期范围的起止时间为同一天，mode = range时有效 Boolean false true | false
round 圆角值，默认无圆角 String | Number 0 -
monthNum 最大展示的月份数量 String | Number 3 -

# Calendar Methods

方法名 说明
open 弹出日历组件
close 关闭日历组件，可能在:confirmClosePopup = "false"用到
setFormatter 日期格式化函数，使用方法及参数配置请参考自定义文案

# Calendar Events

事件名 说明 回调参数
@confirm 日期选择完成后触发，若show-confirm为true，则点击确认按钮后触发 选择日期相关的返回参数
@close 日历关闭时触发 可定义页面关闭时的回调事件
@change 点击日期触发 {day:'点击的日期',selected:'选中的日期'}

← Picker 选择器 →