萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

Android Bitmap 保存到 SD 卡/應用專屬目錄的完整方案

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

方案一:MediaStore (現代標準,API 29+ 無需權限)

// 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 分享給其他應用

方案三:SAF (Storage Access Framework) 用戶自選目錄

// 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);
        }
    });
}

方案四:兼容舊版本 (API < 29) 公共目錄寫入

// 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);

Bitmap 壓縮參數深度解析

格式質量參數範圍透明度適用場景典型質量值
JPEG0-100 (int)❌ 無照片、複雜圖像、體積敏感85-95 (視覺無損/高質量)
PNG0-100 (被忽略,無損)✅ 支持截圖、UI圖標、透明背景、文字圖100 (無損)
WEBP0-100 (有損/無損)✅ 支持綜合最優、現代App首選80-90 (有損)、100 (無損)

壓縮質量選擇建議

  • 用戶頭像/照片:JPEG 90 / WEBP 85 (平衡體積與質量)
  • UI 截圖/分享圖:PNG 100 (無損、保留透明)
  • 緩存縮略圖:JPEG 70 / WEBP 75 (極致壓縮)
  • 原圖備份:PNG 100 / WEBP 無損

異步寫入最佳實踐:協程 + 生命週期感知

// 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 deniedAPI 29+ 直接 File 寫入公共目錄遷移至 MediaStore / SAF / 專屬目錄
bitmap.compress 返回 falseOutputStream 異常、磁盤滿、格式不支持try-catch、檢查磁盤空間、嘗試 PNG/WEBP
保存的圖片無法在相冊顯示MediaStore 未掃描、IS_PENDING=1 未清除更新 IS_PENDING=0、發送 MEDIA_SCANNER_SCAN_FILE 廣播
SAF 寫入失敗未獲取持久化權限、Uri 過期takePersistableUriPermission、重新啟動 SAF 選擇
大圖壓縮 OOMBitmap 過大、質量過高inSampleSize 縮放後再壓縮、分塊編碼

總結

  • 首選 MediaStore:用戶可見媒體文件,現代 Android 標準,無需權限,自動入相冊
  • 次選應用專屬目錄:私有數據、緩存、臨時文件,零權限、自動清理
  • 用戶自選目錄用 SAF:導出、備份、跨應用協作場景
  • 棄用公共目錄直寫:API 29+ 受限,API 33+ 僅媒體權限無法訪問
  • 異步 + 協程 + 生命週期:避免主線程阻塞、內存洩漏、Activity 銷毀後回調崩潰

存儲權限演進的本質是用戶數據主權回歸。擁抱 MediaStore、SAF、專屬目錄,不僅是合規要求,更能構建穩定、安全、用戶信任的文件管理體驗。

copyright © 萬盛學電腦網 all rights reserved