ui_time_picker

ui_time_picker 模块提供时间选择器组件，支持时/分/秒滚轮选择与选中事件监听。

Class Summary

OHOS::UITimePicker

时间选择器组件，支持"时:分"或"时:分:秒"格式的时间选择，选中项高亮显示。

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  SetSelected	设置时间选择器当前选中时间
  GetSelectValue	获取当前选中的完整时间字符串
  GetSelectHour	获取当前选中的小时
  GetSelectMinute	获取当前选中的分钟
  GetSelectSecond	获取当前选中的秒
  SetItemHeight	设置时间选择器每一项的高度
  EnableSecond	设置是否启用秒显示
  SetTextStyle	设置时间选择器文本格式（字体ID与颜色）
  SetTextColor	设置时间选择器文本颜色
  SetBackgroundFont	设置背景文本的字体名称与大小
  SetHighlightFont	设置高亮文本的字体名称与大小
  SetWidth	设置时间选择器宽度
  SetHeight	设置时间选择器高度
  SetLoopState	设置指定Picker类型是否循环滚动
  RegisterSelectedListener	注册选中事件监听器
  OnPressEvent	处理按下事件

• 使用包含头文件：#include "components/ui_time_picker.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_time_picker.h
• 公有运算符：无
• 继承关系：UIViewGroup
• 嵌套类型：enum PickerType；SelectedListener
• 模板形参：无

OHOS::UITimePicker::SelectedListener

时间选择器选中事件监听器，滑动停止后选中项时触发回调。

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnTimePickerStoped	滑动停止后选中项时的回调函数

• 使用包含头文件：#include "components/ui_time_picker.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_time_picker.h
• 公有运算符：无
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::UITimePicker

GetViewType

UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 返回类型为 UI_TIME_PICKER，用于在视图体系中区分时间选择器组件
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_TIME_PICKER	当前对象为时间选择器视图

SetSelected

bool SetSelected(const char* value)

功能说明

• 核心用途：设置时间选择器当前选中的时间
• 入参格式为"时:分:秒"（如"10:12:50"），秒部分可选，取决于 EnableSecond 设置
• 时间值必须合法，例如小时取值范围为 0~23，分钟取值范围为 0~59

入参

名称	参数类型	详细说明	约束取值范围
value	const char*	入参指针，指向选中时间字符串	非nullptr；格式为"HH:MM"或"HH:MM:SS"；小时 0~23，分钟 0~59，秒 0~59

返回值

• 返回类型：bool

返回设置是否成功

返回值	触发场景
true(1)	时间设置成功
false(0)	时间格式无效或数值超范围

GetSelectValue

const char* GetSelectValue()

功能说明

• 核心用途：获取当前选中的完整时间字符串
• 返回格式为"时:分:秒"（如"10:12:50"），秒部分可选，取决于 EnableSecond 设置
• 该函数为非 const 成员函数

返回值

• 返回类型：const char*

返回选中时间字符串指针

返回值	触发场景
非nullptr	指向内部存储的选中时间字符串

GetSelectHour

const char* GetSelectHour() const

功能说明

• 核心用途：获取当前选中的小时字符串
• 返回值为小时部分的字符串表示，例如"10"
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：const char*

返回选中小时字符串指针

返回值	触发场景
非nullptr	指向内部存储的选中小时字符串

GetSelectMinute

const char* GetSelectMinute() const

功能说明

• 核心用途：获取当前选中的分钟字符串
• 返回值为分钟部分的字符串表示，例如"12"
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：const char*

返回选中分钟字符串指针

返回值	触发场景
非nullptr	指向内部存储的选中分钟字符串

GetSelectSecond

const char* GetSelectSecond() const

功能说明

• 核心用途：获取当前选中的秒字符串
• 返回值为秒部分的字符串表示，例如"50"
• 该函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：const char*

返回选中秒字符串指针

返回值	触发场景
非nullptr	指向内部存储的选中秒字符串

SetItemHeight

void SetItemHeight(int16_t height)

功能说明

• 核心用途：设置时间选择器每一项的高度
• 影响时间选择器中时、分、秒各列的项显示高度
• 该函数为 void 返回类型，无返回值

入参

名称	参数类型	详细说明	约束取值范围
height	int16_t	每一项的高度值	正整数

EnableSecond

void EnableSecond(bool state)

功能说明

• 核心用途：设置是否启用时间选择器的秒显示
• 启用后时间格式为"时:分:秒"，禁用后为"时:分"
• 默认状态为禁用（false）

入参

名称	参数类型	详细说明	约束取值范围
state	bool	是否启用秒显示	true：启用秒；false：禁用秒

SetTextStyle

void SetTextStyle(uint16_t backgroundFontId, uint16_t highlightFontId, ColorType backgroundColor, ColorType highlightColor)

功能说明

• 核心用途：设置时间选择器文本格式，包括背景文本与高亮文本的字体ID和颜色
• 背景文本为未选中项的显示样式，高亮文本为选中项的显示样式
• 该函数同时设置字体ID与颜色，也可单独调用 SetTextColor 仅设置颜色

入参

名称	参数类型	详细说明	约束取值范围
backgroundFontId	uint16_t	背景文本字体ID	有效的字体ID
highlightFontId	uint16_t	高亮文本字体ID	有效的字体ID
backgroundColor	ColorType	背景文本颜色	合法的ColorType值
highlightColor	ColorType	高亮文本颜色	合法的ColorType值

SetTextColor

void SetTextColor(ColorType backgroundColor, ColorType highlightColor)

功能说明

• 核心用途：设置时间选择器文本颜色
• 背景颜色为未选中项的文字颜色，高亮颜色为选中项的文字颜色
• 该函数仅设置颜色，不影响字体ID

入参

名称	参数类型	详细说明	约束取值范围
backgroundColor	ColorType	背景文本颜色	合法的ColorType值
highlightColor	ColorType	高亮文本颜色	合法的ColorType值

SetBackgroundFont

void SetBackgroundFont(const char* name, uint8_t size)

功能说明

• 核心用途：设置背景文本（未选中项）的字体名称与大小
• 字体名称指向已注册的字体资源
• 该函数仅影响未选中项的字体显示

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参指针，指向字体名称字符串	非nullptr；已注册的字体名称
size	uint8_t	字体大小	正整数

SetHighlightFont

void SetHighlightFont(const char* name, uint8_t size)

功能说明

• 核心用途：设置高亮文本（选中项）的字体名称与大小
• 字体名称指向已注册的字体资源
• 该函数仅影响选中项的字体显示

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参指针，指向字体名称字符串	非nullptr；已注册的字体名称
size	uint8_t	字体大小	正整数

SetWidth

void SetWidth(int16_t width) override

功能说明

• 核心用途：设置时间选择器的宽度
• 重写基类 UIViewGroup 的 SetWidth 方法
• 宽度设置后会影响时间选择器各列的布局

入参

名称	参数类型	详细说明	约束取值范围
width	int16_t	时间选择器宽度值	正整数

SetHeight

void SetHeight(int16_t height) override

功能说明

• 核心用途：设置时间选择器的高度
• 重写基类 UIViewGroup 的 SetHeight 方法
• 高度设置后会影响时间选择器整体的显示区域

入参

名称	参数类型	详细说明	约束取值范围
height	int16_t	时间选择器高度值	正整数

SetLoopState

void SetLoopState(const uint8_t pickerType, bool state)

功能说明

• 核心用途：设置指定Picker类型是否循环滚动
• 当循环开启时，列表末尾滚动到头后继续滚动会回到起始位置
• 通过 pickerType 参数指定时、分、秒哪一列启用循环

入参

名称	参数类型	详细说明	约束取值范围
pickerType	const uint8_t	Picker类型标识	PickerType枚举值：PICKER_HOUR(0)、PICKER_MIN(1)、PICKER_SEC(2)
state	bool	是否启用循环	true：启用循环；false：禁用循环

RegisterSelectedListener

void RegisterSelectedListener(SelectedListener* timePickerListener)

功能说明

• 核心用途：注册选中事件监听器
• 当滑动停止后选中某一项时触发监听器回调
• 注册新的监听器会替换之前注册的监听器

入参

名称	参数类型	详细说明	约束取值范围
timePickerListener	SelectedListener*	入参指针，指向选中事件监听器对象	可为nullptr（取消监听）；非nullptr时需为有效的 SelectedListener 对象

OnPressEvent

bool OnPressEvent(const PressEvent& event) override

功能说明

• 核心用途：处理按下事件
• 重写基类事件处理方法，响应触摸屏按下操作
• 该函数为 override 成员函数

入参

名称	参数类型	详细说明	约束取值范围
event	const PressEvent&	入参只读引用，按下事件信息	合法的PressEvent对象引用

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true(1)	按下事件已被消费
false(0)	按下事件未被消费

OHOS::UITimePicker::SelectedListener

OnTimePickerStoped

virtual void OnTimePickerStoped(UITimePicker& picker) {}

功能说明

• 核心用途：滑动停止后选中项时的回调函数
• 该函数为虚函数，由应用程序实现具体逻辑
• 默认实现为空函数体

入参

名称	参数类型	详细说明	约束取值范围
picker	UITimePicker&	入参引用，触发回调的时间选择器实例	合法的UITimePicker对象引用

Enumerations

PickerType

enum PickerType : uint8_t {
    PICKER_HOUR = 0,
    PICKER_MIN,
    PICKER_SEC,
    PICKER_MAX,
};

枚举成员	取值	描述
PICKER_HOUR	0	时Picker
PICKER_MIN	1	分Picker
PICKER_SEC	2	秒Picker
PICKER_MAX	3	Picker类型最大值