更新记录

1.0.0（2025-12-07） 下载此版本

appx-calendar 是一款基于 uts 开发的多模式日历选择组件，支持单日期选择和日期范围选择，可自定义禁用日期、禁用周末、日期区间限制等功能，适配多端渲染，样式可通过自定义属性灵活调整。

平台兼容性

uni-app x(4.87)

appx-calendar 日历组件帮助文档

一、组件介绍

appx-calendar 是一款基于 uts 开发的多模式日历选择组件，支持单日期选择和日期范围选择，可自定义禁用日期、禁用周末、日期区间限制等功能，适配多端渲染，样式可通过自定义属性灵活调整。

二、使用方式

1. 基础引入

<template>
  <appx-calendar 
    mode="single" 
    :value="selectedDate"
    @confirm="handleConfirm"
  />
</template>

<script lang="uts" setup>
import appxCalendar from '@/components/appx-calendar/appx-calendar.vue';
const selectedDate = ref('2025-12-07');
const handleConfirm = (value) => {
  console.log('选中的日期：', value);
};
</script>

2. 范围选择示例

<appx-calendar 
  mode="range" 
  :value="['2025-12-01', '2025-12-10']"
  :minDate="2025-12-01"
  :maxDate="2025-12-31"
  :disableWeekend="true"
  @change="handleRangeChange"
/>

三、Props 配置项

四、事件说明

五、插槽说明

插槽使用示例

<appx-calendar>
  <template #date-format="{ year, month, day }">
    <!-- 自定义显示：添加日期后缀 -->
    <text>{{ day }}日</text>
  </template>
</appx-calendar>

六、样式自定义

组件通过 CSS 变量 --active-color 控制选中态颜色，也可通过 scoped 样式穿透修改默认样式：

/* 修改日历容器边框 */
:deep(.appx-calendar-container) {
  border: 1px solid #ddd;
  border-radius: 8px;
}

/* 修改禁用日期颜色 */
:deep(.appx-calendar-disabled) {
  color: #eee;
}

七、注意事项

1. 日期格式必须为 YYYY-MM-DD，非法格式（如 2025-13-01、2025-02-30）会被判定为禁用日期；
2. 范围选择时，若先选结束日期、后选开始日期，组件会自动交换顺序，保证开始日期 ≤ 结束日期；
3. disabledDates 数组中的日期需严格匹配 YYYY-MM-DD 格式，否则不会生效；
4. 切换年月时，组件会自动同步 picker 选择器的值，无需手动维护。

八、常见问题

Q1：选中日期后不触发 change 事件？

A1：单模式下点击日期会立即触发 change 事件；范围模式下需选完开始和结束日期后才触发，若仅选开始日期不会触发。

Q2：禁用周末不生效？

A2：检查 disableWeekend 是否设置为 true，同时确认日期未被 minDate/maxDate/disabledDates 额外限制。

Q3：范围选择的中间日期背景色不显示？

A3：需确保已选完整的开始和结束日期，且中间日期未被禁用，背景色由 --active-color 的透明色控制（默认 rgba(60, 156, 255, 0.1)）。