【入门到实战】OpenHarmony开发：日历选择器组件（UICalendarPicker）

本文链接：https://blog.csdn.net/Androidbye/article/details/147589214

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

简介

UICalendarPicker，是一个基于open harmony基础组件开发的日历选择器组件，包含单日期选择、多日期选择和时间段选择的功能，让用户快捷选择日期。

快速开始

安装

ohpm install @hw-agconnect/ui-base
ohpm install @hw-agconnect/ui-calendar-picker

使用

// 在应用的入口文件进行初始化，比如EntryAbility.ets
import { UIBase } from '@hw-agconnect/ui-base';

onWindowStageCreate(windowStage: window.WindowStage): void {
  UIBase.init(windowStage);
}

// 在业务页面使用组件，比如xxx.ets
import { UICalendarPicker, TypePicker } from '@hw-agconnect/ui-calendar-picker';

UICalendarPicker({ type: TypePicker.SINGLE })

约束与限制

1.本示例仅支持标准系统上运行，支持设备：华为手机。

2.HarmonyOS系统：HarmonyOS 5.0.0 Release及以上。

3.DevEco Studio版本：DevEco Studio 5.0.0 Release及以上。

4.HarmonyOS SDK版本：HarmonyOS 5.0.0 Release SDK及以上。

子组件

可以包含单个子组件

接口

UICalendarPicker(option: UICalendarPickerOptions)

UICalendarPickerOptions对象说明

参数名	类型	必填	说明
type	TypePicker	否	日期选择器类型，默认值是SINGLE单日期
dialogType	DialogType	否	弹窗类型，支持常规弹窗和半模态弹窗，默认值DialogType.SHEET
swiperDirection	SwiperDirection	否	滑动方向，支持左右滑动和上下滑动，仅半模态弹窗支持上下滑动，默认值SwiperDirection.HORIZONTAL
customColor	ResourceColor	否	定制颜色，涉及所选日期背景色、当日字体、箭头、年月滚轮
customFontColor	ResourceColor	否	定制未选中文字颜色
startDayOfWeek	number	否	一周起始天，默认值是0，星期天，取值范围0 - 6之间的整数
startYear	number	否	切换年月的起始年份，默认是1900
endYear	number	否	切换年月的结束年份，默认是2100
rangeLimit	Date[]	否	设置可选范围，取数组第一项作为可选范围的开始日期，第二项作为可选范围的结束日期
disabledDates	Date[]	否	设置禁选日期，仅针对单日期、多日期生效
disableDayLabel	ResourceStr	否	设置禁选日期下方的文字
maxGap	number	否	设置起止日期之间的最大跨度，仅时间段类型生效
enableSelectTime	boolean	否	开启时间选择，默认值否，仅单日期类型以及横向滑动SwiperDirection.HORIZONTAL时生效
isMilitaryTime	boolean	否	时间选择是否24小时制，默认值否
sheetTitle	ResourceStr	否	设置半模态弹窗标题文字
sheetH	SheetSize \| Length	否	设置半模态弹窗高度，仅横向滑动SwiperDirection.HORIZONTAL生效
detents	[ (SheetSize \| Length), (SheetSize \| Length)?, (SheetSize \| Length)? ]	否	设置半模态弹窗高度档位，仅纵向滑动SwiperDirection.VERTICAL生效
selected	Date	否	选中的单日期，无默认值
selectDates	Date[]	否	选中的多日期、时间段。时间段只取前两个日期作为开始和结束日期。无默认值
yOffset	number	否	常规弹窗垂直方向偏移量，默认垂直居中对齐
customBuildPanel	() => void;	否	自定义触发弹窗的控件

TypePicker枚举说明

名称	描述
SINGLE	单日期
MULTIPLE	多日期
RANGE	时间段

DialogType枚举说明

名称	描述
DIALOG	常规弹窗
SHEET	半模态弹窗

SwiperDirection枚举说明

名称	描述
HORIZONTAL	水平方向
VERTICAL	垂直方向

事件

名称	功能描述
onSelected(callback: (date: Date \| Date[]) => void)	确认选择的回调
cancel(callback: () => void)	取消选择的回调
onClickDate(callback: (date: Date) => void)	点击日期的回调

支持情况说明

针对是否支持选择时间、设置禁选日期、设置可选范围、设置最大跨度，不同类型的日期选择器支持情况说明如下：

类型	时间选择enableSelectTime	禁选disabledDates	可选范围rangeLimit	跨度maxGap
单日期	√	√	√	x
多日期	x	√	√	x
时间段	x	x	√	√

异常情形说明

异常情形	对应结果
一周起始天不合法	取值默认值0
起始年份小于1900	取默认值1900
结束年份大于2100	取默认值2100
起始年份晚于结束年份	起始年份、结束年份均为默认值
针对单日期选择，选中日期早于起始年份	选中日期非法，置空处理，当前视图为系统时间所在月
针对单日期选择，选中日期晚于结束年份	选中日期非法，置空处理，当前视图为系统时间所在月
针对单日期选择，起始年份晚于当前系统日期，选中日期未设置	当前视图为起始年份第一个月
针对单日期选择，结束年份早于当前系统日期，选中日期未设置	当前视图为结束年份最后一个月
针对多日期选择，部分选中日期不在起止年份间	过滤掉不在起止年份间的日期，当前视图为第一个有效日期所在月
针对多日期选择，全部选中日期不在起止年份间	过滤所有非法日期，当前视图为系统时间所在月
针对时间段选择，开始日期不早于结束日期	默认值非法，置空处理，当前视图为系统时间所在月
针对时间段选择，开始日期或结束日期不在起止年份之间	默认值非法，置空处理，当前视图为系统时间所在月
针对可选范围rangeLimit，开始时间不早于结束时间	非法传参，参数不生效

示例

示例1

import { DialogType, SwiperDirection, TypePicker, UICalendarPicker } from '@hw-agconnect/ui-calendar-picker';

@Extend(Row)
function rowStyle() {
  .width('100%')
  .justifyContent(FlexAlign.SpaceBetween)
  .padding(16)
  .borderRadius(12)
  .backgroundColor($r('sys.color.ohos_id_color_card_bg'))
}

@Extend(Text)
function textStyle() {
  .margin({ right: 20 })
  .layoutWeight(1)
}

@Entry
@Component
struct CalendarPickerSample1 {
  @State selectedDate: Date = new Date(2024, 2, 1);
  @State selectedDates: Date[] = [];

  build() {
    NavDestination() {
      Scroll() {
        Column({ space: 10 }) {
          Row() {
            Text('常规弹窗：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.DIALOG,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.SHEET,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，纵向滑动：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.SHEET,
              swiperDirection: SwiperDirection.VERTICAL,
              startYear: 2024,
              endYear: 2024,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，支持选择时间：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.SHEET,
              enableSelectTime: true,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，设置禁选日期：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.SHEET,
              disabledDates: [
                new Date('2024-12-20'),
                new Date(),
                new Date('2024-12-26'),
                new Date('2025-01-20'),
                new Date('2025-01-26'),
              ]
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，设置range范围：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.SHEET,
              rangeLimit: [new Date()],
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，有默认值：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.SHEET,
              selected: new Date(2024, 2, 15),
              startYear: 2020,
              endYear: 2030
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，有默认值，支持选择时间：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              dialogType: DialogType.SHEET,
              selected: new Date('2024-12-25 14:20:20'),
              enableSelectTime: true,
              startYear: 2020,
              endYear: 2030
            })
          }.rowStyle()

        }
        .width('100%')
      }
      .padding(16)
      .height('100%')
      .edgeEffect(EdgeEffect.Spring)
      .align(Alignment.TopStart)
    }
    .title('选择单日期')
    .backgroundColor($r('sys.color.ohos_id_color_sub_background'))
  }
}

示例2

import { DialogType, SwiperDirection, TypePicker, UICalendarPicker } from '@hw-agconnect/ui-calendar-picker';

@Extend(Row)
function rowStyle() {
  .width('100%')
  .justifyContent(FlexAlign.SpaceBetween)
  .padding(16)
  .borderRadius(12)
  .backgroundColor($r('sys.color.ohos_id_color_card_bg'))
}

@Extend(Text)
function textStyle() {
  .margin({ right: 20 })
  .layoutWeight(1)
}

@Entry
@Component
struct CalendarPickerSample2 {
  @State selectedDate: Date = new Date(2024, 2, 1);
  @State selectedDates: Date[] = [];

  build() {
    NavDestination() {
      Scroll() {
        Column({ space: 20 }) {

          Row() {
            Text('常规弹窗：').textStyle()
            UICalendarPicker({
              type: TypePicker.MULTIPLE,
              dialogType: DialogType.DIALOG,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗：').textStyle()
            UICalendarPicker({
              type: TypePicker.MULTIPLE,
              dialogType: DialogType.SHEET,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，纵向滑动：').textStyle()
            UICalendarPicker({
              type: TypePicker.MULTIPLE,
              dialogType: DialogType.SHEET,
              swiperDirection: SwiperDirection.VERTICAL,
            })
          }.rowStyle()


          Row() {
            Text('半模态弹窗，设置禁选日期：').textStyle()
            UICalendarPicker({
              type: TypePicker.MULTIPLE,
              dialogType: DialogType.SHEET,
              disabledDates: [
                new Date('2024-12-20'),
                new Date(),
                new Date('2024-12-26'),
                new Date('2025-01-20'),
                new Date('2025-01-26'),
              ]
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，设置range范围：').textStyle()
            UICalendarPicker({
              type: TypePicker.MULTIPLE,
              dialogType: DialogType.SHEET,
              rangeLimit: [new Date()],
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，有默认值：').textStyle()
            UICalendarPicker({
              type: TypePicker.MULTIPLE,
              dialogType: DialogType.SHEET,
              selectDates: [new Date(2024, 2, 15)],
              startYear: 2020,
              endYear: 2030
            })
          }.rowStyle()

        }
        .width('100%')
      }
      .padding(16)
      .height('100%')
      .edgeEffect(EdgeEffect.Spring)
      .align(Alignment.TopStart)
    }
    .title('选择多日期')
    .backgroundColor($r('sys.color.ohos_id_color_sub_background'))
  }
}

示例3

import { DialogType, SwiperDirection, TypePicker, UICalendarPicker } from '@hw-agconnect/ui-calendar-picker';

@Extend(Row)
function rowStyle() {
  .width('100%')
  .justifyContent(FlexAlign.SpaceBetween)
  .padding(16)
  .borderRadius(12)
  .backgroundColor($r('sys.color.ohos_id_color_card_bg'))
}

@Extend(Text)
function textStyle() {
  .margin({ right: 20 })
  .layoutWeight(1)
}

@Entry
@Component
struct CalendarPickerSample3 {
  @State selectedDate: Date = new Date(2024, 2, 1);
  @State selectedDates: Date[] = [];

  build() {
    NavDestination() {
      Scroll() {
        Column({ space: 20 }) {

          Row() {
            Text('常规弹窗：').textStyle()
            UICalendarPicker({
              type: TypePicker.RANGE,
              dialogType: DialogType.DIALOG,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗：').textStyle()
            UICalendarPicker({
              type: TypePicker.RANGE,
              dialogType: DialogType.SHEET,
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，纵向滑动：').textStyle()
            UICalendarPicker({
              type: TypePicker.RANGE,
              dialogType: DialogType.SHEET,
              swiperDirection: SwiperDirection.VERTICAL,
            })
          }.rowStyle()


          Row() {
            Text('半模态弹窗，设置最大跨度：').textStyle()
            UICalendarPicker({
              type: TypePicker.RANGE,
              dialogType: DialogType.SHEET,
              swiperDirection: SwiperDirection.VERTICAL,
              maxGap: 3
            })
          }.rowStyle()

          Row() {
            Text('半模态弹窗，设置range范围：').textStyle()
            UICalendarPicker({
              type: TypePicker.RANGE,
              dialogType: DialogType.SHEET,
              swiperDirection: SwiperDirection.VERTICAL,
              rangeLimit: [new Date()],
            })
          }.rowStyle()


          Row() {
            Text('半模态弹窗，有默认值：').textStyle()
            UICalendarPicker({
              type: TypePicker.RANGE,
              dialogType: DialogType.SHEET,
              swiperDirection: SwiperDirection.VERTICAL,
              selectDates: [new Date(2024, 4, 15), new Date(2024, 4, 20)],
              startYear: 1940,
              endYear: 2050
            })
          }.rowStyle()

        }
        .width('100%')
      }
      .padding(16)
      .height('100%')
      .edgeEffect(EdgeEffect.Spring)
      .align(Alignment.TopStart)
    }
    .title('选择时间段')
    .backgroundColor($r('sys.color.ohos_id_color_sub_background'))
  }
}

示例4

import { DialogType, TypePicker, UICalendarPicker } from '@hw-agconnect/ui-calendar-picker';

@Extend(Row)
function rowStyle() {
  .width('100%')
  .justifyContent(FlexAlign.SpaceBetween)
  .padding(16)
  .borderRadius(12)
  .backgroundColor($r('sys.color.ohos_id_color_card_bg'))
}

@Extend(Text)
function textStyle() {
  .margin({ right: 20 })
  .layoutWeight(1)
}

@Entry
@Component
struct CalendarPickerSample4 {
  @State selectedDate: Date = new Date(2024, 2, 1);
  @State selectedDates: Date[] = [];

  build() {
    NavDestination() {
      Scroll() {
        Column({ space: 20 }) {
          Row() {
            Text('单日期-自定义主题色：').textStyle()
            UICalendarPicker({
              type: TypePicker.SINGLE,
              customColor: Color.Orange,
              selected: this.selectedDate,
              onSelected: (date) => {
                this.selectedDate = date as Date;
              }
            }) {
              Text(this.selectedDate.toLocaleDateString())
            }
          }.rowStyle()

          Row() {
            Text('多日期-自定义控件：').textStyle()
            UICalendarPicker({
              type: TypePicker.MULTIPLE,
              customColor: Color.Pink,
              selectDates: this.selectedDates,
              onSelected: (date) => {
                this.selectedDates = date as Date[];
              }
            }) {
              Scroll() {
                Column({ space: 4 }) {
                  if (this.selectedDates.length) {
                    ForEach(this.selectedDates, (item: Date) => {
                      Text(item.toLocaleDateString())
                    })
                  } else {
                    Text('请选择您的日期')
                  }
                }
              }.constraintSize({ maxHeight: 200, minHeight: 40 })
            }
          }.rowStyle()

          Row() {
            Text('半模态弹窗，点击日期有事件：').textStyle()
            UICalendarPicker({
              type: TypePicker.RANGE,
              dialogType: DialogType.SHEET,
              onClickDate: (date) => {
                this.getUIContext().getPromptAction().showToast({ message: '点击了日期:' + date });
              }
            })
          }.rowStyle()

        }
        .width('100%')
      }
      .padding(16)
      .height('100%')
      .edgeEffect(EdgeEffect.Spring)
      .align(Alignment.TopStart)
    }
    .title('定制参数')
    .backgroundColor($r('sys.color.ohos_id_color_sub_background'))
  }
}