android-frame/frame/image/CLAUDE.md

Image 模块

模块概述

Image 模块是基于 Fresco 的图片加载框架封装，提供了统一的图片加载接口、缓存管理、图片处理和显示功能。该模块简化了 Fresco 的使用，提供了更便捷的图片加载 API。

主要功能

1. 图片加载

• 统一的图片加载接口: 支持各种图片源加载
• 多种图片格式支持: JPG、PNG、GIF、WebP 等
• 网络图片缓存: 自动内存和磁盘缓存管理
• 图片预加载: 提前加载图片到缓存

2. 图片处理

• 图片变换: 圆角、裁剪、缩放等处理
• 滤镜效果: 模糊、颜色调整等效果
• 占位图支持: 加载中和失败占位图
• 渐进式加载: 大图分层次显示

3. 自定义视图

• 扩展的 ImageView: 增强功能的图片视图
• 圆形图片视图: 圆形头像等场景
• 可缩放图片视图: 支持手势缩放
• 属性配置: XML 属性配置支持

4. 内存管理

• 智能缓存策略: 根据设备配置自动调整
• 内存监控: 低内存时自动清理
• 缓存清理: 提供手动清理接口

核心接口

// 图片加载器接口
interface ImageLoader {
    fun load(url: String): ImageRequest
    fun load(uri: Uri): ImageRequest
    fun load(resourceId: Int): ImageRequest
    
    fun preload(url: String)
    fun clearCache()
    fun pauseRequests()
    fun resumeRequests()
}

// 图片请求构建器
class ImageRequest {
    fun into(imageView: ImageView)
    fun placeholder(drawable: Drawable): ImageRequest
    fun error(drawable: Drawable): ImageRequest
    fun resize(width: Int, height: Int): ImageRequest
    fun centerCrop(): ImageRequest
    fun centerInside(): ImageRequest
    fun transform(transformation: Transformation): ImageRequest
    fun fade(duration: Int): ImageRequest
}

使用方式

1. 基本图片加载

// 加载网络图片
ImageLoader.load("https://example.com/image.jpg")
    .placeholder(R.drawable.placeholder)
    .error(R.drawable.error)
    .into(imageView)

// 加载本地资源
ImageLoader.load(R.drawable.local_image)
    .into(imageView)

// 加载本地文件
ImageLoader.load(Uri.fromFile(file))
    .into(imageView)

2. 图片变换

ImageLoader.load(imageUrl)
    .resize(300, 200)
    .centerCrop()
    .transform(RoundedCornersTransformation(10))
    .into(imageView)

3. 自定义视图使用

<com.adealink.frame.image.CircleImageView
    android:layout_width="100dp"
    android:layout_height="100dp"
    app:border_width="2dp"
    app:border_color="#ffffff"
    app:src="@drawable/avatar_placeholder" />

4. 预加载和缓存管理

// 预加载图片
ImageLoader.preload("https://example.com/image.jpg")

// 清理缓存
ImageLoader.clearCache()

// 暂停/恢复请求（用于列表滚动优化）
ImageLoader.pauseRequests()
ImageLoader.resumeRequests()

配置选项

// 图片加载配置
class ImageConfig {
    var memoryCache: Boolean = true
    var diskCache: Boolean = true
    var cacheSize: Long = 100 * 1024 * 1024 // 100MB
    var placeholder: Drawable? = null
    var errorDrawable: Drawable? = null
    var fadeInDuration: Int = 300
    var enableProgressiveJPEG: Boolean = true
    var enableWebP: Boolean = true
}

依赖关系

编译时依赖

• com.facebook.fresco - Fresco 图片加载库
• frame:base - 基础框架模块
• frame:util - 工具类模块

功能特性

• 内存优化: 基于 Fresco 的高效内存管理
• 格式支持: 支持多种图片格式包括动图
• 渐进式加载: 大图分层显示提升用户体验
• 网络优化: 智能的网络加载和重试机制

构建配置

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

注意事项

1. 初始化: 需要在 Application 中初始化 Fresco
2. 内存管理: 大图加载注意内存使用，建议使用合适的尺寸
3. 缓存策略: 根据应用需求配置合适的缓存大小
4. 线程安全: 所有 API 都是线程安全的
5. 生命周期: 在页面销毁时不需要手动取消请求
6. 网络权限: 加载网络图片需要网络权限
7. ProGuard: 需要添加 Fresco 相关的混淆规则