android-frame/frame/effect/CLAUDE.md

Effect 模块

模块概述

Effect 模块是动画效果播放框架，支持多种动画格式的播放和管理，包括 SVGA、VAP、Lottie 等动画格式，提供统一的动画播放接口。

主要功能

1. 多格式支持

• SVGA动画: 支持SVGA矢量动画播放
• VAP动画: 腾讯VAP动画格式支持
• Lottie动画: Airbnb Lottie动画支持
• GIF动画: 传统GIF动画播放

2. 播放控制

• 播放控制: 播放、暂停、停止、循环
• 进度控制: 动画进度设置和获取
• 速度控制: 播放速度调节功能
• 帧控制: 精确到帧的播放控制

3. 动画管理

• 缓存管理: 动画资源缓存和清理
• 预加载: 动画资源预加载机制
• 内存优化: 内存使用优化和管理
• 生命周期: 动画生命周期管理

4. 交互支持

• 点击事件: 动画区域点击检测
• 动态替换: 动画中图片文字动态替换
• 状态回调: 动画播放状态回调
• 自定义控制: 自定义动画控制逻辑

核心接口

interface EffectPlayer {
    fun loadAnimation(source: AnimationSource)
    fun play()
    fun pause()
    fun stop()
    fun setLoop(loop: Boolean)
    fun setSpeed(speed: Float)
    fun setAnimationListener(listener: AnimationListener)
}

interface AnimationListener {
    fun onAnimationStart()
    fun onAnimationEnd()
    fun onAnimationCancel()
    fun onAnimationRepeat()
}

使用方式

// 创建动画播放器
val effectPlayer = EffectPlayer.create(context, effectView)

// 设置监听器
effectPlayer.setAnimationListener(object : AnimationListener {
    override fun onAnimationStart() {
        // 动画开始
    }
    
    override fun onAnimationEnd() {
        // 动画结束
        hideEffectView()
    }
})

// 加载并播放动画
effectPlayer.loadAnimation(AnimationSource.fromAssets("gift_animation.svga"))
effectPlayer.setLoop(false)
effectPlayer.play()

// 动态替换内容
val dynamicItem = DynamicItem()
dynamicItem.setText("username", "张三")
dynamicItem.setImage("avatar", avatarBitmap)
effectPlayer.setDynamicItem(dynamicItem)

XML配置

<com.adealink.frame.effect.EffectView
    android:id="@+id/effect_view"
    android:layout_width="match_parent"
    android:layout_height="200dp"
    app:effect_auto_play="true"
    app:effect_loop="false"
    app:effect_source="@raw/animation" />

动画格式

SVGA动画

• 矢量动画，文件小，清晰度高
• 支持动态文字和图片替换
• 适合礼物动效、UI动画

VAP动画

• 支持透明通道的MP4动画
• 高质量视频动画效果
• 适合复杂特效动画

Lottie动画

• After Effects导出的JSON动画
• 支持复杂动画效果
• 跨平台兼容性好

性能优化

// 预加载动画
EffectPreloader.preload(listOf(
    "gift1.svga",
    "gift2.svga",
    "entrance.vap"
))

// 内存管理
effectPlayer.setMemoryStrategy(MemoryStrategy.LOW_MEMORY)

// 缓存配置
val cacheConfig = CacheConfig.Builder()
    .maxCacheSize(50 * 1024 * 1024) // 50MB
    .maxCacheCount(100)
    .build()

构建配置

implementation "com.wenext.android:frame-effect:6.0.0"