ui_fragment

ui_fragment 模块提供片段（Fragment）组件，支持UI模块化拆分与片段生命周期管理。

Class Summary

OHOS::UIFragment

可复用的 UI 片段，拥有独立生命周期，可处理自身事件

• 构造：UIFragment(const std::string& id)

• 成员函数：

  接口名称	功能简述
  UIFragment	带参数构造函数，根据 id 注册到 UIFragmentManager
  CreateView	创建 Fragment 视图，状态为 INITIALIZED 时调用 OnCreateView
  ResumeView	恢复 Fragment 视图，状态为 CREATED 时调用 OnResumeView
  PauseView	暂停 Fragment 视图，状态为 RESUMED 时调用 OnPauseView
  DestroyView	销毁 Fragment 视图，状态为 RESUMED 或 CREATED 时调用 OnDestroyView
  GetFragmentView	获取 Fragment 所持有的 UIViewGroup 视图对象
  GetState	获取当前 Fragment 生命周期状态

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

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

OHOS::UIFragmentManager

UIFragment 管理器，通过 id 检索 Fragment 实例

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetInstance	获取 UIFragmentManager 单例引用
  AddFragment	根据 id 注册 UIFragment 实例
  RemoveFragment	根据 id 移除已注册的 UIFragment 实例
  GetFragmentById	根据 id 查找并返回已注册的 UIFragment 实例
  GetFragmentsCount	获取已注册的 Fragment 数量

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

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

Functions

OHOS::UIFragment

UIFragment

UIFragment(const std::string& id)

功能说明

• 构造 UIFragment 对象并绑定标识符 id
• 若 id 非空，该 Fragment 实例自动注册到 UIFragmentManager
• 调用者需确保 id 在 UIFragmentManager 中唯一，重复 id 不会被覆盖

入参

名称	参数类型	详细说明	约束取值范围
id	const std::string&	入参只读引用，用于区分和获取不同 UIFragment 实例	非空字符串时注册到 UIFragmentManager；空字符串时不注册

CreateView

UIView* CreateView(void* data = nullptr)

功能说明

• 当 Fragment 状态为 INITIALIZED 时，调用 OnCreateView 创建视图
• 调用后 Fragment 状态转换为 CREATED
• 返回 fragmentView_ 的指针，用于获取 Fragment 创建的视图

入参

名称	参数类型	详细说明	约束取值范围
data	void*	入参指针，传递给 OnCreateView 的自定义数据	默认值为 nullptr；可传入自定义数据结构指针

返回值

• 返回类型：UIView*

返回 Fragment 所持有的视图对象指针

返回值	触发场景
非 nullptr	fragmentView_ 的地址，始终返回
nullptr	不会返回（fragmentView_ 为成员对象，始终有效）

ResumeView

void ResumeView()

功能说明

• 当 Fragment 状态为 CREATED 时，调用 OnResumeView 恢复视图
• 调用后 Fragment 状态转换为 RESUMED
• 建议在 OnResumeView 中设置输入事件监听、请求焦点或启动动画

PauseView

void PauseView()

功能说明

• 当 Fragment 状态为 RESUMED 时，调用 OnPauseView 暂停视图
• 调用后 Fragment 状态转换为 CREATED
• 建议在 OnPauseView 中清除输入事件监听、清除焦点或停止动画

DestroyView

void DestroyView()

功能说明

• 当 Fragment 状态为 RESUMED 或 CREATED 时，调用 OnDestroyView 销毁视图
• 调用后 Fragment 状态转换为 INITIALIZED
• 建议在 OnDestroyView 中销毁属于该 Fragment 的 UIView 或 UIViewGroup

GetFragmentView

UIView* GetFragmentView()

功能说明

• 获取 Fragment 所持有的 UIViewGroup 视图对象的指针
• 返回的是内部成员 fragmentView_ 的地址，该对象生命周期与 Fragment 一致
• 该函数为 const 无修改，调用不改变对象状态

返回值

• 返回类型：UIView*

返回 Fragment 所持有的视图对象指针

返回值	触发场景
非 nullptr	fragmentView_ 的地址，始终返回

GetState

FragmentState GetState()

功能说明

• 获取当前 Fragment 的生命周期状态
• 返回值为 FragmentState 枚举，包含 INITIALIZED、CREATED、RESUMED 三种状态
• 调用不改变对象状态

返回值

• 返回类型：FragmentState

返回当前 Fragment 生命周期状态

返回值	触发场景
FragmentState::INITIALIZED(0)	Fragment 已构造但未创建视图
FragmentState::CREATED(1)	Fragment 视图已创建或已暂停
FragmentState::RESUMED(2)	Fragment 视图已恢复

OHOS::UIFragmentManager

GetInstance

static UIFragmentManager& GetInstance()

功能说明

• 获取 UIFragmentManager 的单例引用
• 使用静态局部变量实现，首次调用时构造实例
• 全局唯一，所有调用者共享同一实例

返回值

• 返回类型：UIFragmentManager&

返回 UIFragmentManager 单例引用

返回值	触发场景
UIFragmentManager&	始终返回单例引用

AddFragment

void AddFragment(const std::string& id, UIFragment* fragment)

功能说明

• 将 UIFragment 实例以指定 id 注册到管理器
• 若 id 已存在，则不覆盖且输出错误日志
• 调用者需确保 fragment 指针有效且 id 唯一

入参

名称	参数类型	详细说明	约束取值范围
id	const std::string&	入参只读引用，Fragment 的唯一标识符	需在管理器中唯一，重复 id 不覆盖
fragment	UIFragment*	入参指针，待注册的 UIFragment 实例	不可为 nullptr；调用方不转移所有权

RemoveFragment

void RemoveFragment(const std::string& id)

功能说明

• 根据 id 从管理器中移除已注册的 UIFragment 实例
• 若 id 不存在，则输出错误日志
• 移除后对应 id 可重新注册新的 Fragment

入参

名称	参数类型	详细说明	约束取值范围
id	const std::string&	入参只读引用，待移除 Fragment 的标识符	需为已注册的 id

GetFragmentById

UIFragment* GetFragmentById(const std::string& id)

功能说明

• 根据 id 查找并返回已注册的 UIFragment 实例
• 若 id 不存在，返回 nullptr 且输出错误日志
• 调用者不应释放返回的 Fragment 对象

入参

名称	参数类型	详细说明	约束取值范围
id	const std::string&	入参只读引用，待查找 Fragment 的标识符	需为已注册的 id

返回值

• 返回类型：UIFragment*

返回匹配 id 的 UIFragment 实例指针

返回值	触发场景
非 nullptr	找到匹配 id 的 Fragment 实例
nullptr	id 未注册

GetFragmentsCount

uint32_t GetFragmentsCount()

功能说明

• 获取当前已注册的 Fragment 数量
• 返回内部 unordered_map 的 size
• 调用不改变对象状态

返回值

• 返回类型：uint32_t

返回已注册 Fragment 的数量

返回值	触发场景
0	无已注册 Fragment
>0	已注册 Fragment 的数量

Enumerations

FragmentState

enum class FragmentState : uint8_t {
    INITIALIZED,
    CREATED,
    RESUMED
};

枚举成员	取值	描述
INITIALIZED	0	Fragment 已构造但未创建视图
CREATED	1	Fragment 视图已创建
RESUMED	2	Fragment 视图已恢复