Bitmap 持久化到存儲是圖片編輯、截圖分享、緩存、離線下載等場景的核心需求。隨著 Android 存儲權限演進 (分區存儲、MediaStore、SAF),「寫入 SD 卡」的最佳實踐發生根本變化。本文提供全版本兼容方案:應用專屬目錄 (無需權限)、MediaStore 媒體庫 (標準媒體文件)、SAF 文檔選擇器 (用戶指定目錄),並解決壓縮質量、異步寫入、錯誤處理、內存管理等工程化細節。
需要保存圖片
│
├─ 用戶可見、系統相冊展示、長期保留、跨應用共享
│ └─ → MediaStore (Images.Media) 【推薦,API 29+ 無需權限】
│
├─ 僅本應用使用、卸載應用時刪除、隱私數據
│ └─ → 應用專屬目錄 context.getExternalFilesDir(Environment.DIRECTORY_PICTURES) 【無需權限】
│
├─ 用戶自定義保存位置、導出到特定文件夾
│ └─ → SAF (ACTION_CREATE_DOCUMENT) 【用戶授權,無需權限聲明】
│
└─ 兼舊版本 (API < 29) 需寫入公共目錄
└─ → 需 WRITE_EXTERNAL_STORAGE 權限 (用戶授權) + File API
// Kotlin 擴展函數
suspend fun Context.saveBitmapToMediaStore(
bitmap: Bitmap,
displayName: String = "IMG_${System.currentTimeMillis()}.jpg",
mimeType: String = "image/jpeg",
quality: Int = 90,
relativePath: String = Environment.DIRECTORY_PICTURES + "/MyApp"
): Uri? = withContext(Dispatchers.IO) {
val resolver = contentResolver
val contentValues = ContentValues().apply {
put(MediaStore.Images.Media.DISPLAY_NAME, displayName)
put(MediaStore.Images.Media.MIME_TYPE, mimeType)
put(MediaStore.Images.Media.RELATIVE_PATH, relativePath)
put(MediaStore.Images.Media.IS_PENDING, 1) // 標記為處理中,媒體掃描器忽略
}
val uri = resolver.insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, contentValues)
?: return@withContext null
try {
resolver.openOutputStream(uri)?.use { outputStream ->
bitmap.compress(Bitmap.CompressFormat.JPEG, quality, outputStream)
outputStream.flush()
} ?: return@withContext null
// 完成寫入,移除 PENDING 標記
contentValues.clear()
contentValues.put(MediaStore.Images.Media.IS_PENDING, 0)
resolver.update(uri, contentValues, null, null)
// 可選:通知媒體掃描器 (通常自動)
// context.sendBroadcast(Intent(Intent.ACTION_MEDIA_SCANNER_SCAN_FILE, uri))
uri
} catch (e: Exception) {
// 失敗時清理
resolver.delete(uri, null, null)
null
}
}
// 獲取目錄:/storage/emulated/0/Android/data/com.example.app/files/Pictures/
File picturesDir = context.getExternalFilesDir(Environment.DIRECTORY_PICTURES);
if (picturesDir == null) {
// 存儲不可用 (未掛載、USB共享等)
return;
}
File file = new File(picturesDir, "IMG_" + System.currentTimeMillis() + ".jpg");
// 異步寫入
Executors.newSingleThreadExecutor().execute(() -> {
FileOutputStream fos = null;
try {
fos = new FileOutputStream(file);
bitmap.compress(Bitmap.CompressFormat.JPEG, 90, fos);
fos.flush();
// 成功回調主線程
} catch (IOException e) {
// 錯誤處理
} finally {
if (fos != null) try { fos.close(); } catch (IOException ignored) {}
}
});
// 關鍵優勢:
// 1. 無需任何權限聲明
// 2. 卸載應用自動清理
// 3. 不受分區存儲限制
// 4. 可通過 FileProvider 分享給其他應用
// 1. 啟動文檔創建意圖
Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT)
.addCategory(Intent.CATEGORY_OPENABLE)
.setType("image/jpeg")
.putExtra(Intent.EXTRA_TITLE, "IMG_" + System.currentTimeMillis() + ".jpg");
// 可選:指定初始目錄 (API 21+)
// intent.putExtra(DocumentsContract.EXTRA_INITIAL_URI, initialUri);
startActivityForResult(intent, REQUEST_CODE_SAVE_IMAGE);
// 2. onActivityResult 處理
@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (requestCode == REQUEST_CODE_SAVE_IMAGE && resultCode == RESULT_OK && data != null) {
Uri uri = data.getData();
// 獲取持久化權限 (跨重啟保持)
final int takeFlags = Intent.FLAG_GRANT_READ_URI_PERMISSION | Intent.FLAG_GRANT_WRITE_URI_PERMISSION;
getContentResolver().takePersistableUriPermission(uri, takeFlags);
// 異步寫入
saveBitmapToUri(uri, bitmap);
}
}
private void saveBitmapToUri(Uri uri, Bitmap bitmap) {
Executors.newSingleThreadExecutor().execute(() -> {
try (OutputStream os = getContentResolver().openOutputStream(uri)) {
if (os != null) {
bitmap.compress(Bitmap.CompressFormat.JPEG, 90, os);
os.flush();
}
} catch (IOException e) {
Log.e("SaveImage", "SAF save failed", e);
}
});
}
// Manifest 權限
// API 29+ 自動忽略
// 運行時權限請求 (ActivityCompat.requestPermissions)
// 獲取公共圖片目錄
File publicPicturesDir = Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES);
File appDir = new File(publicPicturesDir, "MyApp");
if (!appDir.exists()) appDir.mkdirs();
File file = new File(appDir, "IMG_" + System.currentTimeMillis() + ".jpg");
// 寫入同方案二
// 完成後通知媒體掃描
MediaScannerConnection.scanFile(context, new String[]{file.getAbsolutePath()}, null, null);
| 格式 | 質量參數範圍 | 透明度 | 適用場景 | 典型質量值 |
|---|---|---|---|---|
| JPEG | 0-100 (int) | ❌ 無 | 照片、複雜圖像、體積敏感 | 85-95 (視覺無損/高質量) |
| PNG | 0-100 (被忽略,無損) | ✅ 支持 | 截圖、UI圖標、透明背景、文字圖 | 100 (無損) |
| WEBP | 0-100 (有損/無損) | ✅ 支持 | 綜合最優、現代App首選 | 80-90 (有損)、100 (無損) |
// ViewModel 中
class ImageSaveViewModel : ViewModel() {
private val ioScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
fun saveBitmap(bitmap: Bitmap, saveType: SaveType) {
ioScope.launch {
val result = when (saveType) {
SaveType.MEDIA_STORE -> saveToMediaStore(bitmap)
SaveType.APP_PRIVATE -> saveToAppPrivate(bitmap)
SaveType.SAF_URI -> saveToSafUri(bitmap) // 需傳入 Uri
}
_saveResult.postValue(result)
}
}
private suspend fun saveToMediaStore(bitmap: Bitmap): Result { /* 方案一代碼 */ }
private suspend fun saveToAppPrivate(bitmap: Bitmap): Result { /* 方案二代碼 */ }
override fun onCleared() {
super.onCleared()
ioScope.cancel()
}
}
| 錯誤 | 原因 | 解決 |
|---|---|---|
| FileNotFoundException / Permission denied | API 29+ 直接 File 寫入公共目錄 | 遷移至 MediaStore / SAF / 專屬目錄 |
| bitmap.compress 返回 false | OutputStream 異常、磁盤滿、格式不支持 | try-catch、檢查磁盤空間、嘗試 PNG/WEBP |
| 保存的圖片無法在相冊顯示 | MediaStore 未掃描、IS_PENDING=1 未清除 | 更新 IS_PENDING=0、發送 MEDIA_SCANNER_SCAN_FILE 廣播 |
| SAF 寫入失敗 | 未獲取持久化權限、Uri 過期 | takePersistableUriPermission、重新啟動 SAF 選擇 |
| 大圖壓縮 OOM | Bitmap 過大、質量過高 | inSampleSize 縮放後再壓縮、分塊編碼 |
存儲權限演進的本質是用戶數據主權回歸。擁抱 MediaStore、SAF、專屬目錄,不僅是合規要求,更能構建穩定、安全、用戶信任的文件管理體驗。