演示APP
Calendar 日历
组件类型:WxCalendarComponentPublicInstance
日历组件,通过draw api来绘制日历,性能非常高且支持超多功能,让您纵享丝滑的使用日历(下列仅为部分功能描述)。
- 多日历类型(周、月日历)
- 多日期选择模式(日期单选、日期多选、日期范围选择)
- 多滑动切换模式(纵、横、不滑动)
- 多日历起始周几(周日、周一)
- 自定义主题颜色
- 自定义打点
- 日期信息(农历日期、星座、星期几、生肖、天干地支、节气、节日)
平台兼容性
Android uni-app-x | iOS uni-app-x | web | 小程序 |
---|---|---|---|
√ | × | × | × |
基础使用
通过日历组件的类型 WxCalendarComponentPublicInstance
调用 init
方法,即可在页面中显示日历(待uniapp x支持组件内监听页面生命周期后会省去本步骤)。
- 选择日期时触发
change
事件 - 在
App
端使用页面级滚动时,需要在外层scroll-view
的@scrollend
事件中调用setScroll
方法,才能让日历在滚动页面中正确选中,弹窗日历则不需要。
<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
事件
<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
来支持日历折叠。
<wx-calendar type="month" :fold="true"></wx-calendar>
日历选择模式
通过设置 mode
属性来指定日历选择模式,默认为 single
。
通过 date
来指定默认选中日期。
single(单选)
multiple(多选)
range(范围选择)
日历单选
<wx-calendar mode="single" :date="['2024-07-07']"></wx-calendar>
日历多选
<wx-calendar mode="multiple" :date="['2024-07-07', '2024-07-11', '2024-07-14']"></wx-calendar>
日历范围选择
<wx-calendar mode="range" :date="['2024-07-09', '2024-07-29']"></wx-calendar>
以下三项仅在 mode="range"
时生效
日历范围同一天
通过设置 rangeSameDay
属性为 true
,来允许日期范围开始日期与结束日期可以为同一天。
<wx-calendar mode="range" :rangeSameDay="true"></wx-calendar>
选择范围内重选结束日期
通过设置 rangeEndRepick
属性为 true
, 来允许选择完成后点击选择范围内日期来重选结束日期(默认为true)。
<wx-calendar mode="range" :rangeEndRepick="true"></wx-calendar>
选择范围内遇到自定义打点禁用日期时进行截断
通过设置 rangeHaveDisableTruncation
属性为 true
, 来允许选择范围内遇到打点禁用日期时进行截断,会以第一个打点禁用日期的前一个日期作为选择范围的结束日期。
<wx-calendar mode="range" :rangeHaveDisableTruncation="true"></wx-calendar>
默认日期
在不使用 date
属性时,默认会使用今天作为默认日期。
mode
为不同模式时会有不同的效果。
single(单选)
模式会选中今天的日期multiple(多选)
模式会将数组第一个变为今天的日期range(范围选择)
模式会将开始日期变为今天的日期
如果不想使用默认日期可以将 useToday
设置为 false
。
<wx-calendar mode="single" :useToday="false"></wx-calendar>
设置滑动切换模式
通过设置 slideSwitchMode
属性来指定滑动切换的模式,默认为 horizontal
。
- horizontal 横向滑动切换
- vertical 纵向滑动切换
- none 不使用滑动切换
<wx-calendar slideSwitchMode="vertical"></wx-calendar>
自定义日期范围
通过 startDate
与 endDate
属性来指定日历的范围。
<wx-calendar startDate="2024-07-09" endDate="2024-08-09"></wx-calendar>
农历显示
通过设置 lunar
属性为 true
, 来启用日历的农历显示(默认为true)。
<wx-calendar :lunar="true"></wx-calendar>
每月是否仅展示当月数据
通过设置 monthShowCurrentMonth
属性为 true
, 来启用每月仅展示当月数据。
<wx-calendar :monthShowCurrentMonth="true"></wx-calendar>
自定义主题颜色
通过设置 color
属性来指定自定义主题颜色,会通过 WXUI
的 API Color
自动生成自定义主题色的其余配色,让您可以随意设置主题色,且不会显得突兀。
<wx-calendar color="#6ac695"></wx-calendar>
自定义打点
通过 selected
属性来实现自定义日期打点。
<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
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
date | Array<string> | [] | 默认选中日期 |
type | string | month | 日历类型 |
mode | string | single | 日历选择模式 |
useToday | boolean | true | 是否使用默认日期 |
fold | boolean | false | 是否使用折叠功能 |
color | string(string.ColorString) | #3c9cff | 主题色 |
itemHeight | number | 60 | 日历中每项日期的高度 |
cancelColor | string(string.ColorString) | #333 | 弹窗日历取消文字的颜色 |
confirmColor | string(string.ColorString) | #333 | 弹窗日历确认文字的颜色 |
startText | string | 开始 | mode=range时,开始日期的底部提示文字 |
endText | string | 结束 | mode=range时,结束日期的底部提示文字 |
startWeek | string | mon | 日历以周几开始 |
selected | Array<WxCanledarSelectedType> | [] | 自定义打点 |
lunar | boolean | true | 是否显示农历 |
startDate | string | - | 日期范围-开始日期 |
endDate | string | - | 日期范围-结束日期 |
rangeEndRepick | boolean | true | mode=range时,允许日期选择范围内重选结束日期 |
rangeSameDay | boolean | false | mode=range时,允许日期选择范围起始日期为同一天 |
rangeHaveDisableTruncation | boolean | false | mode=range时,允许日期选择范围内遇到打点禁用日期进行截断 |
monthShowCurrentMonth | boolean | false | 每月仅显示当月日期 |
insert | boolean | true | 插入模式;ture:插入模式,false:弹窗模式 |
slideSwitchMode | string | horizontal | 滑动切换模式 |
showMonth | boolean | true | 是否显示月份为背景 |
clearDate | boolean | true | 弹窗模式是否清空上次选择内容 |
maskClick | boolean | false | 是否点击遮罩层关闭 |
disabledChoice | boolean | false | 是否禁止点击日历 |
operationPosition | string | top | 弹窗日历取消和确认按钮的显示位置 |
confirmFullDate | boolean | false | 弹窗日历确认按钮点击时是否需要选择完整日期 |
type
值名称 | 描述 |
---|---|
month | 月日历 |
week | 周日历 |
startWeek
值名称 | 描述 |
---|---|
mon | 周一 |
sun | 周日 |
slideSwitchMode
值名称 | 描述 |
---|---|
horizontal | 横向滑动 |
vertical | 纵向滑动 |
none | 不滑动 |
WxCanledarSelectedType
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
date | string | 是 | - | 日期 |
info | string | 否 | - | 日期下方文案 |
infoColor | string(string.ColorString) | 否 | - | 日期下方文案的颜色 |
topInfo | string | 否 | - | 日期上方文案 |
topInfoColor | string(string.ColorString) | 否 | - | 日期上文案的颜色 |
badge | boolean | 否 | - | 是否显示圆点 |
badgeSize | number | 否 | - | 显示圆点的大小 |
badgeColor | string(string.ColorString) | 否 | - | 显示圆点的颜色 |
badgePosition | string | 否 | - | 显示圆点的位置 |
disabled | boolean | 否 | - | 日期禁用 |
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 的属性值
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
range | WxCanledarRangeType | 是 | - | 日期选择范围信息 |
multiple | Array<string> | 是 | - | 日期多选信息 |
mode | string | 是 | - | 日历选择模式 |
type | string | 是 | - | 日历类型 |
year | number | 是 | - | 年 |
month | string | 是 | - | 月 |
date | string | 是 | - | 日 |
data | WxLunarInfoType | 否 | - | 日期农历信息 |
fullDate | string | 否 | - | 日期的字符串形式 |
lunar | string | 是 | - | 农历日期 |
extraInfo | WxCanledarSelectedType | 否 | - | 日期自定义打点信息 |
status | string | 否 | - | 日历折叠状态 |
WxCanledarRangeType 的属性值
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
before | string | 是 | - | 开始日期 |
after | string | 是 | - | 结束日期 |
data | Array<string> 是 | - | 开始与结束日期的数组 |
WxLunarInfoType 的属性值
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
lYear | number | 是 | - | 农历年 |
lMonth | number | 是 | - | 农历月 |
lDay | number | 是 | - | 农历日 |
Animal | string | 是 | - | 生肖 |
IMonthCn | string | 是 | - | 农历月的汉字表述 |
IDayCn | string | 是 | - | 农历日的汉字表述 |
cYear | number | 是 | - | 年 |
cMonth | number | 是 | - | 月 |
cDay | number | 是 | - | 日 |
gzYear | string | 是 | - | 干支年 |
gzMonth | string | 是 | - | 干支月 |
gzDay | string | 是 | - | 干支日 |
isToday | boolean | 是 | - | 当前日期是否为今天 |
isLeap | boolean | 是 | - | 是否跳农历日期 |
nWeek | number | 是 | - | 星期几 |
ncWeek | string | 是 | - | 星期几的汉字表述 |
isTerm | boolean | 是 | - | 当前日期是否为24节气之一 |
Term | string | 是 | - | 节气名称 |
astro | string | 是 | - | 星座 |
festival | string | 是 | - | 节日 |
WxCalendarSwitchEvent
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
type | string | 是 | - | 日历类型 |
status | string | 是 | - | 日历折叠状态 |
year | number | 是 | - | 年 |
month | number | 是 | - | 月 |
fullDate | string | 是 | - | 完整日期 |
WxCalendarFoldSwitchEvent
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
type | string | 是 | - | 日历类型 |
status | string | 是 | - | 日历折叠状态 |
Slots
插槽名称 | 描述 |
---|---|
header | 日历头部插槽 |
operation | 弹窗日历取消和确认按钮插槽 |
v-slot:header
值名称 | 描述 |
---|---|
timeData | 目前所在月份时间数据 |