gif控件¶

1. 使用场景¶

控件基于 LVGL 开发，专属的 gif 动画播放控件，提供 gif 动画硬件解码 + 轻量化播放控制能力，适用于全场景动效开发

2. 接口介绍¶

2.1 基础功能¶

接口函数	功能说明	参数说明
`lv_obj_t lv_gif_dec_create(lv_obj_t parent, const void data, void bg_color, uint8_t out_bp);`	创建基础 gif 控件实例（基于 LVGL 图片对象扩展）	parent：父对象，NULL 表示默认屏幕；data：gif 数据；bg_color：用于接收 gif 背景色的输出参数；out_bp：图形库的色深（如 16/24 位）
`lv_obj_t lv_gif_dec_create_ext(lv_obj_t parent, const void data, void bg_color, uint8_t out_bp, uint8_t order, uint16_t start_frame_no);`	创建支持播放顺序、起始帧配置的 gif 控件实例	order：播放顺序（0 为正序，1 为倒序）；start_frame_no：播放起始帧序号
`lv_obj_t lv_gif_dec_create_comm(lv_obj_t parent, const void data, void bg_color, uint8_t out_bp, uint8_t order, uint16_t start_frame_no, uint8_t cache_all);`	创建支持播放顺序、起始帧、缓存策略配置的 gif 控件实例	cache_all：缓存策略（0 为不缓存全部帧，1 为将整个 gif 资源存入缓存）
`void lv_gif_dec_restart(lv_obj_t *img);`	重置 gif 播放状态，恢复至起始帧并重新开始播放	img：已初始化的 gif 控件实例对象
`uint16_t lv_gif_dec_frame_num(lv_obj_t *img);`	获取 gif 资源的总帧数	img：已初始化的 gif 控件实例对象
`lv_timer_t lv_gif_dec_task_create(lv_obj_t img, uint16_t peroid);`	创建 gif 帧播放定时器，驱动 gif 帧自动切换	img：已初始化的 gif 控件实例对象；peroid：帧切换间隔（单位：ms），值越小播放速度越快
`void lv_gif_dec_task_pause(lv_obj_t *img, bool rel_gif);`	暂停 gif 播放，可选择是否释放帧缓存以节省内存	img：已初始化的 gif 控件实例对象；rel_gif：缓存释放标识（true 释放 gif 帧缓存，false 保留缓存）
`void lv_gif_dec_task_resume_with_delay(lv_obj_t *img, uint16_t delay_play_time);`	启动/恢复 gif 播放，支持配置延时触发时长	img：已初始化的 gif 控件实例对象；delay_play_time：播放启动/恢复的延时时长（单位：ms）
`void lv_gif_dec_task_resume(lv_obj_t *img);`	立即启动/恢复 gif 播放（无延时）	img：已初始化的 gif 控件实例对象
`void lv_gif_dec_task_del(lv_obj_t *img);`	删除 gif 播放定时器（仅销毁定时器，不释放控件本体及 gif 资源）	img：已初始化的 gif 控件实例对象
`void lv_gif_dec_destroy(lv_obj_t *img);`	销毁 gif 控件实例，释放控件关联的所有资源（内存、缓存、定时器等）	img：已初始化的 gif 控件实例对象
`int lv_gif_dec_next_frame(lv_obj_t *img);`	获取并切换至 gif 下一帧图像	img：已初始化的 gif 控件实例对象；返回值：0 表示已到最后一帧，1 表示获取下一帧成功
`int lv_gif_dec_indicated_frame(lv_obj_t *img, uint16_t frame_no);`	获取并切换至 gif 指定序号的帧图像	img：已初始化的 gif 控件实例对象；frame_no：目标帧的序号；返回值：0 表示已到最后一帧，1 表示获取成功
`void lv_gif_dec_end_cb_register(lv_obj_t *img, loop_end_func func);`	注册 gif 播放完成回调函数（播放至最后一帧时触发）	img：已初始化的 gif 控件实例对象；func：播放完成回调函数指针

2.2 扩展功能¶

为满足需使用封面、延迟启动 gif 播放的场景，基于 gif 控件封装了简易的 lvsf_gif_anim 控件。

接口函数	功能说明	参数说明
`lvsf_gif_anim_t lvsf_gif_anim_init(lv_obj_t parent,const void gif_data, const void src_img, lv_coord_t x, lv_coord_t y, uint32_t duration, uint32_t delay);`	创建带封面、延时播放能力的 gif 自定义控件实例（基于 LVGL 图片对象扩展）	parent：父对象（容器/屏幕）；gif_data：gif 动效数据；src_img：gif 封面图片数据；x/y：控件在父对象中的 X/Y 轴坐标；duration：帧播放间隔（单位：ms）；delay：播放启动延时时长（单位：ms）
`void lvsf_gif_anim_set_zoom(lvsf_gif_anim_t *gif_anim,int width_zoom,int height_zoom);`	设置 gif 整体缩放比例	gif_anim：已初始化的 `lvsf_gif_anim` 控件实例；width_zoom：宽度缩放比；height_zoom：高度缩放比；注：最终取宽高缩放比的最小值执行整体缩放
`void lvsf_gif_anim_resume(lvsf_gif_anim_t *gif_anim);`	启动/恢复 gif 动画播放	gif_anim：已初始化的 `lvsf_gif_anim` 控件实例
`void lvsf_gif_anim_pause(lvsf_gif_anim_t *gif_anim);`	暂停 gif 动画播放（保留当前帧画面，不释放资源）	gif_anim：已初始化的 `lvsf_gif_anim` 控件实例
`void lvsf_gif_anim_deinit(lvsf_gif_anim_t *gif_anim);`	销毁 `lvsf_gif_anim` 控件实例，释放所有关联资源（内存、定时器、缓存等）	gif_anim：已初始化的 `lvsf_gif_anim` 控件实例

3. 示例说明¶

3.1 gif 基础控件示例¶

// 定义变量接收 gif 背景色（由 lv_gif_dec_create 接口输出）
lv_color_t bg_color;

// 创建 gif 解码播放控件实例
// 父对象：当前活动屏幕；gif 数据：通过项目自定义宏 APP_GET_gif 获取；
// 背景色输出：&bg_color；色深：LV_COLOR_DEPTH（LVGL 图形库默认色深宏）
lv_obj_t *bg_gif = lv_gif_dec_create(lv_scr_act(), APP_GET_gif(img_gif_demo), &bg_color, LV_COLOR_DEPTH);

// 设置 gif 控件在父对象（屏幕）中居中对齐（无 X/Y 轴偏移）
lv_obj_align(bg_gif, LV_ALIGN_CENTER, 0, 0);

// 创建帧播放定时器，设置帧间隔 50ms（控制播放速度）
lv_gif_dec_task_create(bg_gif, 50);

// 将 gif 控件移至背景层显示，避免遮挡上层控件（适合作为背景动效）
lv_obj_move_background(bg_gif);

3.2. gif_anim示例¶

// 全局/静态变量：保存 gif_anim 控件实例
static lvsf_gif_anim_t *charge_gif = NULL;
static void on_start(void)
{
    // 初始化控件：父对象parent + gif数据 + 封面图数据 + 坐标(0,0) + 帧间隔 + 启动延时
    charge_gif = lvsf_gif_anim_init(parent,
                                    APP_GET_gif(img_gif_demo),
                                    APP_GET_IMG(img_gif_demo_surface),
                                    0, 0,
                                    LV_DISP_DEF_REFR_PERIOD * 3,  // 帧间隔：默认刷新周期*3
                                    100);                         // 启动延时：100ms
}

static void on_resume(void)
{
    // 省略业务逻辑...
    // 启动/恢复 gif 动画播放,暂停后调用可从当前帧继续播放，首次调用从第一帧开始
    if (charge_gif) {
        lvsf_gif_anim_resume(charge_gif);
    }
}

static void on_pause(void)
{
    // 省略业务逻辑...
    // 暂停 gif 动画播放,暂停后仅停止帧切换，保留当前帧画面，控件资源不释放，可调用 resume 恢复
    if (charge_gif) {
        lvsf_gif_anim_pause(charge_gif);
    }
}

static void on_stop(void)
{
    if (charge_gif) {
        // 销毁控件，释放所有资源（内存/定时器/图片缓存等
        lvsf_gif_anim_deinit(charge_gif);
        // 置空实例，标记已销毁
        charge_gif = NULL;
    }
}

3.3. 示例资源目录¶

3.3 案例效果展示¶

4. 注意事项¶

gif 图像不支持透明度，如需实现透明效果，可考虑使用 apng控件或 seqframe控件。