#跟着若城学鸿蒙# UI组件篇-TimePicker及其属性

Huang兄

740人浏览 · 2025-05-18 13:35:47

Huang兄 · 2025-05-18 13:35:47 发布

前言

在现代应用开发中，时间选择器（TimePicker）是一个常见且重要的组件，广泛应用于各种场景，如日程安排、闹钟设置、事件提醒等。ArkUI 提供了一个强大且灵活的 TimePicker 组件，支持 24 小时制和 12 小时制的切换，并允许用户自定义时间格式、起始和结束时间等参数。本文将详细介绍 ArkUI 中的 TimePicker 组件，包括其接口、属性、事件、使用示例以及最佳实践。

TimePicker 组件概述

TimePicker 组件是一个灵活的时间选择工具，支持 24 小时制和 12 小时制的切换，并允许用户自定义时间格式、起始和结束时间等参数。此外，它还提供了丰富的事件回调和样式设置选项，以满足不同场景下的需求。

特点

灵活的时间格式：支持 24 小时制和 12 小时制，用户可以根据需求自由切换。
自定义时间范围：可以设置时间选择器的起始和结束时间，限制用户的选择范围。
丰富的样式设置：支持自定义文本样式、选中项样式等，满足个性化需求。
事件回调：提供丰富的事件回调，方便开发者处理用户选择的时间。

接口

TimePicker 组件的接口定义如下：

TimePicker(options?: TimePickerOptions)

参数

参数名	类型	是否必填	描述
options	TimePickerOptions	否	配置时间选择组件的参数。

TimePickerOptions 对象说明

TimePickerOptions 对象用于配置 TimePicker 组件的参数，具体如下：

参数名	类型	是否必填	描述
selected	Date	否	设置选中项的时间。默认值：当前系统时间。从 API version 10 开始，该参数支持双向绑定变量。
format	TimePickerFormat	否	指定需要显示的 TimePicker 的格式。默认值：TimePickerFormat.HOUR_MINUTE。从 API version 11 开始，该接口支持在原子化服务中使用。
start	Date	否	指定时间选择组件的起始时间。默认值：Date(0, 0, 0, 0, 0, 0)，仅生效设置日期的小时和分钟。设定了 start、end，且为非默认值的场景下，loop 不生效。从 API version 18 开始，该接口支持在原子化服务中使用。
end	Date	否	指定时间选择组件的结束时间。默认值：Date(0, 0, 0, 23, 59, 59)，仅生效设置日期的小时和分钟。设定了 start、end，且为非默认值的场景下，loop 不生效。从 API version 18 开始，该接口支持在原子化服务中使用。

TimePickerFormat 枚举说明

枚举值	描述
HOUR_MINUTE	按照小时和分显示。
HOUR_MINUTE_SECOND	按照小时、分钟和秒显示。

属性

TimePicker 组件除支持通用属性外，还支持以下属性：

useMilitaryTime

useMilitaryTime(value: boolean)

设置展示时间是否为 24 小时制。如果展示时间为 12 小时制，上下午与小时无联动。

参数

参数名	类型	描述
value	boolean	是否使用 24 小时制。

disappearTextStyle

disappearTextStyle(value: PickerTextStyle)

设置所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。

参数

参数名	类型	描述
value	PickerTextStyle	文本样式。

textStyle

textStyle(value: PickerTextStyle)

设置所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。

参数

参数名	类型	描述
value	PickerTextStyle	文本样式。

selectedTextStyle

selectedTextStyle(value: PickerTextStyle)

设置选中项的文本颜色、字号和字体粗细。

参数

参数名	类型	描述
value	PickerTextStyle	文本样式。

loop

loop(value: boolean)

设置循环模式的启用状态。

参数

参数名	类型	描述
value	boolean	是否启用循环模式。

dateTimeOptions

dateTimeOptions(value: DateTimeOptions)

设置时分秒是否显示前导 0。

参数

参数名	类型	描述
value	DateTimeOptions	时分秒显示选项。

enableHapticFeedback

enableHapticFeedback(enable: boolean)

设置是否支持触控反馈。

参数

参数名	类型	描述
enable	boolean	是否支持触控反馈。默认值：true，表示开启触控反馈。设置为 true 后，其是否生效取决于系统的硬件支持情况。

enableCascade

enableCascade(enable: boolean)

在设置 12 小时制时，上午和下午的标识会根据小时数自动切换。

参数

参数名	类型	描述
enable	boolean	是否启用自动切换。默认值：false，表示不开启自动切换。

digitalCrownSensitivity

digitalCrownSensitivity(sensitivity: Optional<CrownSensitivity>)

设置表冠灵敏度。

参数

参数名	类型	描述
sensitivity	Optional<CrownSensitivity>	表冠响应灵敏度。默认值：CrownSensitivity.MEDIUM，响应速度适中。

事件

TimePicker 组件除支持通用事件外，还支持以下事件：

onChange

onChange(callback: (value: TimePickerResult) => void)

选择时间时触发该事件。

参数

参数名	类型	描述
value	TimePickerResult	24 小时制时间。

onEnterSelectedArea

onEnterSelectedArea(callback: Callback<TimePickerResult>)

滑动 TimePicker 过程中，选项进入分割线区域内，触发该回调。

参数

参数名	类型	描述
callback	Callback<TimePickerResult>	滑动 TimePicker 过程中，选项进入分割线区域时触发的回调。

TimePickerResult 对象说明

TimePickerResult 对象返回值为 24 小时制时间。

参数名	类型	描述
hour	number	选中时间的时。取值范围：[0-23]
minute	number	选中时间的分。取值范围：[0-59]
second	number	选中时间的秒。取值范围：[0-59]

使用示例

示例 1：设置文本样式

该示例通过配置 disappearTextStyle、textStyle、selectedTextStyle 实现文本选择器中的文本样式。


@Entry
@Component
struct TimePickerExample {
  private selectedTime: Date = new Date('2022-07-22T08:00:00');

  build() {
    TimePicker({ selected: this.selectedTime })
      .disappearTextStyle({ color: '#004aaf', font: { size: 24, weight: FontWeight.Lighter } })
      .textStyle({ color: Color.Black, font: { size: 26, weight: FontWeight.Normal } })
      .selectedTextStyle({ color: Color.Blue, font: { size: 30, weight: FontWeight.Bolder } })
      .onChange((value: TimePickerResult) => {
        if (value.hour >= 0) {
          this.selectedTime.setHours(value.hour, value.minute);
          console.info('select current date is: ' + JSON.stringify(value));
        }
      });
  }
}

示例 2：切换小时制

该示例通过配置 useMilitaryTime 实现 12 小时制、24 小时制的切换。

@Entry
@Component
struct TimePickerExample {
  @State isMilitaryTime: boolean = false;
  private selectedTime: Date = new Date('2022-07-22T08:00:00');

  build() {
    Column() {
      Button('切换 12 小时制/24 小时制').margin(30).onClick(() => {
        this.isMilitaryTime = !this.isMilitaryTime;
      });
      TimePicker({ selected: this.selectedTime })
        .useMilitaryTime(this.isMilitaryTime)
        .onChange((value: TimePickerResult) => {
          if (value.hour >= 0) {
            this.selectedTime.setHours(value.hour, value.minute);
            console.info('select current time is: ' + JSON.stringify(value));
          }
        })
          //api 18+,可以参考OpenHarmony
        .onEnterSelectedArea((value: TimePickerResult) => {
          console.info('item enter selected area, time is: ' + JSON.stringify(value));
        });
    }.width('100%');
  }
}

示例 3：设置时间格式

该示例使用 format、dateTimeOptions 设置 TimePicker 时间格式。

@Entry
@Component
struct TimePickerExample {
  private selectedTime: Date = new Date('2022-07-22T08:00:00');

  build() {
    Column() {
      TimePicker({ selected: this.selectedTime, format: TimePickerFormat.HOUR_MINUTE_SECOND })
        .dateTimeOptions({ hour: "numeric", minute: "2-digit", second: "2-digit" })
        .onChange((value: TimePickerResult) => {
          if (value.hour >= 0) {
            this.selectedTime.setHours(value.hour, value.minute);
            console.info('select current date is: ' + JSON.stringify(value));
          }
        });
    }.width('100%');
  }
}

示例 4：设置循环滚动

该示例使用 loop 设置 TimePicker 是否循环滚动。

@Entry
@Component
struct TimePickerExample {
  @State isLoop: boolean = true;
  private selectedTime: Date = new Date('2022-07-22T12:00:00');

  build() {
    Column() {
      TimePicker({ selected: this.selectedTime }).loop(this.isLoop).onChange((value: TimePickerResult) => {
        if (value.hour >= 0) {
          this.selectedTime.setHours(value.hour, value.minute);
          console.info('select current date is: ' + JSON.stringify(value));
        }
      });
      Row() {
        Text('循环滚动').fontSize(20);
        Toggle({ type: ToggleType.Switch, isOn: true }).onChange((isOn: boolean) => {
          this.isLoop = isOn;
        });
      }.position({ x: '60%', y: '40%' });
    }.width('100%');
  }
}

示例 5：设置时间选择组件的起始时间

该示例设置 TimePicker 的起始时间。

@Entry
@Component
struct TimePickerExample {
  private selectedTime: Date = new Date('2022-07-22T08:50:00');

  build() {
    Column() {
      TimePicker({
        selected: this.selectedTime,
        format: TimePickerFormat.HOUR_MINUTE_SECOND,
        start: new Date('2022-07-22T08:30:00') //api18+
      })
        .dateTimeOptions({ hour: "numeric", minute: "2-digit", second: "2-digit" })
        .onChange((value: TimePickerResult) => {
          if (value.hour >= 0) {
            this.selectedTime.setHours(value.hour, value.minute);
            console.info('select current date is: ' + JSON.stringify(value));
          }
        });
    }.width('100%');
  }
}

示例 6：设置时间选择组件的结束时间

该示例设置 TimePicker 的结束时间。

@Entry
@Component
struct TimePickerExample {
  private selectedTime: Date = new Date('2022-07-22T08:50:00');

  build() {
    Column() {
      TimePicker({
        selected: this.selectedTime,
        format: TimePickerFormat.HOUR_MINUTE_SECOND,
        end: new Date('2022-07-22T15:20:00'),//api18+
      })
        .dateTimeOptions({ hour: "numeric", minute: "2-digit", second: "2-digit" })
        .onChange((value: TimePickerResult) => {
          if (value.hour >= 0) {
            this.selectedTime.setHours(value.hour, value.minute);
            console.info('select current date is: ' + JSON.stringify(value));
          }
        });
    }.width('100%');
  }
}

示例 7：设置上午下午跟随时间联动

该示例通过配置 enableCascade、loop 实现 12 小时制时上午下午跟随时间联动。

@Entry
@Component
struct TimePickerExample {
  private selectedTime: Date = new Date('2022-07-22T08:00:00');

  build() {
    Column() {
      TimePicker({ selected: this.selectedTime, })
        .enableCascade(true) //api18+
        .loop(true)
        .onChange((value: TimePickerResult) => {
          if (value.hour >= 0) {
            this.selectedTime.setHours(value.hour, value.minute);
            console.info('select current date is: ' + JSON.stringify(value));
          }
        });
    }.width('100%');
  }
}

最佳实践

在使用 TimePicker 组件时，以下是一些最佳实践建议：

合理设置时间范围：根据实际需求设置合理的起始和结束时间，避免用户选择不合理的时间。
自定义样式：根据应用的整体风格，自定义 TimePicker 的样式，使其与应用的其他组件协调一致。
处理事件回调：合理处理 onChange、onEnterSelectedArea 等事件回调，确保用户选择的时间能够正确处理。
性能优化：避免在 TimePicker 组件中进行复杂的计算或数据处理，确保组件的响应速度。

结论

ArkUI 中的 TimePicker 组件是一个功能强大且灵活的时间选择工具，支持多种时间格式、自定义时间范围、丰富的样式设置以及多种事件回调。通过合理配置和使用 TimePicker 组件，开发者可以轻松实现各种时间选择功能，提升用户体验。希望本文的介绍能够帮助开发者更好地理解和使用 ArkUI 中的 TimePicker 组件。

----

文章中使用了部分api18+的接口，并不能保证后续能够合并到HarmonyOS NEXT中，感兴趣可以前往OpenHarmony查看