WXUI

Appearance

演示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 周日历

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

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

日历选择模式 ​

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

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

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

日历单选 ​

vue
<wx-calendar mode="single" :date="['2026-03-01']"></wx-calendar>

日历多选 ​

vue
<wx-calendar mode="multiple"  :date="['2026-03-01', '2026-03-05', '2026-03-08']"></wx-calendar>

日历范围选择 ​

vue
<wx-calendar mode="range" :date="['2026-03-03', '2026-03-23']"></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>

自定义日期范围 ​

通过 startDate 与 endDate 属性来指定日历的范围。

vue
<wx-calendar startDate="2026-03-03" endDate="2026-04-03"></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: '2026-03-02',
            info: '打折',
            infoColor: '#00cc81',
            topInfo: '七五折',
            topInfoColor: '#00cc81',
            badge: true,
            badgeColor: '#00cc81',
            disabled: true
        },
        {
            date: '2026-03-05',
            info: '打折',
            infoColor: '#00cc81',
            badge: true,
            badgeColor: '#00cc81',
            disabled: false
        },
        {
            date: '2026-03-08',
            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-insert 为 false 时，关闭弹窗日历时触发
@cancel() => void-insert 为 false 时，点击取消按钮时触发
@confirm(event: WxCalendarEvent) => void-insert 为 false 时，弹窗日历点击确定是触发
@change(event: WxCalendarEvent) => void-insert 为 true 时，选择日期时触发
@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目前所在月份时间数据

演示效果 ​