uview-plus

# Calendar 日历

打开

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

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

# 平台差异说明

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

# 基本使用

  • 通过show绑定一个布尔变量用于打开或收起日历弹窗。
  • 通过mode参数指定选择日期模式，包含单选/多选/范围选择。
<template>
	<view>
		<up-calendar :show="show"></up-calendar>
		<up-button @click="show = true">打开</up-button>
	</view>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
</script>

<template>
	<view>
		<up-calendar :show="show"></up-calendar>
		<up-button @click="show = true">打开</up-button>
	</view>
</template>

<script>
	export default {
		data() {
			return {
				show: false,
			}
		}
	}
</script>

# 单月切换模式

默认日历会在 scroll-view 中连续展示多个月份。设置 monthSwitch 后，日历改为非滚动的单月展示，用户通过顶部月份两侧按钮切换上一个月/下一个月，通过年份按钮切换上一年/下一年。该模式适合传统 PC 日历或空间固定的弹窗场景。

monthSwitch 只改变月份展示方式，不改变 mode、defaultDate、minDate、maxDate、monthNum 等选择逻辑。可切换月份范围仍由 minDate、maxDate 和 monthNum 决定。

单选示例：

<up-calendar
	:show="show"
	defaultDate="2023-06-15"
	minDate="2022-01-01"
	maxDate="2024-12-31"
	:monthNum="36"
	monthSwitch
	@confirm="confirm"
	@close="show = false"
></up-calendar>

日期区间示例：

<up-calendar
	:show="show"
	mode="range"
	:defaultDate="['2023-06-15', '2023-06-20']"
	minDate="2022-01-01"
	maxDate="2024-12-31"
	:monthNum="36"
	monthSwitch
	@confirm="confirm"
	@close="show = false"
></up-calendar>

多选示例：

<up-calendar
	:show="show"
	mode="multiple"
	:defaultDate="['2023-06-15', '2023-07-15', '2024-06-15']"
	minDate="2022-01-01"
	maxDate="2024-12-31"
	:monthNum="36"
	monthSwitch
	@confirm="confirm"
	@close="show = false"
></up-calendar>

# 单行日历 3.8.42

up-calendar-strip 为单行日历组件，适合首页快捷筛选、日程列表顶部切换等空间受限场景。支持：

  • 单行横向滚动日期
  • 左右切换月份，并受 minDate / maxDate 限制
  • 下拉展开完整月历（基于 up-calendar）
  • 选中日期、今天高亮、只读状态和自定义主题色

版本要求

up-calendar-strip 组件要求 uview-plus >= 3.8.42。

基础示例：

<up-calendar-strip
	v-model="date"
	:minDate="'2022-01-01'"
	:maxDate="'2026-12-31'"
></up-calendar-strip>

const date = ref('2024-11-29')

展开完整月历：

<up-calendar-strip
	v-model="date"
	:minDate="'2024-01-01'"
	:maxDate="'2024-12-31'"
	:fullCalendarProps="{ showLunar: true }"
	@change="onDateChange"
	@monthChange="onMonthChange"
	@toggleFull="onToggleFull"
></up-calendar-strip>

const date = ref('2024-11-29')

const onDateChange = (e) => {
	console.log(e.date, e.month, e.scene)
}

关闭完整月历，仅保留单行切换：

<up-calendar-strip
	v-model="date"
	:fullCalendar="false"
></up-calendar-strip>

# 单行日历 Props

参数 说明 类型 默认值 可选值
v-model 当前选中日期，支持日期字符串、时间戳或 Date String | Number | Date null -
minDate 最小可选日期 String | Number 0 -
maxDate 最大可选日期 String | Number 0 -
color 主题色，对选中日期和今天边框有效 String #3c9cff -
weekText 星期文案，按周一到周日传入 Array 多语言默认值 -
fullCalendar 是否支持下拉展开完整月历 Boolean true false
fullCalendarProps 透传给内嵌 up-calendar 的额外参数 Object {} -
fullMonthNum 完整月历可浏览月份数，仅未传 minDate / maxDate 时生效 String | Number 24 -
pullDownThreshold 下拉展开或上拉收起的手势触发阈值，单位 px String | Number 40 -
collapseAfterSelect 在完整月历中选择日期后是否自动收起 Boolean true false
readonly 是否只读，只读状态下禁止选择日期 Boolean false true
showToday 是否高亮今天 Boolean true false
monthFormat 顶部月份格式化模板，遵循 dayjs 格式 String - -
expandHint 收起状态提示文案 String 下拉展开月历 -
collapseHint 展开状态提示文案 String 上拉收起月历 -

# 单行日历 Events

事件名 说明 回调参数
change 日期变更时触发 { date, month, scene }
confirm 日期确认时触发，单行点击和完整月历选择都会触发 { date, month, scene }
monthChange 月份变更时触发 { month, scene }
toggleFull 展开或收起完整月历时触发 { show, source }
update:modelValue v-model 更新时触发 date

# 单行日历 Methods

方法名 说明
prevMonth 切换到上一个月份
nextMonth 切换到下一个月份
toggleFull 展开或收起完整月历

# 时间选择 3.8.53

up-calendar 支持在顶部增加时间选择区域，适合单选日期时间、区间开始/结束日期时间等场景。开启 enableTime 后，点击顶部时间区域会弹出居中的时间选择器。

<up-calendar
	:show="show"
	enableTime
	timePrecision="second"
	defaultTime="09:30:00"
	@confirm="confirm"
></up-calendar>

mode="range" 时，rangeResultMode="boundary" 会返回开始和结束两个日期时间字符串；rangeResultMode="all" 保持返回区间内所有日期，不展示时间选择。同日区间会校验结束时间不能早于开始时间。

# 日历模式

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

# 单个日期模式

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

["2021-07-01"]

示例代码：

<template>
	<up-calendar :show="show" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(true);
const mode = ref('single');

const confirm = (e) => {
  console.log(e);
};
</script>

<template>
	<up-calendar :show="show" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
				mode: 'single'
			}
		},
		methods: {
			confirm(e) {
				console.log(e);
			}
		}
	}
</script>

# 多个日期模式

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

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

示例代码：

<template>
	<up-calendar :show="show" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(true);
const mode = ref('multiple');

const confirm = (e) => {
  console.log(e);
};
</script>

<template>
	<up-calendar :show="show" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
				mode: 'multiple'
			}
		},
		methods: {
			confirm(e) {
				console.log(e);
			}
		}
	}
</script>

# 日期范围模式

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

此模式的返回参数如下：

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

示例代码：

<template>
	<up-calendar :show="show" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(true);
const mode = ref('range');

const confirm = (e) => {
  console.log(e);
};
</script>

<template>
	<up-calendar :show="show" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
				mode: 'range'
			}
		},
		methods: {
			confirm(e) {
				console.log(e);
			}
		}
	}
</script>

# 自定义主题颜色

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

示例代码：

<template>
	<up-calendar :show="show"
    color="#f56c6c" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(true);
const mode = ref('range');

const confirm = (e) => {
  console.log(e);
};
</script>

<template>
	<up-calendar :show="show"
    color="#f56c6c" :mode="mode" @confirm="confirm"></up-calendar>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
				mode: 'range'
			}
		},
		methods: {
			confirm(e) {
				console.log(e);
			}
		}
	}
</script>

# 自定义文案

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

注意：

微信小程序不支持通过props传递函数参数，所以组件内部暴露了一个setFormatter方法用于设置格式化方法，注意在页面的onReady生命周期获取ref再操作。

<template>
	<up-calendar
        startText="住店"
        endText="离店"
        confirmDisabledText="请选择离店日期"
        :formatter="formatter"
        :show="show"
        :mode="mode"
        @confirm="confirm"
		ref="calendar"
	>
    </up-calendar>
</template>

<script setup>
import { ref } from 'vue';
import { onReady } from '@dcloudio/uni-app';

const show = ref(true);
const mode = ref('range');

const confirm = (e) => {
  console.log(e);
};

const 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 = '有优惠';
    day.dot = true;
  }
  return day;
};

const onReady = () => {
  // 如果需要兼容微信小程序的话，需要用此写法
  $refs.calendar.setFormatter(formatter);
};
</script>

<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

<template>
	<up-calendar
        startText="住店"
        endText="离店"
        confirmDisabledText="请选择离店日期"
        :formatter="formatter"
        :show="show"
        :mode="mode"
        @confirm="confirm"
		ref="calendar"
	>
    </up-calendar>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
				mode: 'range'
			}
		},
		onReady() {
			// 如果需要兼容微信小程序的话，需要用此写法
			this.$refs.calendar.setFormatter(this.formatter)
		},
		methods: {
			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 = '有优惠'
					day.dot = true
				}
				return day
		    }
		}
	}
</script>

<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

# 日期最大范围

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

<template>
	<up-calendar
        :maxDate="maxDate"
        :show="show"
        @confirm="confirm">
	</up-calendar>
</template>

<script setup>
import { ref } from 'vue';

const d = new Date();
const year = d.getFullYear();
let month = d.getMonth() + 1;
month = month < 10 ? `0${month}` : month;
const date = d.getDate();

const show = ref(true);
const maxDate = `${year}-${month}-${date + 10}`;

const confirm = (e) => {
  console.log(e);
};
</script>


<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

<template>
	<up-calendar
        :maxDate="maxDate"
        :show="show"
        @confirm="confirm">
	</up-calendar>
</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 {
				show: true,
				maxDate: `${year}-${month}-${date + 10}`,
			}
		},
		methods: {
			confirm(e) {
				console.log(e);
			},
		}
	}
</script>

<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

# 是否显示农历

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

<template>
	<up-calendar
        showLunar
        :show="show"
        @confirm="confirm">
	</up-calendar>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(true);

const confirm = (e) => {
  console.log(e);
};
</script>

<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

<template>
	<up-calendar
        showLunar
        :show="show"
        @confirm="confirm">
	</up-calendar>
</template>

<script>
	export default {
		data() {
			return {
				show: true,
			}
		},
		methods: {
			confirm(e) {
				console.log(e);
			},
		}
	}
</script>

<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

# 默认日期

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

<template>
	<up-calendar
        :defaultDate="defaultDateMultiple"
        :show="show"
        mode="multiple"
        @confirm="confirm">
	</up-calendar>
</template>

<script setup>
import { ref } from 'vue';

const d = new Date();
const year = d.getFullYear();
let month = d.getMonth() + 1;
month = month < 10 ? `0${month}` : month;
const date = d.getDate();

const show = ref(true);
const defaultDateMultiple = [`${year}-${month}-${date}`, `${year}-${month}-${date + 1}`, `${year}-${month}-${date + 2}`];

const confirm = (e) => {
  console.log(e);
};
</script>


<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

<template>
	<up-calendar
        :defaultDate="defaultDateMultiple"
        :show="show"
        mode="multiple"
        @confirm="confirm">
	</up-calendar>
</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 {
				show: true,
				defaultDateMultiple: [`${year}-${month}-${date}`, `${year}-${month}-${date + 1}`, `${year}-${month}-${date + 2}`],
			}
		},
		methods: {
			confirm(e) {
				console.log(e);
			},
		}
	}
</script>

<style lang="scss" scoped>
	.title{
		color: $u-primary;
		text-align: center;
		padding: 20rpx 0 0 0;
	}
</style>

# 右侧演示页面源代码地址

点击以下链接以查看右侧演示页面的源码


 github  gitee

# API

# Props

参数 说明 类型 默认值 可选值
title 标题内容 String 日期选择 -
showTitle 是否显示标题 Boolean true false
showSubtitle 是否显示副标题 Boolean 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 -
formatter 日期格式化函数(如需兼容微信小程序，则只能通过setFormatter方法) Function null -
showLunar 是否显示农历 Boolean false true
showMark 是否显示月份背景色 Boolean true false
confirmText 确定按钮的文字 String 确定 -
confirmDisabledText 确认按钮处于禁用状态时的文字 String 确定 -
show 是否显示日历弹窗 Boolean false true
closeOnClickOverlay 是否允许点击遮罩关闭日历 （注意：关闭事件需要自行处理，只会在开启closeOnClickOverlay后点击遮罩层执行close回调） Boolean false true
readonly 是否为只读状态，只读状态下禁止选择日期 Boolean false true
maxRange 日期区间最多可选天数，默认无限制，mode = range时有效 Number | String 无限制 -
rangePrompt 范围选择超过最多可选天数时的提示文案，mode = range时有效 String | null 选择天数不能超过 xx 天 -
showRangePrompt 范围选择超过最多可选天数时，是否展示提示文案，mode = range时有效 Boolean true false
allowSameDay 是否允许日期范围的起止时间为同一天，mode = range时有效 Boolean false true
rangeResultMode 3.8.48 区间模式确认返回值格式，all 返回区间内所有日期，boundary 仅返回起止日期 String all boundary
enableTime 3.8.53 是否开启顶部时分秒选择，支持 single 与 range 首尾日期时间 Boolean false true
timePrecision 3.8.53 时间选择精度 String minute hour、minute、second
defaultTime 3.8.53 默认时间，支持 HH / HH:mm / HH:mm:ss String - -
round 圆角值，默认无圆角 String | Number 0 -
monthNum 最大展示的月份数量 String | Number 3 -
monthSwitch 3.8.7 是否启用非滚动的单月切换模式，开启后通过顶部月份和年份按钮切换 Boolean false true
showToday 3.8.37 是否显示今天按钮，3.8.54 起点击今天按钮会同步选中今天并遵循 showConfirm 行为 Boolean true false
weekText 星期文案，可用于多语言。 Array ['一', '二', '三', '四', '五', '六', '日'] -
forbidDays 单选与多选禁止选中的日期列表，mode!=range时有效。 Array [] -
forbidDaysToast 单选与多选禁止选中的日期选择时提示 String 该日期已禁用 -
pageInline 3.5.3 页面内插入模式 Boolean false true

# Methods

方法名 说明
setFormatter 为兼容微信小程序而暴露的内部方法，见上方说明

# Event

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

← Keyboard 键盘 →