弹窗（POPUP）¶
1. 内置弹窗¶
1.1 注册¶
1.1.1 注册接口¶
注册弹窗调用以下接口即可
POPUP_REGISTER(id, priority, time, ptr_size)
参数说明：
id：弹窗的唯一标识符（自定义名称）
priority：弹窗优先级，数值越大，优先级越高
time：弹窗自动退出时长，单位：毫秒
ptr_size：弹窗全局内存大小，由框架统一分配管理
1.1.2. 弹窗消息类型说明¶
POPUP_MSG_HANDLER 中popup_msg_t 类型如下：
消息类型 |
触发时机 |
核心用途与处理要点 |
|---|---|---|
|
弹窗启动时 |
可进行数据初始化及背景页面创建，此消息仅接收一次 |
|
弹窗激活时 |
仅在弹窗处于暂停（ |
|
弹窗暂停时 |
仅在弹窗处于启动、激活或重新刷新状态时可被调用，用于暂停弹窗的运行 |
|
弹窗刷新时 |
当收到重复的弹窗消息时被调用，用于更新弹窗内容 |
|
弹窗销毁时 |
需释放用户申请的内存及删除创建的任务，当前屏幕上的对象无需主动删除 |
|
弹窗摧毁时 |
不会立即执行，在应用涉及列表嵌套时设置，将在退出列表循环后执行 |
|
弹窗挂起时 |
触发时不会创建新的弹窗消息，用于临时挂起弹窗 |
1.1.3 调度接口¶
运行已注册的弹窗，调用接口：
/**
* @brief 运行指定ID的弹窗
* @param id 弹窗唯一标识符，与注册时的id保持一致
* @param user_data 用户自定义数据，可透传给弹窗内部回调函数，无数据传NULL
* @return int 执行状态码，执行成功返回0，失败返回对应错误码
*/
int popup_run(const char *id, void *user_data)
弹窗销毁相关接口：
/**
* @brief 退出指定ID的弹窗，释放对应弹窗资源
* @param id 弹窗唯一标识符
* @return int 执行状态码，执行成功返回0，失败返回对应错误码
*/
int popup_exit(const char *id)
/**
* @brief 销毁当前系统中所有已创建的弹窗，清空全部弹窗资源
* @return int 执行状态码，执行成功返回0，失败返回对应错误码
*/
int popup_destroy_all(void)
1.2 示例¶
注册找手机提醒弹窗示例：
/**
* @brief 弹窗启动回调函数 (对应POPUP_MSG_ONSTART)
* @param param 弹窗节点句柄，对应框架内部结构体‘popup_node_t’指针
* @note 弹窗创建初始化时触发，该回调只会执行一次，做页面初始化/内存赋值/配置初始化
*/
static void on_start(void *param)
{
// 获取弹窗框架分配的内存指针，强转为当前弹窗结构体类型
p_find_phone_win = (popup_find_phone_t *) POPUP_GET_NODE_MEM_PTR;
// 断言校验，防止内存分配失败导致的空指针操作
RT_ASSERT(p_find_phone_win);
// 关闭屏幕锁屏功能，保证弹窗正常显示与操作
app_screen_lock_enable(false);
// 弹窗页面UI创建：背景页面、文本标签、图标、按钮等控件初始化及布局
// 弹窗业务数据初始化、定时器创建、事件回调注册等逻辑
...
}
/**
* @brief 弹窗刷新回调函数 (对应POPUP_MSG_ONREFR)
* @param param 弹窗节点句柄，对应框架内部结构体‘popup_node_t’指针
* @note 弹窗收到重复的启动指令时触发，用于更新弹窗内容，避免重复创建弹窗
*/
static void on_refr(void *param)
{
// 指针非空校验，防止非法内存访问导致程序崩溃
if (p_find_phone_win && p_find_phone_win->bg_page)
{
// 清空弹窗背景页的所有子控件，准备重新绘制刷新内容
lv_obj_clean(p_find_phone_win->bg_page);
// 重新绘制弹窗页面、更新实时展示数据、刷新控件状态等逻辑
...
}
}
/**
* @brief 弹窗销毁回调函数 (对应POPUP_MSG_ONSTOP)
* @param param 弹窗节点句柄，对应框架内部结构体‘popup_node_t’指针
* @note 弹窗退出销毁时触发，做资源释放、状态复位等收尾操作
*/
static void on_stop(void *param)
{
// 全局指针置空，防止野指针访问
p_find_phone_win = NULL;
// 恢复屏幕锁屏功能，还原系统默认状态
app_screen_lock_enable(true);
// 释放用户手动申请的内存、删除自定义定时器/任务等收尾操作
// 控件无需手动删除，由框架自动清理
...
}
// 注册找手机的提醒弹窗
// 优先级：3，自动退出时间：10000ms，内存大小：sizeof(popup_find_phone_t)
POPUP_REGISTER("find_phone", 3, 10000, sizeof(popup_find_phone_t));
参考例程路径：solution\examples\watch\application\popup\find_phone。
2. 外置弹窗¶
2.1 注册¶
外置弹窗的注册流程、调用接口与内置弹窗完全一致，仅需在当前弹窗文件最开头添加以下宏定义即可启用外置弹窗模式：
#define DYN_APP
⚠️注意事项
目前单个应用仅支持注册一个弹窗实例；若业务场景需要实现多弹窗功能，可在当前注册的弹窗页面业务逻辑中，通过自定义标识 / 消息类型做逻辑区分，在同一个弹窗回调内实现不同样式、不同内容的多弹窗展示效果。
2.2 示例¶
注册闹钟提醒弹窗示例：
// 定义宏开启外置弹窗模式，必须写在文件最开头
#define DYN_APP
// 定义模块名称（必须与动态应用APP_ID相同，模拟器调试使用）
#define _MODULE_NAME_ 'alarm'
// 包含资源使用接口头文件
#include "app_module.h"
// 弹窗相关结构体定义、全局变量声明
// 弹窗ONSTART/ONREFR/ONSTOP等回调函数实现
// 业务逻辑处理代码
...
// 注册闹钟提醒弹窗
// 优先级：5，自动退出时间：30000ms，内存大小：sizeof(popup_alarm_t)
POPUP_REGISTER("alarm", 5, 30000, sizeof(popup_alarm_t));
参考例程路径：solution\examples\_dynamic_app\c\app\alarm\src\popup_alarm.c。