场景动画¶
1. 简介¶
场景动画体系主要包含开关机动画和切换动画两大核心模块，覆盖设备开机、关机、低电压充电等系统级场景， 以及应用 / 页面切换的交互级场景，支持自定义替换、灵活配置，适配不同分辨率与应用需求。
2. 开关机动画 ¶
Solution支持通过资源替换或接口配置两种方式自定义开关机动画，涵盖开机、关机、低电压、充电等多场景动画，适配不同分辨率与应用需求。
2.1. 自定义开关机动画¶
2.1.1 资源路径规范¶
开关机动画资源需按分辨率分类存放，默认路径为：resource/images/power_on/[目标分辨率目录]/
例如 410x494 分辨率的开机动画需放入 power_on/410x494/ 目录下。
2.1.2 支持资源类型¶
开关机动画资源可以支持如下几种类型：
单独一张图片，如png或jpg
png的序列帧，遵循序列帧规则
gif
2.1.3 接口说明¶
2.1.3.1 启动动画接口（app_pm_anim_open）¶
app_pm_anim_open接口用于启动播放开关机、低电压充电、低电提示等 PM 动画。调用该接口后会创建高优先级动画线程，默认每 30 ms 刷新一次动画。调用方必须在
lv_task或lv_timer任务中调用，并在后续调用app_pm_anim_close等待动画播放结束，避免界面刷新函数重入。play_time为动画总播放时长，单位 ms：当
play_time到达设置时长时，动画会立即退出；当动画在
play_time到达前已播放完成，会从头循环播放，直到达到play_time；当
play_time设置为 0 时，动画只播放一次，播放完成后停止。
/**
* This function use to playing the pm animation. such as power on, power off, charging, low_voltage charged.
* Note:
* When calling this function, it must be in the task of lv_task (or lv_timer) and must be blocked by pm_anim_close,
* as this function starts a high priority thread and plays animations every 30ms (adjustable).
* The function that plays animations directly calls the refresh function.
* If not blocked, the refresh function will experience reentry, leading to unpredictable consequences.
* @param anim_type pm_anim_type_t.
* @param play_time The playing time of the animation.
* After the animation starts playing, the play_time is used as the timeout standard.
* If the duration set by play_time is reached during the animation playback, the playback will exit immediately.
* If the animation finishes playing within the play_time duration,
* it will restart from the beginning and loop in this way until the play_time duration is reached and then exit.
* If play_time is set to 0, the animation will only play once and stop directly after the playback is completed.
* @retval rt_err_t RT_EOK or RT_ERROR.
*/
int app_pm_anim_open(pm_anim_type_t anim_type, uint32_t play_time)
动画类型枚举定义（定义位置：
solution/framework/service/srv_app/pm/app_pm.h）
typedef enum
{
POWER_ON_ANIM, /**< power on animation when power on */
POWER_OFF_ANIM, /**< power off animation when power off */
LOW_VOLT_CHARGING_ANIM, /**< charging animation icon of low voltage */
LOW_VOLT_NOTIFY_ANIM, /**< notification(event) animation icon when low voltage satified */
PM_ANIM_TYPE_NUM, /**< Place it at the end of anim_type to indicate the number of animation types.*/
} pm_anim_type_t;
2.1.3.2 结束动画接口（app_pm_anim_close）¶
app_pm_anim_close 接口用于阻塞当前 lv_task 或 lv_timer 任务，等待动画播放结束并释放动画资源。open_lcd 仅用于开机低电提示动画场景，只有在充电后电量满足开机条件时才设置为 true。
/**
* Block the current lv_task (or lv_timer) task and wait for the animation to finish playing.
* @param open_lcd It is only for playing the animation of the low battery reminder during boot.
* It will be set to true only when the charged battery level meets the boot scenario conditions.
*/
int app_pm_anim_close(bool open_lcd)
2.1.4 资源与代码关联¶
默认动画资源通过anim_default_img数组与pm_anim_type_t枚举关联，数组元素顺序需与枚举值顺序严格一致。
static const anim_img_t anim_default_img[PM_ANIM_TYPE_NUM] =
{
#ifdef PM_ANIM_ENABLE
{(lv_img_dsc_t *) APP_GET_GIF(gif_power_on), 0, 30},
{(lv_img_dsc_t *) APP_GET_GIF(gif_power_off), 0, 30},
{(lv_img_dsc_t *) APP_GET_GIF(gif_charging), 0, 30},
{(lv_img_dsc_t *) APP_GET_GIF(gif_charge_flash), 0, 30}
#else
0
#endif
};
2.2. 动画替换方法¶
支持两种替换方式：直接替换资源文件（简单场景）、通过接口配置资源（灵活场景）。
2.2.1 直接替换资源文件¶
准备目标 资源，保持文件名与原资源一致（如替换开机动画需命名为
gif_power_on.gif）；将资源放入对应分辨率的
power_on目录下，覆盖原文件即可；重新编译工程，动画会自动加载新资源。
2.2.2 接口配置资源替换¶
通过app_pm_anim_set_resource接口自定义动画资源（支持 JPG 等静态资源循环播放），需在gui_thread_entry运行前初始化。
2.2.2.1 步骤 1：定义动画资源结构¶
// 示例：将开机动画替换为welcome.jpg，播放300ms
static anim_img_t pm_anim_fn[] =
{
{APP_GET_JPG(welcome), 300, 0, 1}, // 资源句柄、单帧时长、循环次数、外部资源
};
2.2.2.1 步骤 2：初始化资源配置¶
根据应用类型选择初始化方式，确保在 GUI 线程启动前执行：
2.2.2.1.1 场景 1：动态应用（外置应用）¶
使用DLMODULE_INIT_DEF初始化：
static void xxx_init(void)
{
// 设置动画资源
app_pm_anim_set_resource((anim_img_t *)pm_anim_fn, sizeof(pm_anim_fn) / sizeof(anim_img_t));
epbub_decoder_img_init(); // 图像解码器初始化
LOG_I("%s", __func__);
}
/* 必须在gui_thread_entry运行前初始化 */
#ifdef BSP_USING_PC_SIMULATOR
INIT_PRE_APP_EXPORT(xxx_init);
#else
DLMODULE_INIT_DEF(xxx_init);
#endif
2.2.2.1.2 场景 2：内置应用 / 系统模块¶
使用INIT_PRE_APP_EXPORT初始化：
static void reader_init(void)
{
app_pm_anim_set_resource((anim_img_t *)pm_anim_fn, sizeof(pm_anim_fn) / sizeof(anim_img_t));
epbub_decoder_img_init();
LOG_I("%s", __func__);
}
/* 必须在gui_thread_entry运行前初始化 */
INIT_PRE_APP_EXPORT(reader_init);
2.3. 动画播放完成如何跳转默认应用¶
开机动画播放结束后，系统会调用app_get_poweron_app函数获取默认应用，根据开机类型（恢复出厂开机 / 正常重启）的不同，跳转逻辑存在差异，可按需修改目标应用。
2.3.1 恢复出厂设置重开机¶
流程：开机动画 → 开机向导应用 → 跳转默认应用； 说明：首次开机或恢复出厂设置重开机触发，需完成开机向导（如语言设置、网络配置）后才进入目标应用。
2.3.2 正常重启开机¶
首先根据
app_get_reg_power_on_app获取开机跳转默认应用；如果不存在，则试图获取"Main"应用
2.3.3 修改默认跳转应用¶
修改函数
void app_get_poweron_app(void)的开机逻辑通过
app_set_reg_power_on_app设置新的跳转默认应用。参考如何调整开机后默认启动的应用
3. 充电动画¶
充电动画是指设备在充电状态下开机时，系统会实时检测当前电池电压，若电压值低于预设阈值，将自动启动充电动画页面并循环播放；该机制会阻止开机程序继续运行，有效规避因低电量强制开机所引发的各类系统运行异常
充电动画的操作接口及资源配置规则与开关机动画完全一致，相关配置说明详情参考：开关机动画
功能实现核心接口如下：
/**
* @brief 启动低电压充电动画播放
* @param LOW_VOLT_CHARGING_ANIM 充电动画类型枚举值
* @param 2000 动画播放时长，单位：毫秒(ms)
* @note 充电动画播放2秒后，设备将自动进入休眠状态，直至电量充至开机阈值
*/
app_pm_anim_open(LOW_VOLT_CHARGING_ANIM, 2000);
4. 低电警示动画¶
低电警示动画是指设备在无充电状态下开机时，系统会实时检测当前电池电压，若电压值低于预设阈值，将自动启动低电警示动画页面并播放；该机制会阻止开机程序继续运行，有效规避因低电量强制开机所引发的各类系统运行异常
低电警示动画的操作接口及资源配置规则与开关机动画完全一致，相关配置说明详情参考：开关机动画
功能实现核心接口如下：
/**
* @brief 启动低电压警示动画播放
* @param LOW_VOLT_NOTIFY_ANIM 低电警示动画类型枚举值
* @param 5000 动画播放时长，单位：毫秒(ms)
* @note 低电警示动画播放5秒后，系统将检测当前充电状态，未充电则自动执行关机保护；已充电则切换至充电动画流程
*/
app_pm_anim_open(LOW_VOLT_NOTIFY_ANIM, 5000);
5. 界面切换动画¶
5.1 支持的动画类型¶
系统内置多种页面切换动画类型，可按需选择配置，枚举定义如下（定义位置：
sdk/middleware/lvgl/lvsf/lvsf_switchanim.h）：
enum
{
LV_SWITCHANIM_NONE = 0, //无动画
LV_SWITCHANIM_PUSH, //右滑动画
LV_SWITCHANIM_ZOOM, //缩放动画
LV_SWITCHANIM_MASK, //mask动画
LV_SWITCHANIM_SPLIT, //分块动画
LV_SWITCHANIM_TURN_AXIS, //转轴动画
LV_SWITCHANIM_TURN_3D, //3D翻转动画
LV_SWITCHANIM_TURN_HALF, //翻页动画
LV_SWITCHANIM_TURN_SWITCH, //切换动画
LV_SWITCHANIM_TURN_BOOK, //翻书动画
LV_SWITCHANIM_SHUTTLE, //穿梭动画
LV_SWITCHANIM_SHUTTER, //百叶窗动画
LV_SWITCHANIM_DEFAULT = 0xff
};
//上述为系统内置的标准切换动画，包含：右滑动画、缩放动画、渐隐动画、分块动画、转轴动画、3D 翻转动画、翻页动画等。
右滑退出
缩放动画
渐隐动画
转轴动画
3D翻转动画
翻页动画画
应用在使用上述内置动画作为页面切换动画时，调用以下接口进行配置即可：
/**
* @brief 设置页面进入时的切换动画类型
* @param major 动画主ID，对应动画大类枚举值
* @param minor 动画次ID，二级分类（例：3D翻转区分水平/垂直方向）
* @param minor_aux 动画匹配副ID，优先级高的动画会覆盖优先级低的动画配置，保证进出动画匹配
*/
void gui_app_set_enter_anim_type(uint16_t major, uint16_t minor, int16_t minor_aux);
/**
* @brief 设置页面退出时的切换动画类型
* @param major 动画主ID，对应动画大类枚举值
* @param minor 动画次ID，二级分类
* @param minor_aux 动画匹配副ID，参数规则与进入动画一致
*/
void gui_app_set_exit_anim_type(uint16_t major, uint16_t minor, int16_t minor_aux);
5.2 添加自定义动画¶
系统提供 ‘BUILTIN_ANIMATION’ 注册接口，用于添加自定义切换动画，核心功能为注册自定义动画类型及对应的动画进度回调函数，实现自定义的切换动效，以默认动画为例说明完整添加流程：
/**
* @brief 自定义动画进度回调函数
* @param baseanim 进出场动画数据句柄，包含动画相关配置参数
* @param anim_obj 动画载体对象（页面截图对象）
* @param progress 动画进度值，用于控制动画执行过程
* @note 根据进度值处理图片的坐标、透明度、形变等操作，实现自定义动画效果
*/
void lv_baseanim_progress_default(lv_baseanim_t *baseanim, lv_obj_t *anim_obj, int32_t progress)
{
if (LV_BASEANIM_EXIT_TYPE == lv_baseanim_get_type(baseanim))
{
lv_coord_t pos = ((LV_HOR_RES_MAX * progress) >> 10);
lv_coord_t opa = LV_OPA_COVER - ((progress * LV_OPA_COVER) >> 10);
lv_obj_align_to(anim_obj, NULL, LV_ALIGN_CENTER, pos, 0);
lv_obj_set_style_img_opa(anim_obj, opa, 0);
}
}
/**
* @brief 注册自定义动画到系统动画框架
* @param pushanim 自定义动画名称
* @param LV_SWITCHANIM_PUSH 自定义动画对应的主ID枚举值
* @param lv_baseanim_progress_default 绑定的动画进度回调函数
* @note 所有动画的主ID序列号不可重复，配置时通过序列号匹配对应动画类型
*/
BUILTIN_ANIMATION(pushanim, LV_SWITCHANIM_PUSH, lv_baseanim_progress_default);
5.3 配置页面进出动画¶
页面的进出场动画配置，统一在页面初始化函数 ‘on_start()’ 中完成，可配置动画类型及动画优先级，未配置时使用系统默认动画及默认优先级（默认优先级为最低）
/**
* @brief 页面初始化函数
* @note 页面进出场动画、优先级配置，均在此函数中完成
*/
void on_start()
{
// 配置页面进入/退出的动画类型为3D水平翻转
gui_app_set_enter_anim_type(LV_SWITCHANIM_TURN_3D, LV_TURN3D_HOR, LV_TURN3D_HOR);
gui_app_set_exit_anim_type(LV_SWITCHANIM_TURN_3D, LV_TURN3D_HOR, LV_TURN3D_HOR);
// 配置动画优先级为低优先级
gui_app_set_anim_prior(LV_SWITCHANIM_PRIOR_LOW, LV_SWITCHANIM_PRIOR_LOW);
// 其他页面初始化逻辑...
}
5.4 临时关闭页面进出动画¶
当应用页面切换的动画效果（如 3D 翻页、滑动等）已开启时，默认会在页面跳转时展示动效。但部分场景下（例如连续启动两个页面，需跳过中间页面的过渡动画），可通过指定方式临时关闭动画，不影响全局动画配置。
操作方法
在调用页面创建接口（如 ‘gui_app_create_page’ 或 'gui_app_create_page_for_app）'后，立即调用以下函数，即可取消当前页面切换的动画过程：
void gui_app_exec_now(void);
实现原理
页面创建接口默认采用异步方式实现，通过 ‘send_msg_to_gui_app_task’ 发送消息触发页面创建，因此会自然触发预设的切换动画；
‘gui_app_exec_now’ 函数会强制同步执行页面创建流程，并在内部调用’app_schedule_enable_trans_anim(false)’ 临时关闭动画开关，从而跳过中间过渡效果
适用场景
多级页面连续跳转时，避免中间页面的过渡动画，提升操作流畅度；
需要快速响应的交互场景，保留正常场景下的动画体验，按需关闭多余动效。
注意事项
该方法仅对当前单次页面切换的动画效果生效，不会全局关闭动画配置；
正常场景下的页面切换，仍然会展示预设的动画效果。
6. 平铺卡片切换动画¶
6.1. 配置平铺卡片切换动画¶
平铺卡片的动画配置分为两大核心内容：平铺滑动模式配置、平铺切换动画配置，两项配置相互独立，可按需组合使用。
6.1.1 平铺滑动模式¶
平铺滑动模式，用于配置卡片滑动至左右两端后的交互逻辑，系统共提供 4 种标准模式，每种模式对应不同的业务场景：
循环模式：卡片列表首尾相连，滑动至两端后可无缝循环切换至另一侧应用；
回弹模式：滑动到两端后触发弹性回弹效果，停留在当前边界，不会切换到下一个应用；
侧边栏模式：滑动至两端后，可触发打开侧边栏配置页面的交互逻辑；
菜单模式：滑动至两端后，自动跳转至系统主菜单页面。
6.1.2 平铺切换动画¶
平铺切换动画，用于配置平铺卡片之间的切换动效，系统内置多种标准动画类型，枚举定义如下（定义位置：solution/framework/gui_fwk/tlv_fwk/tlv_fwk.h）：
/**
* @brief 平铺卡片切换动画类型枚举 [文件：app.md]
*/
enum
{
TLV_ANIM_TRANS_NONE = 0, // 无切换动画
TLV_ANIM_TRANS_ZOOM, // 缩放切换动画
TLV_ANIM_TRANS_FADE, // 渐隐切换动画
TLV_ANIM_TRANS_TURN_3D_HOR, // 水平3D翻转动画
TLV_ANIM_TRANS_TURN_Y, // Y轴压缩动画
TLV_ANIM_TRANS_DRAG, // 拖拽滑动动画
TLV_ANIM_TRANS_RING // 六扇门切换动画
};
缩放动画
渐隐动画
Y轴压缩
3D翻转
六扇门
6.2. 配置MASK效果¶
系统的页面进出动画框架中已集成 MASK 蒙版效果架构，无需开发额外逻辑，只需完成基础配置及资源添加，即可实现带 MASK 蒙版的切换动画效果，配置步骤如下：
在工程配置项中，使能配置项 ‘Enbel app trans animation mask function’，开启 MASK 蒙版功能；
在资源目录的mask文件夹中，放入对应的 MASK 蒙版图片，注意：蒙版图片的分辨率必须与动画缓存区分辨率保持一致；
在系统初始化阶段，按工程中的 MASK 配置示例完成蒙版资源绑定。当前源码未提供
app_trans_anim_mask_set_src接口，避免直接按该名称调用；请以对应工程的 MASK 配置示例或最新头文件声明为准。
配置完成后，切换应用及页面时，即可展示带 MASK 蒙版效果的切换动画。