ezipa控件¶

1. 使用场景¶

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

注意：lv_ezipa_*接口不在solution/framework/gui_widget目录下定义，当前实现位于sdk/middleware/lvgl/lvsf/lvsf_ezipa.h。因此该控件属于UI控件文档中的APNG/eZIPA播放能力说明，但不是solution/framework/gui_widget目录内的组件。

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：按设定次数循环播放。
回调函数注意：只有当循环次数设置为非循环模式时，才会被调用，否则不会调用。