ui_view_group
ui_view_group 模块提供视图容器基类，在视图基类基础上增加子视图添加、移除与遍历等容器管理能力。
Class Summary
OHOS::UIViewGroup
表示一个由子视图组成的视图组，子视图可以添加、插入和移除，后添加的子视图显示在视图组的上层，所有子视图存储在链表中。
- 构造：无
-
成员函数：
接口名称 功能简述 GetViewType 获取视图类型 Add 添加子视图 Insert 在指定子视图后插入新子视图 Remove 移除指定子视图 RemoveAll 移除所有子视图 RemoveAndDeleteAllRecursively 递归移除并删除所有子视图 GetTargetView 根据坐标获取可响应触摸事件的目标子视图 MoveChildByOffset 按偏移量移动所有子视图 GetChildrenHead 获取第一个子视图 GetChildrenTail 获取最后一个子视图 GetChildrenRenderHead 获取第一个渲染子视图 SetChildrenRenderHead 设置第一个渲染子视图 SetDisallowIntercept 设置触摸事件是否被拦截 GetChildById 根据ID获取子视图 SetAutoSize 设置视图组大小是否自适应子视图 GetChildrenNumber 获取子视图数量 SetInterceptFocus 设置组件是否拦截焦点 IsInterceptFocus 获取组件是否拦截焦点 UpdateRenderView 更新渲染树 -
使用包含头文件：
#include "components/ui_view_group.h" - 声明头文件：
/src/middleware/services/gui/uikit/ui/interfaces/kits/components/ui_view_group.h - 公有运算符：无
- 继承关系：UIView
- 嵌套类型：无
- 模板形参：无
Functions
OHOS::UIViewGroup
GetViewType
UIViewType GetViewType() const override
功能说明
- 核心用途：获取当前视图的类型标识
- 返回值为
UI_VIEW_GROUP，定义于 UIViewType 枚举中 - 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
UIViewType
返回视图类型标识
| 返回值 | 触发场景 |
|---|---|
| UI_VIEW_GROUP(1) | 当前对象为 UIViewGroup 实例 |
Add
virtual void Add(UIView* view)
功能说明
- 核心用途：向视图组中添加子视图，子视图被追加到链表末尾
- 添加后子视图的 parent 指向当前视图组，若启用了自适应大小则自动调整视图组尺寸
- 不允许添加自身、不允许添加 nullptr、不允许重复添加同一子视图
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| view | UIView* | 入参指针，指向待添加的子视图 | 不为 nullptr，不能为 this 自身，不能已有 parent |
Insert
virtual void Insert(UIView* prevView, UIView* insertView)
功能说明
- 核心用途：在指定子视图后插入新子视图
- 若 prevView 为 nullptr，则将新子视图插入到链表头部；若子视图链表为空，则调用 Add 添加
- 插入后更新渲染链表和子视图数量，若启用自适应大小则自动调整
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| prevView | UIView* | 入参指针，指定前一个子视图的位置 | 可为 nullptr（插入到头部） |
| insertView | UIView* | 入参指针，指向待插入的新子视图 | 不为 nullptr，不能为 this 自身，不能已有 parent |
Remove
virtual void Remove(UIView* view)
功能说明
- 核心用途：从视图组中移除指定子视图
- 移除后子视图的 parent 和 nextSibling 置为 nullptr，同时从渲染链表中移除
- 移除后更新子视图数量，若启用自适应大小则自动调整
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| view | UIView* | 入参指针，指向待移除的子视图 | 不为 nullptr，须为当前视图组的子视图 |
RemoveAll
virtual void RemoveAll()
功能说明
- 核心用途：移除视图组中所有子视图
- 遍历子视图链表，将每个子视图的 parent、nextSibling、nextRenderSibling 均置为 nullptr
- 清空后子视图链表头尾指针和渲染头指针均置为 nullptr，子视图数量归零
RemoveAndDeleteAllRecursively
static void RemoveAndDeleteAllRecursively(UIViewGroup*& group)
功能说明
- 核心用途：递归移除并删除视图组及其所有子视图
- 对于特定类型（如 UIPicker、UITimePicker、UIImagePicker、UIDigitalClock、UIRollerView、UICoverFlow、UIMenuItem、UIList、UIOptionBox、UIVideo）直接 delete 整个 group
- 对于 UICrossView、UICardContainer、UISlipflowView 类型需手动删除其他子视图后调用
- 对于普通视图组，递归遍历子视图链表，若子视图为视图组则递归调用自身，否则直接 delete
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| group | UIViewGroup*& | 入参引用指针，指向待递归删除的视图组 | 不为 nullptr |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_FOCUS_MANAGER | 启用焦点管理器 | - |
GetTargetView
void GetTargetView(const Point& point, UIView** last) override
功能说明
- 核心用途：根据给定坐标获取可见且可响应触摸事件的目标子视图
- 若视图组设置了拦截触摸事件标志（disallowIntercept），则返回 nullptr
- 遍历渲染链表查找包含指定坐标且可响应的子视图
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| point | const Point& | 入参只读引用，指定坐标 | - |
| last | UIView** | 出参指针，指向获取到的目标视图 | 不为 nullptr，可被写入 nullptr 表示未获取到 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| last | UIView** | 出参指针，由被调用方写入目标视图指针或 nullptr |
GetTargetView
void GetTargetView(const Point& point, UIView** current, UIView** target) override
功能说明
- 核心用途：根据指定坐标获取当前视图和目标视图，当前视图为包含坐标且可响应触摸的顶层视图，目标视图为包含坐标的顶层视图
- 若视图组设置了拦截触摸事件标志（disallowIntercept），则 current 和 target 均置为 nullptr
- 支持变换映射（TransformMap）下的坐标转换
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| point | const Point& | 入参只读引用，指定坐标 | - |
| current | UIView** | 出参指针，指向获取到的当前视图 | 不为 nullptr |
| target | UIView** | 出参指针，指向获取到的目标视图 | 不为 nullptr |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| current | UIView** | 出参指针，由被调用方写入当前视图指针或 nullptr |
| target | UIView** | 出参指针，由被调用方写入目标视图指针或 nullptr |
MoveChildByOffset
virtual void MoveChildByOffset(int16_t x, int16_t y)
功能说明
- 核心用途：按偏移量移动视图组中所有子视图的位置
- 遍历子视图链表，将每个子视图的 x/y 坐标分别加上指定偏移量
- 该函数为虚函数，子类可重写以实现自定义移动逻辑
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| x | int16_t | x 轴偏移距离 | INT16_MIN ~ INT16_MAX |
| y | int16_t | y 轴偏移距离 | INT16_MIN ~ INT16_MAX |
GetChildrenHead
UIView* GetChildrenHead() const
功能说明
- 核心用途：获取视图组中第一个子视图
- 返回子视图链表的头节点指针
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
UIView*
返回第一个子视图指针
| 返回值 | 触发场景 |
|---|---|
| 非空指针 | 子视图链表非空 |
| nullptr | 子视图链表为空 |
GetChildrenTail
UIView* GetChildrenTail() const
功能说明
- 核心用途：获取视图组中最后一个子视图
- 返回子视图链表的尾节点指针
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
UIView*
返回最后一个子视图指针
| 返回值 | 触发场景 |
|---|---|
| 非空指针 | 子视图链表非空 |
| nullptr | 子视图链表为空 |
GetChildrenRenderHead
UIView* GetChildrenRenderHead() const
功能说明
- 核心用途：获取视图组中第一个渲染子视图
- 渲染链表按 zIndex 排序，与子视图链表的添加顺序不同
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
UIView*
返回第一个渲染子视图指针
| 返回值 | 触发场景 |
|---|---|
| 非空指针 | 渲染链表非空 |
| nullptr | 渲染链表为空 |
SetChildrenRenderHead
void SetChildrenRenderHead(UIView* renderHead)
功能说明
- 核心用途：设置视图组的第一个渲染子视图
- 待设置的视图必须为当前视图组的子视图，否则设置失败
- 该接口用于手动调整渲染链表头部
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| renderHead | UIView* | 入参指针，指定第一个渲染子视图 | 可为 nullptr；若非 nullptr 则须为当前视图组的子视图 |
SetDisallowIntercept
void SetDisallowIntercept(bool flag)
功能说明
- 核心用途：设置视图组在触摸事件中是否被拦截
- 设置为 true 时，视图组将拦截触摸事件，GetTargetView 返回 nullptr
- 设置为 false 时，触摸事件正常传递到子视图
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| flag | bool | 入参，是否拦截触摸事件 | true：拦截；false：不拦截 |
GetChildById
virtual UIView* GetChildById(const char* id) const override
功能说明
- 核心用途：根据 ID 查找目标子视图
- 采用深度优先遍历方式在子视图树中查找匹配 ID 的子视图
- 该函数为 const 成员函数，不修改对象状态
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| id | const char* | 入参只读指针，目标子视图的 ID 字符串 | 不为 nullptr |
返回值
- 返回类型：
UIView*
返回匹配 ID 的子视图
| 返回值 | 触发场景 |
|---|---|
| 非空指针 | 找到匹配 ID 的子视图 |
| nullptr | 未找到匹配 ID 的子视图 |
SetAutoSize
void SetAutoSize(bool state)
功能说明
- 核心用途：设置视图组大小是否自适应所有子视图
- 启用后，添加或插入子视图时视图组将自动调整大小以包含所有子视图
- 禁用后，视图组大小需手动设置
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| state | bool | 入参，是否启用自适应大小 | true：启用；false：禁用 |
GetChildrenNumber
uint16_t GetChildrenNumber() const
功能说明
- 核心用途：获取视图组中子视图的数量
- 返回当前视图组中子视图链表的节点数
- 该函数为 const 成员函数，不修改对象状态
返回值
- 返回类型：
uint16_t
返回子视图数量
| 返回值 | 触发场景 |
|---|---|
| 0 | 无子视图 |
| 1~65535 | 子视图数量 |
SetInterceptFocus
void SetInterceptFocus(bool interceptFocus)
功能说明
- 核心用途：设置组件是否拦截焦点
- 设置为 true 时，该视图组将拦截焦点
- 该接口仅在 ENABLE_FOCUS_MANAGER 宏启用时可用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| interceptFocus | bool | 入参，是否拦截焦点 | true：拦截焦点；false：不拦截焦点 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_FOCUS_MANAGER | 启用焦点管理器 | - |
IsInterceptFocus
bool IsInterceptFocus() const
功能说明
- 核心用途：获取组件是否拦截焦点
- 返回当前焦点拦截标志的状态
- 该接口仅在 ENABLE_FOCUS_MANAGER 宏启用时可用
返回值
- 返回类型：
bool
返回焦点拦截状态
| 返回值 | 触发场景 |
|---|---|
| true | 组件拦截焦点 |
| false | 组件不拦截焦点 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_FOCUS_MANAGER | 启用焦点管理器 | - |
UpdateRenderView
void UpdateRenderView(UIView* targetView)
功能说明
- 核心用途：更新渲染树，在子视图添加、移除或 zIndex 变更时调用
- 根据 zIndex 值将目标视图插入到渲染链表的正确位置
- 先从渲染链表中移除目标视图，再按 zIndex 顺序重新插入
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| targetView | UIView* | 入参指针，被添加/移除或变更 zIndex 的视图 | 不为 nullptr |