gif控件¶

1. 使用场景¶

控件基于 LVGL 开发，是 solution/framework/gui_widget 中封装的 GIF 动画播放控件，提供 GIF 动画解码播放、封面显示、延迟启动、暂停/恢复、缩放等控制能力，适用于全场景动效开发。

2. 接口介绍¶

2.1 基础功能¶

gui_widget 对外公开的基础 GIF 控件接口定义在 solution/framework/gui_widget/include/lvsf_gif.h，接口名为 lv_sfgif_*。底层 lv_gif_dec_* 解码接口由该控件内部调用，不作为本控件文档的直接使用入口。

接口函数	功能说明	参数说明
`lv_obj_t lv_sfgif_create(lv_obj_t parent);`	创建 GIF 控件实例	`parent`：父对象，如屏幕或容器
`void lv_sfgif_open(lv_obj_t gif, const char gif_data, const char *src_img, lv_coord_t x, lv_coord_t y, uint32_t anim_time, uint16_t period);`	打开 GIF 资源，可同时设置封面图、控件位置、延迟启动时间和帧间隔	`gif`：GIF 控件；`gif_data`：GIF 数据；`src_img`：封面图数据，可为 `NULL`；`x` / `y`：控件位置；`anim_time`：延迟启动时间，0 表示立即创建 GIF；`period`：帧间隔，0 时使用默认刷新周期
`void lv_sfgif_resume(lv_obj_t *gif);`	启动或恢复 GIF 播放	`gif`：GIF 控件
`void lv_sfgif_pause(lv_obj_t *gif);`	暂停 GIF 播放，保留控件对象	`gif`：GIF 控件
`void lv_sfgif_close(lv_obj_t *gif);`	关闭 GIF 资源，释放内部 GIF 或封面对象	`gif`：GIF 控件
`void lv_sfgif_set_zoom(lv_obj_t *gif, uint16_t zoom);`	设置 GIF 缩放比例	`gif`：GIF 控件；`zoom`：LVGL 图片缩放值，256 表示原始尺寸

2.2 扩展功能¶

为满足需使用封面、延迟启动 GIF 播放的场景，基于 GIF 控件封装了简易的 lvsf_gif_anim 控件，接口定义在 solution/framework/gui_widget/include/lvsf_gif_anim.h。

接口函数	功能说明	参数说明
`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 自定义控件实例	`parent`：父对象；`gif_data`：GIF 动效数据；`src_img`：GIF 封面图片数据；`x` / `y`：控件位置；`duration`：帧播放间隔；`delay`：播放启动延时
`void lvsf_gif_anim_set_zoom(lvsf_gif_anim_t *gif_anim, int width_zoom, int height_zoom);`	设置 GIF 整体缩放比例	`gif_anim`：控件实例；`width_zoom`：宽度缩放比；`height_zoom`：高度缩放比；最终取较小值执行整体缩放
`void lvsf_gif_anim_set_layer(lvsf_gif_anim_t *gif_anim, lvsf_gif_layer_t layer);`	设置 GIF 显示层级	`gif_anim`：控件实例；`layer`：层级枚举值
`void lvsf_gif_anim_enable_bg_color(lvsf_gif_anim_t *gif_anim, bool enable);`	使能或关闭背景色处理	`gif_anim`：控件实例；`enable`：是否启用背景色
`void lvsf_gif_anim_resume(lvsf_gif_anim_t *gif_anim);`	启动或恢复 GIF 动画播放	`gif_anim`：控件实例
`void lvsf_gif_anim_pause(lvsf_gif_anim_t *gif_anim);`	暂停 GIF 动画播放	`gif_anim`：控件实例
`void lvsf_gif_anim_deinit(lvsf_gif_anim_t *gif_anim);`	销毁 GIF 动画控件实例，释放关联资源	`gif_anim`：控件实例

3. 示例说明¶

3.1 GIF 基础控件示例¶

lv_obj_t *bg_gif = lv_sfgif_create(lv_scr_act());

/* 打开 GIF 资源：无封面图、位置为 (0, 0)、立即播放、帧间隔 50 ms */
lv_sfgif_open(bg_gif,
              APP_GET_gif(img_gif_demo),
              NULL,
              0, 0,
              0,
              50);

lv_obj_align(bg_gif, LV_ALIGN_CENTER, 0, 0);
lv_sfgif_resume(bg_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,
                                    100);
}

static void on_resume(void)
{
    if (charge_gif) {
        lvsf_gif_anim_resume(charge_gif);
    }
}

static void on_pause(void)
{
    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.4 案例效果展示¶

4. 注意事项¶

GIF 图像不支持透明度，如需实现透明效果，可考虑使用 apng控件或 seqframe控件。
基础 GIF 控件的公开入口是 lv_sfgif_*；不要在业务文档中直接依赖底层 lv_gif_dec_* 接口。
页面销毁或切换时，建议先调用 lv_sfgif_close 或 lvsf_gif_anim_deinit 释放资源。