android-frame/frame/util/CLAUDE.md

Util 模块

模块概述

Util 模块是通用工具类集合模块，提供了丰富的 Android 开发常用工具类和扩展函数。该模块涵盖了系统工具、UI 工具、数据处理、文件操作、设备信息、性能优化等多个方面的实用功能。

主要功能

1. 扩展函数 (ext 包)

• BooleanExt: 布尔值扩展
• BundleExt: Bundle 扩展
• ColorExt: 颜色处理扩展
• CommonExt: 通用扩展函数
• FragmentExt: Fragment 扩展
• ImageExt: 图片处理扩展
• IntentExt: Intent 扩展
• ListExt: 列表扩展
• SpanExt: 文本样式扩展
• StringExt: 字符串扩展
• ViewTreeObserverExt: 视图树观察者扩展

2. 系统工具 (util 包)

• ActivityUtil: Activity 相关工具
• AppUtil: 应用相关工具
• DeviceUtil: 设备信息工具
• PackageUtil: 包管理工具
• ProcessUtil: 进程工具
• SystemUtils: 系统工具
• ThreadUtil: 线程工具

3. UI 相关工具

• DisplayUtil: 显示相关工具
• EdgeUtil: 边缘处理工具
• ScreenAutoSizeUtil: 屏幕适配工具
• UIUtil: UI 通用工具
• UnitUtil: 单位转换工具
• ViewUtil: 视图工具
• ViewShotUtil: 截图工具

4. 文件和数据处理

• AssetUtil: 资源文件工具
• CompressUtil: 压缩工具
• FileProvider7: 文件提供者工具 (Android 7+)
• FileUtil: 文件操作工具
• GzipUtils: Gzip 压缩工具
• IOUtil: IO 操作工具
• ImageUtil: 图片处理工具

5. 网络和通信

• LocationUtil: 位置工具
• NetworkUtil: 网络工具
• PhoneUtil: 电话号码工具
• UriUtil: URI 工具

6. 数据处理和算法

• AlgorithmUtil: 算法工具
• HashUtil: 哈希工具
• HexUtil: 十六进制工具
• StringUtil: 字符串处理工具
• TypeUtil: 类型工具
• TimeUtil: 时间工具

7. 调试和性能

• BuildPropertiesUtil: 构建属性工具
• ExceptionUtils: 异常处理工具
• LogcatUtil: 日志工具
• PerformanceUtil: 性能工具
• ReflectUtil: 反射工具
• VersionUtil: 版本工具

8. 特殊工具

• CoroutineUtil: 协程工具
• DelegateUtil: 委托工具
• RomUtil: ROM 识别工具

核心功能分类

系统和设备相关

// 获取设备信息
DeviceUtil.getDeviceInfo()
DeviceUtil.isTablet(context)
DeviceUtil.getScreenDensity(context)

// 应用工具
AppUtil.getVersionName(context)
AppUtil.getVersionCode(context)
AppUtil.isAppInstalled(context, packageName)

// 系统工具
SystemUtils.isMainThread()
SystemUtils.getProcessName(context)

UI 和视图相关

// 单位转换
UnitUtil.dp2px(context, dpValue)
UnitUtil.px2dp(context, pxValue)
UnitUtil.sp2px(context, spValue)

// 视图工具
ViewUtil.setVisible(view, isVisible)
ViewUtil.measureView(view)
ViewUtil.getViewLocation(view)

// 截图工具
ViewShotUtil.takeScreenshot(view)
ViewShotUtil.saveViewAsImage(view, file)

文件和存储

// 文件操作
FileUtil.createFile(path)
FileUtil.deleteFile(file)
FileUtil.copyFile(source, dest)
FileUtil.getFileSize(file)

// Asset 资源
AssetUtil.readAssetFile(context, fileName)
AssetUtil.copyAssetFile(context, assetName, destPath)

// 压缩工具
CompressUtil.compressImage(imagePath, quality)
GzipUtils.compress(data)
GzipUtils.decompress(compressedData)

网络和通信

// 网络状态
NetworkUtil.isNetworkAvailable(context)
NetworkUtil.getNetworkType(context)
NetworkUtil.isWifiConnected(context)

// 电话号码
PhoneUtil.isValidPhoneNumber(phoneNumber)
PhoneUtil.formatPhoneNumber(phoneNumber, countryCode)

数据处理

// 哈希工具
HashUtil.md5(input)
HashUtil.sha1(input)
HashUtil.sha256(input)

// 十六进制
HexUtil.bytesToHex(bytes)
HexUtil.hexToBytes(hex)

// 字符串处理
StringUtil.isEmpty(str)
StringUtil.isNotEmpty(str)
StringUtil.formatString(template, args)

扩展函数示例

// 字符串扩展
"hello".isNotNullOrEmpty()
"123".toIntOrDefault(0)

// 列表扩展
list.isNotNullOrEmpty()
list.safeGet(index)

// 颜色扩展
Color.parseColor("#FF0000").toHexString()

// Intent 扩展
intent.putExtraString("key", "value")
intent.getExtraString("key", "default")

使用方式

1. 基础工具使用

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // 检查网络状态
        if (NetworkUtil.isNetworkAvailable(this)) {
            // 网络可用
        }
        
        // 获取屏幕密度
        val density = DeviceUtil.getScreenDensity(this)
        
        // 单位转换
        val dpValue = UnitUtil.px2dp(this, 100)
    }
}

2. 扩展函数使用

// 字符串扩展
val text = "hello world"
if (text.isNotNullOrEmpty()) {
    // 字符串不为空
}

// 列表扩展
val list = listOf(1, 2, 3)
if (list.isNotNullOrEmpty()) {
    val firstItem = list.safeGet(0) // 安全获取
}

// 视图扩展
view.setVisible(isVisible)
view.setGone(!isVisible)

3. 文件操作

// 读取 Asset 文件
val content = AssetUtil.readAssetFile(context, "config.json")

// 文件压缩
val compressedImage = CompressUtil.compressImage(imagePath, 80)

// 文件拷贝
FileUtil.copyFile(sourceFile, destFile)

4. 系统信息获取

// 获取应用版本
val versionName = AppUtil.getVersionName(context)
val versionCode = AppUtil.getVersionCode(context)

// 检查应用安装
val isInstalled = AppUtil.isAppInstalled(context, "com.example.app")

// 获取进程名
val processName = SystemUtils.getProcessName(context)

依赖关系

编译时依赖

• kotlinx.coroutines - 协程支持
• androidx.core - Android 核心库
• androidx.appcompat - AppCompat 支持
• play-feature-delivery - Google Play 功能交付
• google-libphonenumber - 电话号码处理
• okio - IO 操作库
• relinker - 原生库加载
• external:AndroidAutoSize - 屏幕适配

内部依赖

• frame:base - 基础模块
• frame:data - 数据模块
• frame:zero - 零依赖模块

构建配置

implementation "com.wenext.android:frame-util:6.0.2"

注意事项

1. 线程安全: 大部分工具类是线程安全的，但使用时需要注意上下文环境
2. 权限要求: 某些功能需要相应的 Android 权限（如网络状态、定位等）
3. 版本兼容: 工具类考虑了不同 Android 版本的兼容性
4. 内存管理: 使用文件和图片处理工具时注意内存消耗
5. 异常处理: 大多数工具方法都有适当的异常处理
6. 上下文依赖: 许多工具方法需要 Context 参数，注意避免内存泄漏
7. 性能考虑: 某些工具方法可能涉及 IO 操作，建议在后台线程使用
8. 扩展函数: Kotlin 扩展函数提供了更便捷的 API，推荐优先使用