Skip to content

演示APP

推荐浏览器扫码安装

Calendar 日历

组件类型:WxCalendarComponentPublicInstance

日历组件,通过draw api来绘制日历,性能非常高且支持超多功能,让您纵享丝滑的使用日历(下列仅为部分功能描述)。

  • 多日历类型(周、月日历)
  • 多日期选择模式(日期单选、日期多选、日期范围选择)
  • 多滑动切换模式(纵、横、不滑动)
  • 多日历起始周几(周日、周一)
  • 自定义主题颜色
  • 自定义打点
  • 日期信息(农历日期、星座、星期几、生肖、天干地支、节气、节日)

平台兼容性

Android uni-app-xiOS uni-app-xweb小程序
×××

基础使用

通过日历组件的类型 WxCalendarComponentPublicInstance 调用 init 方法,即可在页面中显示日历(待uniapp x支持组件内监听页面生命周期后会省去本步骤)。

  • 选择日期时触发 change 事件
  • App 端使用页面级滚动时,需要在外层 scroll-view@scrollend 事件中调用 setScroll 方法,才能让日历在滚动页面中正确选中,弹窗日历则不需要。
vue
<template>
    <!-- #ifdef APP -->
    <scroll-view style="flex:1" @scrollend="scrollend">
    <!-- #endif -->
        <wx-calendar ref="wxCalendarRef" @change="calendarChange"></wx-calendar>
    <!-- #ifdef APP -->
    </scroll-view>
    <!-- #endif -->
</template>

<script setup>
    import type { WxCalendarEvent } from '@/uni_modules/wx-ui/libs/componentType.uts'
    let wxCalendarRef = ref<WxCalendarComponentPublicInstance | null>(null);
    
    let scrollend = (e: UniScrollEvent)=> {
        wxCalendarRef.value!.setScroll(e)
    }
    let calendarChange = (e : WxCalendarEvent)=> {
        console.log(e)
    }

    onReady(()=>{
        wxCalendarRef.value!.init();
    }) 
</script>

弹窗日历

通过设置 insert 属性为 false,并通过日历组件类型 WxCalendarComponentPublicInstance 调用 open 方法来使用弹窗日历。

  • 点击确定时触发 confirm 事件
vue
<template>
	<!-- #ifdef APP -->
	<scroll-view style="flex:1">
	<!-- #endif -->
        <button @click="openCalendar">打开日历</button>
        <wx-calendar ref="wxCalendarRef" :insert="false" @confirm="calendarConfirm"></wx-calendar>
	<!-- #ifdef APP -->
	</scroll-view>
	<!-- #endif -->
</template>

<script setup>
    import type { WxCalendarEvent } from '@/uni_modules/wx-ui/libs/componentType.uts'
    let wxCalendarRef = ref<WxCalendarComponentPublicInstance | null>(null);
    
    let openCalendar = ()=> {
        wxCalendarRef.value!.open()
    }
    let calendarConfirm = (e : WxCalendarEvent)=> {
        console.log(e)
    }
</script>

日历类型

通过设置 type 属性来指定日历类型,默认为 month

  • month 月日历
  • week 周日历

monthweek 类型可以通过 fold 设置为 true 来支持日历折叠。

vue
<wx-calendar type="month" :fold="true"></wx-calendar>

日历选择模式

通过设置 mode 属性来指定日历选择模式,默认为 single

通过 date 来指定默认选中日期。

  • single(单选)
  • multiple(多选)
  • range(范围选择)

日历单选

vue
<wx-calendar mode="single" :date="['2024-07-07']"></wx-calendar>

日历多选

vue
<wx-calendar mode="multiple"  :date="['2024-07-07', '2024-07-11', '2024-07-14']"></wx-calendar>

日历范围选择

vue
<wx-calendar mode="range" :date="['2024-07-09', '2024-07-29']"></wx-calendar>

以下三项仅在 mode="range" 时生效

日历范围同一天

通过设置 rangeSameDay 属性为 true,来允许日期范围开始日期与结束日期可以为同一天。

vue
<wx-calendar mode="range" :rangeSameDay="true"></wx-calendar>
选择范围内重选结束日期

通过设置 rangeEndRepick 属性为 true, 来允许选择完成后点击选择范围内日期来重选结束日期(默认为true)。

vue
<wx-calendar mode="range" :rangeEndRepick="true"></wx-calendar>
选择范围内遇到自定义打点禁用日期时进行截断

通过设置 rangeHaveDisableTruncation 属性为 true, 来允许选择范围内遇到打点禁用日期时进行截断,会以第一个打点禁用日期的前一个日期作为选择范围的结束日期。

vue
<wx-calendar mode="range" :rangeHaveDisableTruncation="true"></wx-calendar>

默认日期

在不使用 date 属性时,默认会使用今天作为默认日期。

mode 为不同模式时会有不同的效果。

  • single(单选) 模式会选中今天的日期
  • multiple(多选) 模式会将数组第一个变为今天的日期
  • range(范围选择) 模式会将开始日期变为今天的日期

如果不想使用默认日期可以将 useToday 设置为 false

vue
<wx-calendar mode="single" :useToday="false"></wx-calendar>

设置滑动切换模式

通过设置 slideSwitchMode 属性来指定滑动切换的模式,默认为 horizontal

  • horizontal 横向滑动切换
  • vertical 纵向滑动切换
  • none 不使用滑动切换
vue
<wx-calendar slideSwitchMode="vertical"></wx-calendar>

自定义日期范围

通过 startDateendDate 属性来指定日历的范围。

vue
<wx-calendar startDate="2024-07-09" endDate="2024-08-09"></wx-calendar>

农历显示

通过设置 lunar 属性为 true, 来启用日历的农历显示(默认为true)。

vue
<wx-calendar :lunar="true"></wx-calendar>

每月是否仅展示当月数据

通过设置 monthShowCurrentMonth 属性为 true, 来启用每月仅展示当月数据。

vue
<wx-calendar :monthShowCurrentMonth="true"></wx-calendar>

自定义主题颜色

通过设置 color 属性来指定自定义主题颜色,会通过 WXUI 的 API Color 自动生成自定义主题色的其余配色,让您可以随意设置主题色,且不会显得突兀。

vue
<wx-calendar color="#6ac695"></wx-calendar>

自定义打点

通过 selected 属性来实现自定义日期打点。

vue
<template>
    <!-- #ifdef APP -->
    <scroll-view style="flex:1" @scrollend="scrollend">
    <!-- #endif -->
        <wx-calendar ref="wxCalendarRef" :selected="selected"></wx-calendar>
    <!-- #ifdef APP -->
    </scroll-view>
    <!-- #endif -->
</template>

<script setup>
    import type { WxCanledarSelectedType } from '@/uni_modules/wx-ui/libs/componentType.uts'

    let wxCalendarRef = ref<WxCalendarComponentPublicInstance | null>(null);
    let selected = ref([
        {
            date: '2024-07-08',
            info: '打折',
            infoColor: '#00cc81',
            topInfo: '七五折',
            topInfoColor: '#00cc81',
            badge: true,
            badgeColor: '#00cc81',
            disabled: true
        },
        {
            date: '2024-07-11',
            info: '打折',
            infoColor: '#00cc81',
            badge: true,
            badgeColor: '#00cc81',
            disabled: false
        },
        {
            date: '2024-07-14',
            info: '打折',
            infoColor: '#00cc81',
            badge: true,
            badgeColor: '#00cc81',
            disabled: false
        }
    ] as WxCanledarSelectedType[])

    let scrollend = (e: ScrollEvent)=> {
        wxCalendarRef.value!.setScroll(e)
    }

    onReady(()=> {
        wxCalendarRef.value!.init()
    })
</script>

API

Props

名称类型默认值描述
dateArray<string>[]默认选中日期
typestringmonth日历类型
modestringsingle日历选择模式
useTodaybooleantrue是否使用默认日期
foldbooleanfalse是否使用折叠功能
colorstring(string.ColorString)#3c9cff主题色
itemHeightnumber60日历中每项日期的高度
cancelColorstring(string.ColorString)#333弹窗日历取消文字的颜色
confirmColorstring(string.ColorString)#333弹窗日历确认文字的颜色
startTextstring开始mode=range时,开始日期的底部提示文字
endTextstring结束mode=range时,结束日期的底部提示文字
startWeekstringmon日历以周几开始
selectedArray<WxCanledarSelectedType>[]自定义打点
lunarbooleantrue是否显示农历
startDatestring-日期范围-开始日期
endDatestring-日期范围-结束日期
rangeEndRepickbooleantruemode=range时,允许日期选择范围内重选结束日期
rangeSameDaybooleanfalsemode=range时,允许日期选择范围起始日期为同一天
rangeHaveDisableTruncationbooleanfalsemode=range时,允许日期选择范围内遇到打点禁用日期进行截断
monthShowCurrentMonthbooleanfalse每月仅显示当月日期
insertbooleantrue插入模式;ture:插入模式,false:弹窗模式
slideSwitchModestringhorizontal滑动切换模式
showMonthbooleantrue是否显示月份为背景
clearDatebooleantrue弹窗模式是否清空上次选择内容
maskClickbooleanfalse是否点击遮罩层关闭
disabledChoicebooleanfalse是否禁止点击日历
operationPositionstringtop弹窗日历取消和确认按钮的显示位置
confirmFullDatebooleanfalse弹窗日历确认按钮点击时是否需要选择完整日期

type

值名称描述
month月日历
week周日历

startWeek

值名称描述
mon周一
sun周日

slideSwitchMode

值名称描述
horizontal横向滑动
vertical纵向滑动
none不滑动

WxCanledarSelectedType

名称类型必填默认值描述
datestring-日期
infostring-日期下方文案
infoColorstring(string.ColorString)-日期下方文案的颜色
topInfostring-日期上方文案
topInfoColorstring(string.ColorString)-日期上文案的颜色
badgeboolean-是否显示圆点
badgeSizenumber-显示圆点的大小
badgeColorstring(string.ColorString)-显示圆点的颜色
badgePositionstring-显示圆点的位置
disabledboolean-日期禁用
badgePosition
值名称描述
top-left日期左上角
top-center日期上方中间
top-right日期右上角
bottom-left日期左下角
bottom-center日期下方中间
bottom-right日期右下角

Events

名称类型默认值描述
@close() => void-insertfalse 时,关闭弹窗日历时触发
@cancel() => void-insertfalse 时,点击取消按钮时触发
@confirm(event: WxCalendarEvent) => void-insertfalse 时,弹窗日历点击确定是触发
@change(event: WxCalendarEvent) => void-inserttrue 时,选择日期时触发
@init(event: WxCalendarEvent) => void-初始化时触发
@switch(event: WxCalendarSwitchEvent) => void-切换月份或周时触发
@foldSwitch(event: WxCalendarFoldSwitchEvent) => void-切换折叠状态时触发

WxCalendarEvent

WxCalendarEvent 的属性值
名称类型必填默认值描述
rangeWxCanledarRangeType-日期选择范围信息
multipleArray<string>-日期多选信息
modestring-日历选择模式
typestring-日历类型
yearnumber-
monthstring-
datestring-
dataWxLunarInfoType-日期农历信息
fullDatestring-日期的字符串形式
lunarstring-农历日期
extraInfoWxCanledarSelectedType-日期自定义打点信息
statusstring-日历折叠状态
WxCanledarRangeType 的属性值
名称类型必填默认值描述
beforestring-开始日期
afterstring-结束日期
dataArray<string> 是-开始与结束日期的数组
WxLunarInfoType 的属性值
名称类型必填默认值描述
lYearnumber-农历年
lMonthnumber-农历月
lDaynumber-农历日
Animalstring-生肖
IMonthCnstring-农历月的汉字表述
IDayCnstring-农历日的汉字表述
cYearnumber-
cMonthnumber-
cDaynumber-
gzYearstring-干支年
gzMonthstring-干支月
gzDaystring-干支日
isTodayboolean-当前日期是否为今天
isLeapboolean-是否跳农历日期
nWeeknumber-星期几
ncWeekstring-星期几的汉字表述
isTermboolean-当前日期是否为24节气之一
Termstring-节气名称
astrostring-星座
festivalstring-节日

WxCalendarSwitchEvent

名称类型必填默认值描述
typestring-日历类型
statusstring-日历折叠状态
yearnumber-
monthnumber-
fullDatestring-完整日期

WxCalendarFoldSwitchEvent

名称类型必填默认值描述
typestring-日历类型
statusstring-日历折叠状态

Slots

插槽名称描述
header日历头部插槽
operation弹窗日历取消和确认按钮插槽

v-slot:header

值名称描述
timeData目前所在月份时间数据

演示效果