uView Next
4.1.6

外观

Calendar 日历

约 2115 字大约 7 分钟

2025-10-31

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

基本使用

  • 通过show绑定一个布尔变量用于打开或收起日历弹窗
<template>
	<un-calendar :show="show"></un-calendar>
	<un-button @click="show = true">打开</un-button>
</template>

<script setup lang="uts">
import { ref } from 'vue';

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

日历模式

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

单个日期模式

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

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

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);

const confirm = (value: string[]) => {
	console.log(value); //["2021-07-01"]
}
</script>

多个日期模式

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

示例代码：

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

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);

const confirm = (value: string[]) => {
	console.log(value);  //["2021-07-27", "2021-07-29", "2021-07-30"]
}
</script>

日期范围模式

此模式用于选择一个日期范围，返回开始日期和结束日期的数组，比如住酒店的入住到离店的日期范围。

示例代码：

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

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);

const confirm = (value: string[]) => {
	console.log(value);  //["2021-07-27", "2021-07-31"] ['开始日期', '结束日期']
}
</script>

插入模式

un-calendar-view组件可以直接插入到页面中，无需弹窗模式。

<template>
	<un-calendar-view @change="change"></un-calendar-view>
</template>

<script setup lang="uts">
const change = (value: string[]) => {
	console.log(value);
}
</script>

自定义主题颜色

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

示例代码：

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

<script setup lang="uts">
import { ref } from 'vue';
const show = ref(true);
const confirm = (value: string[]) => {
	console.log(value);
}
</script>

自定义文案

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

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

<script setup lang="uts">
import { ref, onReady } from 'vue';

const show = ref(true);

const confirm = (value: string[]) => {
	console.log(value);
}
</script>

日期最小/大范围

组件可以通过minDate定义最小可选日期，通过maxDate定义最大可选日期。

<template>
	<un-calendar mode="range" :minDate="minDate" :maxDate="maxDate" :show="show" @confirm="confirm"></un-calendar>
</template>

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);
const minDate = ref('2025-01-01');
const maxDate = ref('2026-12-31');

const confirm = (value: string[]) => {
	console.log(value);
}
</script>

是否显示农历

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

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

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);

const confirm = (value: string[]) => {
	console.log(value);
}
</script>

默认日期

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

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

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);
const defaultDateMultiple = ref([
	'2025-07-27',
	'2025-07-29',
	'2025-07-30'
]);

const confirm = (value: string[]) => {
	console.log(value);
}
</script>

禁止选择日期

组件可以通过disabledDate定义禁止被选择的日期。

<template>
	<un-calendar :disabledDate="disabledDate" :show="show" @confirm="confirm"></un-calendar>
</template>

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);
const disabledDate = ref(['2025-07-01', "2025-07-02"]);
// 也可以使用字符串形式：disabledDate: '2025-07-01'

const confirm = (value: string[]) => {
	console.log(value);
}
</script>

日期视图模式

组件可以通过viewMode定义日期视图模式，支持滚动模式、滑动模式和单页模式。

<template>
	<!-- 滚动模式 -->
	<un-calendar viewMode="scroll" :show="show" @confirm="confirm"></un-calendar>
	
	<!-- 滑动模式 -->
	<un-calendar viewMode="swiper" :show="show" @confirm="confirm"></un-calendar>
	
	<!-- 单页模式 -->
	<un-calendar viewMode="single" :show="show" @confirm="confirm"></un-calendar>
</template>

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);
const confirm = (value: string[]) => {
	console.log(value);
}
</script>

滑动方向

当viewMode为swiper时，可以通过swiperDirection定义滑动切换月份的方向。

<template>
	<!-- 水平滑动 -->
	<un-calendar viewMode="swiper" swiperDirection="horizontal" :show="show" @confirm="confirm"></un-calendar>
	
	<!-- 垂直滑动 -->
	<un-calendar viewMode="swiper" swiperDirection="vertical" :show="show" @confirm="confirm"></un-calendar>
</template>

<script setup lang="uts">
import { ref } from 'vue';

const show = ref(true);
const confirm = (value: string[]) => {
	console.log(value);
}
</script>

扩展日期

组件可以通过extend属性为指定日期添加额外信息，如徽章、底部文字、背景色等。

<template>
	<un-calendar :extend="extend" :show="show" @confirm="confirm"></un-calendar>
</template>

<script setup lang="uts">
import { ref, onReady } from 'vue';
import { padZero } from '@/uni_modules/uview-unix';
import type { CalendarExtend } from '@/uni_modules/uview-unix';

const show = ref(true);
const extend = computed((): CalendarExtend[] => {
	const d = new Date();
	const currentYear = d.getFullYear();
	const currentMonth = d.getMonth();
	
	return [
		{
			date: `${currentYear}-${padZero(currentMonth + 1)}-04`,
			badge: true,
			badgeText: '休',
			badgeTextColor: 'white',
			badgeSize: 16,
			badgeTextSize: 10,
			badgeRound: 4,
		},
		{
			date: `${currentYear}-${padZero(currentMonth + 1)}-06`,
			badge: true,
			badgeText: '班',
			badgeTextColor: 'white',
			badgeColor: 'rgba(255, 0, 0, 0.5)',
			badgeSize: 16,
			badgeTextSize: 10,
			badgeRound: 4,
		},
		{
			date: `${currentYear}-${padZero(currentMonth + 1)}-12`,
			bottomInfo: '休息',
			bottomInfoColor: 'red',
		},
		{
			date: `${currentYear}-${padZero(currentMonth + 1)}-15`,
			bottomInfo: '打球',
			bottomInfoColor: 'green',
		},
		{
			date: `${currentYear}-${padZero(currentMonth + 1)}-18`,
			bottomInfo: '跳舞',
			bottomInfoColor: 'white',
			bgColor: 'red',
			textColor: 'white',
			round: 5,
		},
		{
			date: `${currentYear}-${padZero(currentMonth + 1)}-20`,
			badge: true,
			isDot: true,
			badgePosition: 'bottom-center',
		},
		{
			date: `${currentYear}-${padZero(currentMonth + 1)}-21`,
			badge: true,
			isDot: true,
			badgeColor: 'blue',
			badgePosition: 'top-right',
		},
	];
});

const confirm = (value: string[]) => {
	console.log(value);
}
</script>

API

Props

参数说明类型默认值
show是否显示日历弹窗Booleanfalse
title标题内容String日期选择
showTitle是否显示标题Booleantrue
showSubtitle是否显示副标题Booleantrue
closeOnClickOverlay是否允许点击遮罩关闭日历Booleantrue
mode日期类型选择
Enum
single
switchMode切换模式，none-垂直滚动
Enum
single
shape选中的日期的形状
Enum
square
startTextmode=range时，第一个日期底部的提示文字String开始
endTextmode=range时，最后一个日期底部的提示文字String结束
color主题色，对底部按钮和选中日期有效String#3c9cff
minDate最小的可选日期Number | String0
maxDate最大可选日期Number | String0
defaultDate默认选中的日期，mode为multiple或range是必须为数组格式Array | String | Datenull
maxCountmode=multiple时，最多可选多少个日期Number | StringNumber.MAX_SAFE_INTEGER
rowHeight日期行高Number | String56
formatter日期格式化函数Functionnull
showLunar是否显示农历Booleanfalse
showMark是否显示月份背景色Booleantrue
readonly是否为只读状态，只读状态下禁止选择日期Booleanfalse
maxRange日期区间最多可选天数，默认无限制，mode = range时有效Number | String无限制
rangePrompt范围选择超过最多可选天数时的提示文案，mode = range时有效String选择天数不能超过 xx 天
showRangePrompt范围选择超过最多可选天数时，是否展示提示文案，mode = range时有效Booleantrue
monthNum最多展示月份数量Number | String3
allowSameDay是否允许日期范围的起止时间为同一天，mode = range时有效Booleanfalse
disabledDate禁止选择的日期Array | String-
weekdays星期几String日一二三四五六
buttonDisabled是否禁用底部按钮Booleanfalse
showConfirm是否显示确认按钮Booleantrue
round圆角值String | Number0
confirmText确认按钮文字String确定
confirmDisabledText确认按钮禁用时的文字String确定
firstDayOfWeek第一周从星期几开始
Enum
0
showOtherMonthDays是否显示其他月份的日期Booleanfalse
selectedHighlight是否选中日期时，添加背景高亮Booleantrue
viewMode日期视图模式，scroll-滚动模式，swiper-滑动模式，single-单页模式
Enum
single
swiperDirection滑动切换月份时的方向
Enum
horizontal
extend扩展日期Array<CalendarExtend>-

Event

事件名说明类型
confirm仅弹窗模式下有效，日期选择完成后触发，若show-confirm为true，则点击确认按钮后触发
Function
change选择日期时触发 （仅calendar-view有效）
Function
close日历关闭时触发
Function

数据类型


// 日历扩展数据类型，用于定义 `extend` 属性的数据结构。
type CalendarExtend = {
    date: string                               // 日期，格式为 YYYY-MM-DD
    bottomInfo?: string                        // 底部文字信息
    bottomInfoColor?: string                   // 底部文字颜色
    bgColor?: string                           // 背景颜色
    textColor?: string                         // 文字颜色
    round?: string | number                    // 圆角值
    badge?: boolean                            // 是否显示徽章
    badgeStyle?: object                        // 徽章样式
    badgeText?: string                         // 徽章文字
    badgeTextColor?: string                    // 徽章文字颜色
    badgeTextSize?: string | number            // 徽章文字大小
    badgeSize?: string | number                // 徽章大小
    badgeRound?: string | number               // 徽章圆角
    badgeOffset?: Array<number>                // 徽章偏移量
    badgeColor?: string                        // 徽章颜色
    isDot?: boolean                            // 是否显示为点
    badgePosition?: 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center' // 徽章位置
}

Copyright © 2026 uView Next