ezipa控件¶

1. 使用场景¶

本控件基于lvsf_ezipa组件实现APNG（动态PNG）格式图片的解析、播放、控制等功能，适用于需要带透明度图片组成的序列帧动画。

2. 接口介绍¶

2.1 核心数据结构（关键说明）¶

结构体/枚举	说明
lv_ezipa_status_t	APNG播放状态枚举，包含`LV_EZIPA_STOP`（停止）、`LV_EZIPA_CURR`（当前帧）、`LV_EZIPA_NEXT`（下一帧）
lv_ezipa_ext_t	lv_ezipa`控件扩展数据结构，包含播放动画、解码实例、循环次数、播放间隔、回调函数等核心控制参数（上层使用无需直接修改）
lv_ezipa_end_cb_t	播放结束回调函数类型，原型为`void ()(lv_obj_t ezipa)`，播放完成后触发

2.2 核心接口列表¶

接口函数	功能说明	参数说明
lv_obj_t lv_ezipa_create(lv_obj_t parent)`	创建APNG播放控件	parent`：父对象（如lv_scr_act()），返回创建的ezipa控件对象
void lv_ezipa_set_src(lv_obj_t ezipa, const char src)	设置APNG文件源路径	ezipa`：控件对象；`src`：APNG文件路径（如"fs:/xxx.apng"）
void lv_ezipa_set_surface(lv_obj_t ezipa, const void src)	设置APNG播放背景层	ezipa`：控件对象；`src`：背景层数据源（格式与APNG适配）
void lv_ezipa_pause(lv_obj_t *ezipa)	暂停APNG播放	ezipa`：控件对象
void lv_ezipa_resume(lv_obj_t *ezipa)	恢复APNG播放	ezipa`：控件对象
void lv_ezipa_resume_with_delay(lv_obj_t *ezipa, uint16_t delay_time)	延迟恢复播放	ezipa`：控件对象；`delay_time`：延迟时间（单位：ms）
void lv_ezipa_set_loop_times(lv_obj_t *ezipa, int times)	设置播放循环次数	ezipa`：控件对象；`times`：-1（无限循环）、0（播放1次）、N（播放N次）
void lv_ezipa_set_play_end_cb(lv_obj_t *ezipa, lv_ezipa_end_cb_t cb)	设置播放结束回调	ezipa`：控件对象；`cb`：播放结束触发的回调函数
void lv_ezipa_set_interval(lv_obj_t *ezipa, int32_t interval)	强制设置帧播放间隔	ezipa`：控件对象；`interval`：帧间隔（ms），>0时覆盖APNG内置间隔
void lv_ezipa_set_zoom(lv_obj_t *ezipa, uint16_t zoom)	设置APNG缩放比例	ezipa`：控件对象；`zoom`：缩放值（LVGL标准缩放参数）
void lv_ezipa_set_opa(lv_obj_t *ezipa, uint16_t opa)	设置APNG透明度	ezipa`：控件对象；`opa`：透明度（0~255，0全透，255不透明）

3. 使用案例¶

3.1 基础使用示例¶

static lv_obj_t* p_apng = NULL;
static void apng_play_end_cb(lv_obj_t* ezipa)
{
    rt_kprintf("play end.\n");
}

static void on_start(void)
{
    p_apng = lv_ezipa_create(lv_scr_act());
    lv_ezipa_set_src(p_apng, APP_GET_IMG(apng));
    lv_ezipa_set_surface(p_apng, APP_GET_IMG(apng_thum));
    lv_ezipa_set_interval(p_apng, 50);
	//默认为循环模式，只有设置非循环模式下设置回调函数才有效被调用
    //lv_ezipa_set_loop_times(p_apng, 0);
    //lv_ezipa_set_play_end_cb(p_apng, apng_play_end_cb);
    lv_obj_center(p_apng);
}

static void on_resume(void)
{
    lv_ezipa_resume(p_apng);
}

static void on_pause(void)
{
    lv_ezipa_pause(p_apng);
}

static void on_stop(void)
{
    p_apng = NULL;
}

3.3 案例效果展示¶

4. 注意事项¶

图片后缀：序列帧图片合成后的apng文件后缀为png。
循环次数规则：
- loop_times = -1：无限循环播放,默认为循环模式；
- loop_times = 0：播放1次后停止；
- loop_times > 0：按设定次数循环播放。
回调函数注意：只有当循环次数设置为非循环模式时，才会被调用，否则不会调用。