ui_picker

ui_picker 模块提供选择器组件，支持滚轮式选项选择与选中事件监听。

Class Summary

OHOS::PickerListScrollListener

Picker 组件列表滚动事件监听器，响应列表项选中与滚动结束事件

• 构造：PickerListScrollListener(UIPicker* picker, UIList* list)

• 成员函数：

  接口名称	功能简述
  PickerListScrollListener	构造监听器并绑定 Picker 与列表实例
  OnItemSelected	列表项选中时回调，更新选中项高亮样式
  OnScrollEnd	列表滚动结束时回调，更新选中项并通知停止事件
  SetSelectView	设置当前选中视图
  GetSelectView	获取当前选中视图
  SetSelectIndex	设置当前选中项索引
  GetSelectIndex	获取当前选中项索引
  SetInitStatus	设置初始化状态标志

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

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

OHOS::UIPicker

Picker 滑动选择器组件，支持文本或数字的滑动选择与高亮显示

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  OnPreDraw	绘制前回调，控制是否跳过绘制
  SetValues	通过字符串数组设置 Picker 数据
  SetValues	通过数值范围设置 Picker 数据
  ClearValues	清除 Picker 中所有数据
  SetFontId	设置背景与高亮文本字体 ID
  SetBackgroundFont	设置背景文本字体名称和大小
  SetHighlightFont	设置高亮文本字体名称和大小
  GetBackgroundFontId	获取背景文本字体 ID
  GetHighlightFontId	获取高亮文本字体 ID
  SetTextColor	设置背景与高亮文本颜色
  GetBackgroundTextColor	获取背景文本颜色
  GetHighlightTextColor	获取高亮文本颜色
  SetSelected	设置当前选中项索引
  GetSelected	获取当前选中项索引
  SetItemHeight	设置每项高度
  SetWidth	设置组件宽度
  SetHeight	设置组件高度
  SetLoopState	设置是否循环滑动
  RegisterSelectedListener	注册选中事件监听器
  SetDirect	设置文本方向
  SetTextFormatter	设置文本格式化器
  SetDragFunc	设置拖拽缓动函数
  SetReboundSize	设置回弹距离
  SetAutoAlignTime	设置自动对齐动画时长
  SetDragACCLevel	设置拖拽加速度级别
  SetSwipeACCLevel	设置滑动补偿距离级别
  SetScrollBlankSize	设置滚动留白大小
  RequestFocus	请求获焦
  ClearFocus	清除焦点
  SetRotateFactor	设置旋转因子
  GetRotateFactor	获取旋转因子
  SetRotateThrowThreshold	设置触发惯性滑动的旋转阈值
  SetOnRotateListener	设置旋转事件监听器
  GetOnRotateListener	获取旋转事件监听器
  SetFocusable	设置是否可获焦
  IsFocusable	查询是否可获焦
  Focus	组件获焦响应
  Blur	组件失焦响应
  SetOnFocusListener	设置焦点改变事件监听器
  GetOnFocusListener	获取焦点改变事件监听器
  GetList	获取内部列表视图

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

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

OHOS::UIPicker::SelectedListener

Picker 选中事件监听器基类，提供选中停止和滑动中回调接口

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnPickerStoped	滑动停止后选中项回调
  OnPickerChanged	滑动过程中选中项回调

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

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

Functions

OHOS::PickerListScrollListener

PickerListScrollListener(UIPicker picker, UIList list)

PickerListScrollListener(UIPicker* picker, UIList* list)

功能说明

• 构造 PickerListScrollListener 实例，绑定 Picker 与列表视图
• 初始化选中索引为 0，选中视图与上一次选中视图为 nullptr
• 初始化状态标志为 false

入参

名称	参数类型	详细说明	约束取值范围
picker	UIPicker*	入参指针，关联的 Picker 实例	非 nullptr
list	UIList*	入参指针，关联的列表视图实例	非 nullptr

OnItemSelected

void OnItemSelected(int16_t index, UIView* view) override

功能说明

• 列表项被选中时的回调，更新选中项的高亮样式
• 将上一次选中项恢复为背景样式，将当前选中项设为高亮样式
• 触发已注册的 SelectedListener 的 OnPickerChanged 回调

入参

名称	参数类型	详细说明	约束取值范围
index	int16_t	选中项索引	0 ~ 列表项数-1
view	UIView*	入参指针，选中项对应的视图	非 nullptr

OnScrollEnd

void OnScrollEnd(int16_t index, UIView* view) override

功能说明

• 列表滚动结束时的回调，更新选中项高亮样式并记录最终选中视图
• 将上一次选中项恢复为背景样式，将当前选中项设为高亮样式
• 触发已注册的 SelectedListener 的 OnPickerStoped 回调

入参

名称	参数类型	详细说明	约束取值范围
index	int16_t	最终选中项索引	0 ~ 列表项数-1
view	UIView*	入参指针，最终选中项对应的视图	非 nullptr

SetSelectView

void SetSelectView(UIView* view)

功能说明

• 设置当前选中视图，同时更新上一次选中视图记录
• 调用后 GetSelectView 将返回新设置的视图

入参

名称	参数类型	详细说明	约束取值范围
view	UIView*	入参指针，要设置的选中视图	可为 nullptr

GetSelectView

const UIView* GetSelectView() const

功能说明

• 获取当前选中视图
• 返回的指针为只读指针，调用方不应修改所指对象
• 此函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：const UIView*

返回当前选中视图指针

返回值	触发场景
非 nullptr	已设置选中视图
nullptr	未设置选中视图

SetSelectIndex

void SetSelectIndex(uint16_t index)

功能说明

• 设置当前选中项的索引值
• 不触发界面刷新，仅更新内部索引记录

入参

名称	参数类型	详细说明	约束取值范围
index	uint16_t	选中项索引	0 ~ 65535

GetSelectIndex

uint16_t GetSelectIndex() const

功能说明

• 获取当前选中项的索引值
• 此函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：uint16_t

返回当前选中项索引

返回值	触发场景
0 ~ 65535	当前选中项索引值

SetInitStatus

void SetInitStatus(bool status)

功能说明

• 设置初始化状态标志
• 初始化状态为 false 时，OnItemSelected 回调将不执行选中逻辑

入参

名称	参数类型	详细说明	约束取值范围
status	bool	初始化状态标志	true / false

OHOS::UIPicker

GetViewType

UIViewType GetViewType() const override

功能说明

• 获取当前视图的类型标识
• 返回值固定为 UI_PICKER，用于区分 Picker 组件与其他视图类型
• 此函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_PICKER	当前视图为 Picker 类型

OnPreDraw

bool OnPreDraw(Rect& invalidatedArea) const override

功能说明

• 绘制前回调，控制是否跳过当前绘制
• 固定返回 false，表示不跳过绘制
• 此函数为 const 成员函数，不修改对象状态

入参

名称	参数类型	详细说明	约束取值范围
invalidatedArea	Rect&	入参引用，无效区域矩形	-

返回值

• 返回类型：bool

返回是否跳过绘制

返回值	触发场景
false(0)	不跳过绘制，继续执行绘制流程

SetValues(const char* value[], uint16_t count)

virtual bool SetValues(const char* value[], uint16_t count)

功能说明

• 通过字符串数组设置 Picker 的动态文本数据
• 设置后自动刷新列表显示，保留用户之前的选中索引
• 若 value 为 nullptr 则返回 false

入参

名称	参数类型	详细说明	约束取值范围
value	const char*[]	入参指针，文本数据数组	非 nullptr
count	uint16_t	数组元素个数	1 ~ 65535

返回值

• 返回类型：bool

返回设置是否成功

返回值	触发场景
true(1)	设置成功
false(0)	value 为 nullptr 或宽高未设置

SetValues(int16_t start, int16_t end)

virtual bool SetValues(int16_t start, int16_t end)

功能说明

• 通过数值范围设置 Picker 的数据，自动生成 start 到 end 之间的所有整数
• start 必须小于等于 end，否则返回 false
• 设置后自动刷新列表显示，保留用户之前的选中索引

入参

名称	参数类型	详细说明	约束取值范围
start	int16_t	起始整数值	-32768 ~ 32767
end	int16_t	结束整数值	start ~ 32767

返回值

• 返回类型：bool

返回设置是否成功

返回值	触发场景
true(1)	设置成功
false(0)	start > end 或宽高未设置

ClearValues

virtual void ClearValues()

功能说明

• 清除 Picker 中所有数据，重置数值范围与列表显示
• 清除内部文本适配器并重置选中状态
• 无返回值

SetFontId

void SetFontId(uint16_t backgroundFontId, uint16_t highlightFontId)

功能说明

• 设置背景文本与高亮文本的字体 ID
• 设置后清除已设置的字体名称，以字体 ID 为准
• 设置后自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
backgroundFontId	uint16_t	背景文本字体 ID	有效字体 ID
highlightFontId	uint16_t	高亮文本字体 ID	有效字体 ID

SetBackgroundFont

void SetBackgroundFont(const char* name, uint8_t size)

功能说明

• 设置背景文本的字体名称和大小
• 设置后以字体名称和大小为准，覆盖之前设置的字体 ID
• 设置后自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参指针，字体名称	非 nullptr
size	uint8_t	字体大小	1 ~ 255

SetHighlightFont

void SetHighlightFont(const char* name, uint8_t size)

功能说明

• 设置高亮文本的字体名称和大小
• 设置后以字体名称和大小为准，覆盖之前设置的字体 ID
• 设置后自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参指针，字体名称	非 nullptr
size	uint8_t	字体大小	1 ~ 255

GetBackgroundFontId

uint16_t GetBackgroundFontId() const

功能说明

• 获取背景文本的字体 ID
• 此函数为 const 成员函数，不修改对象状态
• 返回值由 SetFontId 或构造时主题样式决定

返回值

• 返回类型：uint16_t

返回背景文本字体 ID

返回值	触发场景
0 ~ 65535	背景文本字体 ID

GetHighlightFontId

uint16_t GetHighlightFontId() const

功能说明

• 获取高亮文本的字体 ID
• 此函数为 const 成员函数，不修改对象状态
• 返回值由 SetFontId 或构造时主题样式决定

返回值

• 返回类型：uint16_t

返回高亮文本字体 ID

返回值	触发场景
0 ~ 65535	高亮文本字体 ID

SetTextColor

void SetTextColor(ColorType backgroundColor, ColorType highlightColor)

功能说明

• 设置背景文本与高亮文本的颜色
• 设置后自动刷新列表显示
• 颜色值相同时不执行刷新

入参

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

GetBackgroundTextColor

ColorType GetBackgroundTextColor() const

功能说明

• 获取背景文本颜色
• 此函数为 const 成员函数，不修改对象状态
• 返回值由 SetTextColor 或构造时主题样式决定

返回值

• 返回类型：ColorType

返回背景文本颜色

返回值	触发场景
ColorType	当前背景文本颜色值

GetHighlightTextColor

ColorType GetHighlightTextColor() const

功能说明

• 获取高亮文本颜色
• 此函数为 const 成员函数，不修改对象状态
• 返回值由 SetTextColor 或构造时主题样式决定

返回值

• 返回类型：ColorType

返回高亮文本颜色

返回值	触发场景
ColorType	当前高亮文本颜色值

SetSelected

bool SetSelected(uint16_t index)

功能说明

• 设置当前选中项的索引
• 索引超出当前数据范围时返回 false
• 设置成功后自动滚动到目标项并更新高亮样式

入参

名称	参数类型	详细说明	约束取值范围
index	uint16_t	选中项索引	0 ~ maxCount-1

返回值

• 返回类型：bool

返回设置是否成功

返回值	触发场景
true(1)	设置成功并刷新显示
false(0)	索引超出范围或宽高未设置

GetSelected

uint16_t GetSelected() const

功能说明

• 获取当前选中项的索引
• 此函数为 const 成员函数，不修改对象状态

返回值

• 返回类型：uint16_t

返回当前选中项索引

返回值	触发场景
0 ~ 65535	当前选中项索引

SetItemHeight

void SetItemHeight(int16_t height)

功能说明

• 设置 Picker 中每项的高度
• 高度值必须大于 0，否则不执行设置
• 设置后自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
height	int16_t	每项高度（像素）	> 0

SetWidth

void SetWidth(int16_t width) override

功能说明

• 设置 Picker 组件的宽度
• 宽度值必须大于 0，否则不执行设置
• 设置后标记宽度已设置并自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
width	int16_t	组件宽度（像素）	> 0

SetHeight

void SetHeight(int16_t height) override

功能说明

• 设置 Picker 组件的高度
• 高度值必须大于 0，否则不执行设置
• 设置后标记高度已设置并自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
height	int16_t	组件高度（像素）	> 0

SetLoopState

void SetLoopState(bool state)

功能说明

• 设置 Picker 是否支持循环滑动
• 默认值为 false（不可循环滑动）
• 设置后自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
state	bool	是否循环滑动	true：可循环；false：不可循环

RegisterSelectedListener

void RegisterSelectedListener(SelectedListener* pickerListener)

功能说明

• 注册选中事件监听器，用于接收选中停止和滑动选中回调
• 传入 nullptr 可取消监听
• 同一时间仅支持一个监听器

入参

名称	参数类型	详细说明	约束取值范围
pickerListener	SelectedListener*	入参指针，选中事件监听器	可为 nullptr

SetDirect

void SetDirect(UITextLanguageDirect direct)

功能说明

• 设置文本方向（从左到右或从右到左）
• 设置后自动刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
direct	UITextLanguageDirect	文本方向	UITextLanguageDirect 枚举值

SetTextFormatter

void SetTextFormatter(TextFormatter* formatter)

功能说明

• 设置文本格式化器，用于自定义文本显示格式
• 设置后自动初始化文本适配器并刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
formatter	TextFormatter*	入参指针，文本格式化器	可为 nullptr

SetDragFunc

void SetDragFunc(EasingFunc func)

功能说明

• 设置手指抬起后滚动动画的缓动函数
• 默认缓动函数为 EasingEquation::CubicEaseOut
• 设置后影响拖拽后的惯性滚动动画效果

入参

名称	参数类型	详细说明	约束取值范围
func	EasingFunc	缓动函数指针	有效的 EasingFunc 函数

SetReboundSize

void SetReboundSize(uint16_t size)

功能说明

• 设置回弹距离，即滑动到端点后松手回弹的像素距离
• 设置后影响滚动到边界时的回弹效果

入参

名称	参数类型	详细说明	约束取值范围
size	uint16_t	回弹距离（像素）	0 ~ 65535

SetAutoAlignTime

void SetAutoAlignTime(uint16_t time)

功能说明

• 设置自动对齐动画时长，单位为毫秒，默认为 100 毫秒
• 该功能依赖 EnableAutoAlign 设置为 true 时才生效
• 设置为 0 表示无动画

入参

名称	参数类型	详细说明	约束取值范围
time	uint16_t	自动对齐动画时长（毫秒）	0 ~ 65535

SetDragACCLevel

void SetDragACCLevel(uint16_t value)

功能说明

• 设置拖拽加速度级别，默认值为 10
• 值越大，惯性滚动速度越高

入参

名称	参数类型	详细说明	约束取值范围
value	uint16_t	拖拽加速度级别	默认值 10

SetSwipeACCLevel

void SetSwipeACCLevel(uint16_t value)

功能说明

• 设置手指抬起后的滑动补偿距离级别，默认值为 0
• 值越大，补偿距离越大

入参

名称	参数类型	详细说明	约束取值范围
value	uint16_t	滑动补偿距离级别	默认值 0

SetScrollBlankSize

void SetScrollBlankSize(uint16_t size)

功能说明

• 设置滚动留白大小，即列表头尾可超出视图边界的像素距离
• 默认值 0 表示头尾节点不能超出视图边界
• 设置后标记留白已设置并刷新列表显示

入参

名称	参数类型	详细说明	约束取值范围
size	uint16_t	滚动留白大小（像素）	0 ~ 65535

RequestFocus

void RequestFocus() override

功能说明

• 请求获取焦点，焦点将传递给内部列表视图
• 需要 ENABLE_ROTATE_INPUT 宏开启

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	旋转输入功能开关	n

ClearFocus

void ClearFocus() override

功能说明

• 清除焦点，将清除内部列表视图的焦点
• 需要 ENABLE_ROTATE_INPUT 宏开启

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	旋转输入功能开关	n

SetRotateFactor

void SetRotateFactor(float factor)

功能说明

• 设置旋转因子，影响旋转输入的灵敏度
• 需要 ENABLE_ROTATE_INPUT 宏开启

入参

名称	参数类型	详细说明	约束取值范围
factor	float	旋转因子	浮点数值

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	旋转输入功能开关	n

GetRotateFactor

float GetRotateFactor()

功能说明

• 获取当前旋转因子
• 需要 ENABLE_ROTATE_INPUT 宏开启

返回值

• 返回类型：float

返回旋转因子

返回值	触发场景
float	当前旋转因子值

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	旋转输入功能开关	n

SetRotateThrowThreshold

void SetRotateThrowThreshold(uint8_t threshold)

功能说明

• 设置触发惯性滑动的旋转比例阈值
• 旋转表冠结束时，若最后一次旋转位移数值大于组件宽或高除以 threshold，则触发惯性滑动
• 需要 ENABLE_ROTATE_INPUT 宏开启

入参

名称	参数类型	详细说明	约束取值范围
threshold	uint8_t	触发惯性滑动的比例阈值	1 ~ 255

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	旋转输入功能开关	n

SetOnRotateListener

void SetOnRotateListener(OnRotateListener* onRotateListener) override

功能说明

• 设置旋转事件监听器
• 需要 ENABLE_ROTATE_INPUT 宏开启

入参

名称	参数类型	详细说明	约束取值范围
onRotateListener	OnRotateListener*	入参指针，旋转事件监听器	可为 nullptr

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	旋转输入功能开关	n

GetOnRotateListener

OnRotateListener*& GetOnRotateListener() override

功能说明

• 获取旋转事件监听器的引用
• 返回引用类型，可用于直接修改监听器指针
• 需要 ENABLE_ROTATE_INPUT 宏开启

返回值

• 返回类型：OnRotateListener*&

返回旋转事件监听器指针引用

返回值	触发场景
OnRotateListener*&	当前旋转事件监听器指针引用

Kconfig 配置

配置项	说明	默认值
ENABLE_ROTATE_INPUT	旋转输入功能开关	n

SetFocusable

void SetFocusable(bool focusable) override

功能说明

• 设置视图是否可获焦
• 需要 ENABLE_FOCUS_MANAGER 宏开启

入参

名称	参数类型	详细说明	约束取值范围
focusable	bool	是否可获焦	true：可获焦；false：不可获焦

Kconfig 配置

配置项	说明	默认值
ENABLE_FOCUS_MANAGER	焦点管理功能开关	n

IsFocusable

bool IsFocusable() const override

功能说明

• 查询视图是否可获焦
• 此函数为 const 成员函数，不修改对象状态
• 需要 ENABLE_FOCUS_MANAGER 宏开启

返回值

• 返回类型：bool

返回是否可获焦

返回值	触发场景
true(1)	视图可获焦
false(0)	视图不可获焦

Kconfig 配置

配置项	说明	默认值
ENABLE_FOCUS_MANAGER	焦点管理功能开关	n

Focus

void Focus() override

功能说明

• 组件获焦响应，焦点将传递给内部列表视图
• 需要 ENABLE_FOCUS_MANAGER 宏开启

Kconfig 配置

配置项	说明	默认值
ENABLE_FOCUS_MANAGER	焦点管理功能开关	n

Blur

void Blur() override

功能说明

• 组件失焦响应，将清除内部列表视图的焦点
• 需要 ENABLE_FOCUS_MANAGER 宏开启

Kconfig 配置

配置项	说明	默认值
ENABLE_FOCUS_MANAGER	焦点管理功能开关	n

SetOnFocusListener

void SetOnFocusListener(OnFocusListener* onFocusListener) override

功能说明

• 设置焦点改变事件监听器
• 需要 ENABLE_FOCUS_MANAGER 宏开启

入参

名称	参数类型	详细说明	约束取值范围
onFocusListener	OnFocusListener*	入参指针，焦点改变事件监听器	可为 nullptr

Kconfig 配置

配置项	说明	默认值
ENABLE_FOCUS_MANAGER	焦点管理功能开关	n

GetOnFocusListener

OnFocusListener* GetOnFocusListener() const override

功能说明

• 获取当前焦点改变事件监听器
• 此函数为 const 成员函数，不修改对象状态
• 需要 ENABLE_FOCUS_MANAGER 宏开启

返回值

• 返回类型：OnFocusListener*

返回焦点改变事件监听器指针

返回值	触发场景
非 nullptr	已设置焦点监听器
nullptr	未设置焦点监听器

Kconfig 配置

配置项	说明	默认值
ENABLE_FOCUS_MANAGER	焦点管理功能开关	n

GetList

UIList* GetList()

功能说明

• 获取 Picker 内部使用的列表视图指针
• 返回的指针可用于直接操作列表视图属性
• 返回指针与 Picker 生命周期绑定

返回值

• 返回类型：UIList*

返回内部列表视图指针

返回值	触发场景
UIList*	内部列表视图指针

OHOS::UIPicker::SelectedListener

OnPickerStoped

virtual void OnPickerStoped(UIPicker& picker)

功能说明

• 滑动停止后选中项的回调，由应用程序实现
• 当 Picker 滑动停止并确定选中项时触发
• 默认实现为空，子类需重写以处理停止选中事件

入参

名称	参数类型	详细说明	约束取值范围
picker	UIPicker&	入参引用，触发事件的 Picker 实例	有效引用

OnPickerChanged

virtual void OnPickerChanged(UIPicker& picker)

功能说明

• 滑动过程中选中项变化的回调，由应用程序实现
• 当 Picker 滑动过程中选中项发生变化时触发
• 默认实现为空，子类需重写以处理滑动选中事件

入参

名称	参数类型	详细说明	约束取值范围
picker	UIPicker&	入参引用，触发事件的 Picker 实例	有效引用