ModernStorage：Android存储操作的一站式解决方案

价值定位：破解Android存储开发的复杂性

Android存储系统长期以来是开发者的痛点所在——从权限管理到API差异，从路径处理到媒体扫描，每个环节都可能成为应用崩溃或用户投诉的源头。ModernStorage作为一套专为Android设计的存储抽象库，通过统一API层解决了以下核心问题：

• 版本碎片化：一套接口兼容Android 5.0至最新版本
• 权限迷宫：自动化处理普通文件与媒体文件的权限请求
• 存储多样性：统一访问内部存储、外部存储与SAF文档
• 媒体管理：简化MediaStore交互与媒体文件元数据处理

场景分析：ModernStorage适用的开发场景

在选择存储方案前，先通过以下决策树判断是否需要ModernStorage：

是否需要兼容Android 10以上版本？→ 是
是否涉及媒体文件管理？→ 是/否
是否需要处理SAF文档选择？→ 是/否
是否希望减少权限处理代码？→ 是

如果以上任一问题回答"是"，ModernStorage将显著提升开发效率。典型应用场景包括：

• 媒体应用：照片编辑器、视频处理工具需要频繁读写媒体文件
• 文件管理器：需要访问多种存储位置的应用
• 文档处理：涉及PDF、Office等文件的导入导出功能
• 社交应用：需要选择并上传图片、视频的场景

模块实战：核心功能的应用指南

权限管理模块（permissions）

适用场景

• Android 6.0+动态权限请求
• 区分媒体文件与普通文件权限
• 权限状态监听与自动重试

核心API

• StoragePermissions：权限状态检查
• RequestAccess：权限请求发起与结果处理

实施步骤

✓ 1. 创建权限管理器实例

val storagePermissions = StoragePermissions(context)

✓ 2. 检查写入权限状态

when {
    storagePermissions.canWriteToMediaStore() -> {
        // 已拥有媒体写入权限
        processMediaFiles()
    }
    storagePermissions.canAccessFiles() -> {
        // 仅有普通文件访问权限
        showMediaAccessWarning()
    }
    else -> {
        // 无权限，发起请求
        requestStorageAccess()
    }
}

✓ 3. 发起权限请求

private fun requestStorageAccess() {
    val request = RequestAccess(context)
    request.requestStoragePermissions(
        includeMedia = true,
        onResult = { granted ->
            if (granted) {
                // 权限已授予，重新执行操作
                processMediaFiles()
            } else {
                showPermissionDeniedDialog()
            }
        }
    )
}

常见误区

• ❌ 混淆普通文件权限与媒体权限的申请时机
• ❌ 未处理权限被永久拒绝的情况
• ❌ 忽略Android 11+的存储权限变更

文件系统模块（storage）

适用场景

• URI与文件路径的转换
• 跨存储区域的文件复制
• 文件元数据提取

核心API

• AndroidFileSystem：系统文件操作实现
• SharedFileSystem：共享存储访问
• PathUtils：路径与URI转换工具

实施步骤

✓ 1. 初始化文件系统

val fileSystem = AndroidFileSystem(context)

✓ 2. URI转文件路径（适用Android 10以下）

val uri = Uri.parse("content://media/external/images/media/123")
val path = PathUtils.getPathFromUri(context, uri)

✓ 3. 复制文件到下载目录

val sourceUri = Uri.fromFile(File(context.cacheDir, "temp.pdf"))
val destinationUri = fileSystem.copyToDownloads(
    source = sourceUri,
    fileName = "report.pdf",
    mimeType = "application/pdf"
)

常见误区

• ❌ 在Android 10+使用File API访问外部存储
• ❌ 未处理SAF返回的临时URI权限
• ❌ 忽略文件操作的异常处理

照片选择器模块（photopicker）

适用场景

• 从系统相册选择图片/视频
• 支持单选与多选模式
• 兼容Android 11+的照片选择器API

核心API

• PhotoPicker：照片选择器封装类

实施步骤

✓ 1. 创建选择器实例

val photoPicker = PhotoPicker(context)

✓ 2. 启动单选模式选择

photoPicker.launchSingleImagePicker { uri ->
    uri?.let {
        // 处理选中的图片URI
        loadImage(it)
    }
}

✓ 3. 启动多选模式选择

photoPicker.launchMultiImagePicker(
    maxItems = 5,
    onResult = { uris ->
        if (uris.isNotEmpty()) {
            // 处理选中的多个图片URI
            showSelectedImages(uris)
        }
    }
)

常见误区

• ❌ 在低版本设备上未提供回退方案
• ❌ 未处理选择器取消的情况
• ❌ 直接使用URI而未检查权限有效期

问题解决：常见存储挑战的应对策略

挑战1：Android 10+的作用域存储限制

问题：应用无法直接访问外部存储的非媒体文件
解决方案：使用SAF框架结合ModernStorage的文件系统抽象

// 选择文档文件
val intent = Intent(Intent.ACTION_OPEN_DOCUMENT).apply {
    addCategory(Intent.CATEGORY_OPENABLE)
    type = "application/pdf"
}
startActivityForResult(intent, REQUEST_CODE_DOCUMENT)

// 使用ModernStorage读取内容
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == REQUEST_CODE_DOCUMENT && resultCode == Activity.RESULT_OK) {
        data?.data?.let { uri ->
            val fileSystem = AndroidFileSystem(context)
            val inputStream = fileSystem.getInputStream(uri)
            // 读取文件内容
        }
    }
}

挑战2：媒体文件扫描与更新

问题：新创建的媒体文件未在相册中显示
解决方案：使用ModernStorage的媒体扫描功能

val fileSystem = AndroidFileSystem(context)
val imageFile = File(context.externalCacheDir, "edited_photo.jpg")

// 保存图片后触发媒体扫描
fileSystem.scanMediaFile(
    file = imageFile,
    mimeType = "image/jpeg",
    onScanCompleted = { uri ->
        // 媒体库已更新，可以通过返回的URI访问
        Log.d("MediaScan", "Image added to MediaStore: $uri")
    }
)

挑战3：跨版本存储权限兼容

问题：不同Android版本的权限处理逻辑差异
解决方案：使用权限模块的版本适配能力

val storagePermissions = StoragePermissions(context)

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    // Android 10+使用媒体位置权限
    if (storagePermissions.canAccessMediaLocation()) {
        // 可以访问媒体文件的位置信息
    } else {
        requestMediaLocationPermission()
    }
} else {
    // 旧版本使用WRITE_EXTERNAL_STORAGE
    if (storagePermissions.canWriteToExternalStorage()) {
        // 可以写入外部存储
    } else {
        requestWritePermission()
    }
}

资源拓展：深入学习与应用

官方文档

• 模块详细说明：docs/storage.md
• 媒体库操作指南：docs/mediastore.md
• 权限管理详解：docs/permissions.md

示例代码

• 文件操作示例：sample/src/main/java/com/google/modernstorage/sample/saf/SelectDocumentFileScreen.kt
• 媒体管理示例：sample/src/main/java/com/google/modernstorage/sample/mediastore/AddMediaScreen.kt
• 权限请求示例：sample/src/main/java/com/google/modernstorage/sample/permissions/CheckPermissionScreen.kt

项目结构

• permissions模块 → StoragePermissions → canAccessFiles()/canWriteToMediaStore()
• storage模块 → AndroidFileSystem → copyToDownloads()/scanMediaFile()
• photopicker模块 → PhotoPicker → launchSingleImagePicker()/launchMultiImagePicker()

开始使用

1. 克隆项目仓库

git clone https://gitcode.com/gh_mirrors/mo/modernstorage

2. 根据需求添加模块依赖
3. 参考示例代码实现基础功能
4. 根据应用场景扩展定制功能

ModernStorage通过抽象化存储操作，让开发者能够专注于业务逻辑而非底层实现细节。无论是简单的文件选择还是复杂的媒体管理，这套库都能提供一致且可靠的解决方案，帮助应用在各种Android设备上实现流畅的存储体验。