uvx-ui

外观

Calendar 日历 ​

uvx-calendar 用于查看和选择日期，支持左右滑动切换月份、单选、多选、日期范围、日期限制、打点、农历、插入模式和底部弹窗模式。

平台兼容性 ​

AndroidiOS鸿蒙H5微信
3.9+4.11+4.61+4.0+4.41+

小程序端仅支持微信。

平台能力 ​

能力AndroidiOS鸿蒙H5微信
单选、多选和日期范围√√√√√
插入模式和底部弹窗模式√√√√√
日期限制、打点和自定义文案√√√√√
农历显示（1900 至 2100 年）√√√√√
左右滑动切换月份√√√√√
open、close 实例方法√√√√√

使用须知

  1. date 使用 YYYY-MM-DD 字符串。单选模式传字符串，多选和范围模式传字符串数组；空值或无效值会回退到今天。
  2. insert=false 为弹窗模式，通过 open() 打开并监听 confirm；insert=true 直接显示日历，点击日期时触发 change。
  3. mode="range" 需要选择完整起止日期才能确认；mode="multiple" 至少需要一个日期。readonly=true 时不能点击日期或确认，但仍可滑动浏览月份或打开年月选择器。
  4. clear-date=true 时每次打开弹窗都会按当前 date 重置选择；设为 false 会保留上一次未关闭前的内部选择状态。
  5. start-date、end-date 和 selected[].disable 都会禁用对应日期。日期必须使用本地日历格式，不要传 Date 对象或时间戳。
  6. 农历换算仅覆盖 1900 至 2100 年，超出范围时农历文字为空；日期选择本身仍可正常工作。
  7. 弹窗的滚动穿透行为由 uvx-popup 决定；页面存在独立滚动容器时，应在弹窗打开期间自行控制其滚动状态。

基础用法 ​

弹窗模式通过组件实例的 open() 方法打开，确认后从 confirm 事件获取结果。

vue
<template>
   <uvx-button text="选择日期" @click="handleOpen"></uvx-button>
   <uvx-calendar
      ref="uCalendar"
      @confirm="handleConfirm"
   ></uvx-calendar>
</template>

<script lang="uts" setup>
import type { ChangeEvent } from "@/uni_modules/uvx-ui/components/uvx-calendar/types/index.uts";

// 日历实例
const uCalendar = ref<UvxCalendarComponentPublicInstance | null>(null);

/**
 * 打开日历
 * @returns null
 */
const handleOpen = (): void => {
   uCalendar.value?.open();
};

/**
 * 处理确认结果
 * @param event 日历选择结果
 * @returns null
 */
const handleConfirm = (event: ChangeEvent): void => {
   console.log(event.fulldate);
};
</script>

插入模式 ​

设置 insert 后日历直接显示在页面中，日期变化通过 change 事件返回。

vue
<template>
   <uvx-calendar
      :insert="true"
      @change="handleChange"
   ></uvx-calendar>
</template>

滑动切换月份 ​

在六行日期网格上向左滑动进入下个月，向右滑动进入上个月。月份栏和星期栏保持固定；滑动距离不足时，日期网格会自动回弹到当前月份。

成功切换月份后触发 monthSwitch。点击月份标题可打开年月选择器，点击“今天”可回到并选中当前日期。

多选日期 ​

mode="multiple" 开启多选，date 数组设置默认日期；结果位于 event.multiple.data。

vue
<template>
   <uvx-calendar
      ref="uCalendar"
      mode="multiple"
      :date="DEFAULT_DATES"
      @confirm="handleConfirm"
   ></uvx-calendar>
</template>

<script lang="uts" setup>
const DEFAULT_DATES: string[] = ["2026-10-02", "2026-10-08", "2026-10-16"];
</script>

日期范围 ​

mode="range" 开启范围选择。allow-same-day 决定起止日期能否为同一天，结果位于 event.range。

vue
<template>
   <uvx-calendar
      ref="uCalendar"
      mode="range"
      :date="DEFAULT_RANGE"
      :allow-same-day="true"
      start-text="住店"
      end-text="离店"
      @confirm="handleConfirm"
   ></uvx-calendar>
</template>

<script lang="uts" setup>
const DEFAULT_RANGE: string[] = ["2026-10-02", "2026-10-08"];
</script>

日期限制 ​

start-date 和 end-date 限制可选范围，边界日期自身仍然可以选择。

vue
<template>
   <uvx-calendar
      ref="uCalendar"
      start-date="2026-10-02"
      end-date="2026-10-20"
      @confirm="handleConfirm"
   ></uvx-calendar>
</template>

打点和自定义文案 ​

selected 为指定日期添加顶部文案、底部文案、徽标或禁用状态。组件不会修改传入的打点对象，data 会随选择结果透传。

vue
<template>
   <uvx-calendar
      ref="uCalendar"
      :selected="SELECTED_DATES"
      @confirm="handleConfirm"
   ></uvx-calendar>
</template>

<script lang="uts" setup>
import type { SelectedItem } from "@/uni_modules/uvx-ui/components/uvx-calendar/types/index.uts";

const SELECTED_DATES: SelectedItem[] = [
   {
      date: "2026-10-02",
      info: "签到",
      infoColor: "#ff0000",
      badge: true,
   },
   {
      date: "2026-10-06",
      topinfo: "￥100",
      topinfoColor: "#19be6b",
      info: "余10",
   },
   {
      date: "2026-10-12",
      disable: true,
   },
];
</script>

农历和月份背景 ​

lunar 显示农历日期，show-month 控制日期网格中的月份背景数字。

vue
<template>
   <uvx-calendar
      :insert="true"
      :lunar="true"
      :show-month="true"
   ></uvx-calendar>
</template>

自定义颜色和弹窗 ​

颜色属性为空时跟随 uvx-ui 主题。显式设置 color、confirm-color 或 cancel-color 后使用指定颜色；round 和 close-on-click-overlay 控制弹窗外观与遮罩行为。

vue
<template>
   <uvx-calendar
      ref="uCalendar"
      mode="range"
      color="#f56c6c"
      confirm-color="#f56c6c"
      cancel-color="#606266"
      :round="12"
      :close-on-click-overlay="false"
      @confirm="handleConfirm"
   ></uvx-calendar>
</template>

API ​

Props ​

属性说明类型默认值平台
cancel-color取消按钮颜色；空值时使用主题次级文字色string""全部
confirm-color可确认状态的确认按钮颜色；空值时使用主题主色string""全部
title弹窗标题string""全部
color选中态、今天和范围状态的主题颜色；空值时跟随主题string""全部
date默认日期；单选传字符串，多选和范围传字符串数组string | string[]今天全部
selected日期打点、文案和禁用配置SelectedItem[][]全部
lunar是否显示农历booleanfalse全部
start-date可选开始日期，格式为 YYYY-MM-DDstring""全部
end-date可选结束日期，格式为 YYYY-MM-DDstring""全部
mode选择模式：空字符串为单选，另有 multiple、range"" | multiple | range""全部
insert是否直接插入页面；false 时使用弹窗booleanfalse全部
show-month是否显示日期网格中的月份背景booleantrue全部
clear-date每次打开弹窗时是否按 date 重置选择booleantrue全部
round底部弹窗顶部圆角，数字单位为 pxstring | number8全部
close-on-click-overlay点击遮罩时是否关闭弹窗booleantrue全部
start-text范围开始日期底部文案string开始（国际化）全部
end-text范围结束日期底部文案string结束（国际化）全部
allow-same-day范围起止日期是否允许为同一天，仅 range 生效booleanfalse全部
readonly是否禁止日期选择和确认，不影响月份浏览booleanfalse全部
u-style根节点自定义样式，CSS 字符串string""全部
u-class追加到根节点的外部样式类string""全部

Selected Options ​

属性说明类型必填
date日期，格式为 YYYY-MM-DD；无效日期会被忽略string是
info日期底部文案string否
infoColor底部文案颜色，选中或禁用状态下由状态样式覆盖string否
topinfo日期顶部文案string否
topinfoColor顶部文案颜色，选中或禁用状态下由状态样式覆盖string否
badge是否显示右上角徽标boolean否
disable是否禁止选择该日期boolean否
data随 extraInfo 透传的业务数据，组件不读取其字段UTSJSONObject | null否

Events ​

事件说明参数平台
change插入模式点击有效日期或回到今天后触发ChangeEvent全部
confirm弹窗模式点击可用的确认按钮后触发ChangeEvent全部
close弹窗关闭后触发-全部
monthSwitch左右滑动切月、回到今天跨月或月份选择确认后触发{ year: number, month: number }全部

ChangeEvent ​

字段说明类型
range范围状态，包含 before、after 和自然日数组 dataRangeStatus
multiple多选状态，包含日期数组 dataMultipleStatus
year最近操作日期的年份number
month最近操作日期的月份，范围为 1 至 12number
date最近操作日期的日number
fulldate最近操作日期，格式为 YYYY-MM-DDstring
lunar最近操作日期的农历信息LunarInfo
extraInfo最近操作日期匹配的打点项，无匹配时为 nullSelectedItem | null

LunarInfo ​

字段说明类型
lYear农历年份，超出支持范围时为 0number
lMonth农历月份，超出支持范围时为 0number
lDay农历日期，超出支持范围时为 0number
IMonthCn中文农历月份string
IDayCn中文农历日期string
isLeap是否为闰月boolean

Methods ​

方法说明参数返回值平台
open打开弹窗日历；插入模式调用无效-void全部
close关闭弹窗日历；插入模式调用无效-void全部

参考 ​

uvx-ui · uni-app x 组件库

Released under the MIT License.