场景动画¶
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 启动动画接口（power_on_anim_open）¶
开关机动画open接口，用于启动播放动画。
/**
This function starts playing the startup animation.
Note:
When calling this function, it must be in the task of lv_task (or lv_timer) and must be blocked by power_on_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.
*/
int power_on_anim_open(power_on_anim_type_t anim_type, uint32_t play_time)
动画类型枚举定义
/**
* @brief The type of Power on and Power off animation.
*/
typedef enum
{
LOW_VOLT_CHARGING_ANIM, /**< charging animation icon of low voltage */
LOW_VOLT_NOTIFY_ANIM, /**< notification(event) animation icon when low voltage satified */
POWER_ON_ANIM, /**< power on animation when power on */
POWER_OFF_ANIM, /**< power off animation when power off */
} power_on_anim_type_t;
play_time，播放时长，如果为0，则表示gif的默认时长。
2.1.3.2 结束动画接口（power_on_anim_close）¶
开关机动画close接口,用于动画播放结束释放资源，open_lcd，是否打开lcd。
/**
Block the current lv_task (or lv_timer) task and wait for the animation to finish playing.
*/
int power_on_anim_close(bool open_lcd)
2.1.4 资源与代码关联¶
动画资源通过anim_gif数组与类型枚举关联，枚举值顺序需与数组元素顺序严格一致。
static const anim_gif_t anim_gif[] =
{
(lv_img_dsc_t *) APP_GET_GIF_FROM_APP(switch_anim, gif_charging),
(lv_img_dsc_t *) APP_GET_GIF_FROM_APP(switch_anim, gif_charge_flash),
(lv_img_dsc_t *) APP_GET_GIF(gif_power_on),
(lv_img_dsc_t *) APP_GET_GIF(gif_power_off),
};
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秒后，设备将自动进入休眠状态，直至电量充至开机阈值
*/
power_on_anim_open(LOW_VOLT_CHARGING_ANIM, 2000);
4. 低电警示动画¶
低电警示动画是指设备在无充电状态下开机时，系统会实时检测当前电池电压，若电压值低于预设阈值，将自动启动低电警示动画页面并播放；该机制会阻止开机程序继续运行，有效规避因低电量强制开机所引发的各类系统运行异常
低电警示动画的操作接口及资源配置规则与开关机动画完全一致，相关配置说明详情参考：开关机动画
功能实现核心接口如下：
/**
* @brief 启动低电压警示动画播放
* @param LOW_VOLT_NOTIFY_ANIM 低电警示动画类型枚举值
* @param 5000 动画播放时长，单位：毫秒(ms)
* @note 低电警示动画播放5秒后，系统将检测当前充电状态，未充电则自动执行关机保护；已充电则切换至充电动画流程
*/
power_on_anim_open(LOW_VOLT_NOTIFY_ANIM, 5000);
5. 界面切换动画¶
5.1 支持的动画类型¶
系统内置多种页面切换动画类型，可按需选择配置，枚举定义如下：
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_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 平铺切换动画¶
平铺切换动画，用于配置平铺卡片之间的切换动效，系统内置多种标准动画类型，枚举定义如下：
/**
* @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翻转
六扇门
enum
{
TLV_ANIM_TRANS_NONE = 0,
TLV_ANIM_TRANS_ZOOM,
TLV_ANIM_TRANS_FADE
TLV_ANIM_TRANS_TURN_3D_HOR,
TLV_ANIM_TRANS_TURN_Y,
TLV_ANIM_TRANS_DRAG,
TLV_ANIM_TRANS_RING
}
6.2. 配置MASK效果¶
系统的页面进出动画框架中已集成 MASK 蒙版效果架构，无需开发额外逻辑，只需完成基础配置及资源添加，即可实现带 MASK 蒙版的切换动画效果，配置步骤如下：
在工程配置项中，使能配置项 ‘Enbel app trans animation mask function’，开启 MASK 蒙版功能；
在资源目录的mask文件夹中，放入对应的 MASK 蒙版图片，注意：蒙版图片的分辨率必须与动画缓存区分辨率保持一致；
在系统初始化阶段，调用接口 ‘app_trans_anim_mask_set_src’ 将蒙版图片资源句柄配置到动画框架，完成全部配置
配置完成后，切换应用及页面时，即可展示带 MASK 蒙版效果的切换动画。