授予相片和影片的部分存取權

Android 14 導入了所選相片存取權,可讓使用者授權應用程式存取相片庫中的特定圖片和影片,而不是授予特定類型所有媒體的存取權。

如果您尚未使用相片挑選工具,建議您在應用程式中實作,以提供一致的體驗選取圖片和影片,不必要求任何儲存空間權限,也能強化使用者隱私。

如果您使用儲存空間權限維護自己的圖片庫挑選器,且需要全面掌控實作項目,請調整實作方式,以使用新的 READ_MEDIA_VISUAL_USER_SELECTED 權限。如果您的應用程式未使用新權限,系統會在相容性模式中執行應用程式。

目標 SDK 版本 已宣告 READ_MEDIA_VISUAL_USER_SELECTED 已啟用所選相片存取權 使用者體驗行為
SDK 33
由應用程式控制
SDK 34 由系統控制 (相容行為)
由應用程式控制

建立自己的圖片庫挑選器需要進行大量的開發和維護作業,而您的應用程式需要要求儲存空間權限,才能取得明確的使用者同意聲明。使用者可以拒絕這些要求,或是當應用程式在搭載 Android 14 (API 級別 34) 以上版本的裝置上執行,則限制對所選媒體的存取權。下圖範例顯示了要求權限及使用新選項選取媒體的範例。

he .
圖 1.透過這個新的對話方塊,使用者除了可以選取授予完整存取權的一般選項,也能透過新的對話方塊選取要提供給應用程式的特定相片和影片。

本節說明使用 MediaStore 建立自己的圖片庫挑選器的建議方法。如果您已為應用程式保留圖片庫挑選器,且需要保有完整控制權,可以利用這些範例調整實作方式。如果您未更新實作方式來處理所選相片存取權,系統會在相容模式中執行應用程式。

要求權限

首先,請根據 OS 版本,在 Android 資訊清單中要求正確的儲存空間權限:

<!-- Devices running Android 12L (API level 32) or lower  -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />

<!-- Devices running Android 13 (API level 33) or higher -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

<!-- To handle the reselection within the app on Android 14 (API level 34) -->
<uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED" />

接著,再根據 OS 版本,要求正確的執行階段權限:

// Register ActivityResult handler
val requestPermissions = registerForActivityResult(RequestMultiplePermissions()) { results ->
    // Handle permission requests results
    // See the permission example in the Android platform samples: https://github.com/android/platform-samples
}

// Permission request logic
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
    requestPermissions.launch(arrayOf(READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_MEDIA_VISUAL_USER_SELECTED))
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    requestPermissions.launch(arrayOf(READ_MEDIA_IMAGES, READ_MEDIA_VIDEO))
} else {
    requestPermissions.launch(arrayOf(READ_EXTERNAL_STORAGE))
}

部分應用程式不需要權限

自 Android 10 (API 級別 29) 起,應用程式不再需要儲存空間權限,就能將檔案新增至共用儲存空間。也就是說,應用程式可以新增圖片至圖片庫、錄製影片並將影片儲存至共用儲存空間,或下載 PDF 月結單,而不需要要求儲存空間權限。如果應用程式只將檔案新增至共用儲存空間,且不查詢圖片或影片,您應停止要求儲存空間權限,並在 AndroidManifest.xml 中設定 API 28 的 maxSdkVersion

<!-- No permission is needed to add files to shared storage on Android 10 (API level 29) or higher  -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="28" />

處理媒體重新選取

透過 Android 14 中選定的相片存取權功能,應用程式應採用新的 READ_MEDIA_VISUAL_USER_SELECTED 權限來控制媒體重新選取,並更新應用程式介面,讓使用者將另一組圖片和影片的存取權授予應用程式。下圖顯示了要求權限並重新選取媒體的範例:

he .
圖 2.新的對話方塊也會讓使用者重新選取要提供給應用程式的相片和影片。

開啟選取對話方塊時,系統會根據要求的權限顯示相片、影片或兩者。舉例來說,如果您在沒有 READ_MEDIA_IMAGES 權限的情況下要求 READ_MEDIA_VIDEO 權限,則只有影片會顯示在使用者介面中,讓使用者選取檔案。

// Allow the user to select only videos
requestPermissions.launch(arrayOf(READ_MEDIA_VIDEO, READ_MEDIA_VISUAL_USER_SELECTED))

您可以檢查應用程式是否擁有裝置相片庫的完整、部分或遭拒存取權,並據此更新介面。如果應用程式需要儲存空間存取權,而非啟動時,請要求這些權限。請注意,權限授予可以在 onStartonResume 應用程式生命週期回呼之間變更,因為使用者可在設定中變更存取權,而不會關閉應用程式。

if (
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
    (
        ContextCompat.checkSelfPermission(context, READ_MEDIA_IMAGES) == PERMISSION_GRANTED ||
        ContextCompat.checkSelfPermission(context, READ_MEDIA_VIDEO) == PERMISSION_GRANTED
    )
) {
    // Full access on Android 13 (API level 33) or higher
} else if (
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
    ContextCompat.checkSelfPermission(context, READ_MEDIA_VISUAL_USER_SELECTED) == PERMISSION_GRANTED
) {
    // Partial access on Android 14 (API level 34) or higher
}  else if (ContextCompat.checkSelfPermission(context, READ_EXTERNAL_STORAGE) == PERMISSION_GRANTED) {
    // Full access up to Android 12 (API level 32)
} else {
    // Access denied
}

查詢裝置程式庫

確認您有權存取正確的儲存空間權限後,可以與 MediaStore 互動來查詢裝置程式庫 (無論獲得的存取權是部分還是完整存取權,方法都會相同):

data class Media(
    val uri: Uri,
    val name: String,
    val size: Long,
    val mimeType: String,
)

// Run the querying logic in a coroutine outside of the main thread to keep the app responsive.
// Keep in mind that this code snippet is querying only images of the shared storage.
suspend fun getImages(contentResolver: ContentResolver): List<Media> = withContext(Dispatchers.IO) {
    val projection = arrayOf(
        Images.Media._ID,
        Images.Media.DISPLAY_NAME,
        Images.Media.SIZE,
        Images.Media.MIME_TYPE,
    )

    val collectionUri = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        // Query all the device storage volumes instead of the primary only
        Images.Media.getContentUri(MediaStore.VOLUME_EXTERNAL)
    } else {
        Images.Media.EXTERNAL_CONTENT_URI
    }

    val images = mutableListOf<Media>()

    contentResolver.query(
        collectionUri,
        projection,
        null,
        null,
        "${Images.Media.DATE_ADDED} DESC"
    )?.use { cursor ->
        val idColumn = cursor.getColumnIndexOrThrow(Images.Media._ID)
        val displayNameColumn = cursor.getColumnIndexOrThrow(Images.Media.DISPLAY_NAME)
        val sizeColumn = cursor.getColumnIndexOrThrow(Images.Media.SIZE)
        val mimeTypeColumn = cursor.getColumnIndexOrThrow(Images.Media.MIME_TYPE)

        while (cursor.moveToNext()) {
            val uri = ContentUris.withAppendedId(collectionUri, cursor.getLong(idColumn))
            val name = cursor.getString(displayNameColumn)
            val size = cursor.getLong(sizeColumn)
            val mimeType = cursor.getString(mimeTypeColumn)

            val image = Media(uri, name, size, mimeType)
            images.add(image)
        }
    }

    return@withContext images
}

這個程式碼片段經過簡化,方便您與 MediaStore 互動。在可用於實際工作環境的應用程式中,請搭配使用分頁和分頁程式庫等項目,協助確保效能良好。

裝置升級後,系統會保留相片和影片存取權

如果應用程式所在裝置是從舊版 Android 升級至 Android 14,則系統會完整保留使用者的相片和影片存取權,並自動授予應用程式部分權限。實際行為取決於裝置在升級至 Android 14 之前所授予應用程式的權限組合。

Android 13 的權限

請考慮以下狀況:

  1. 您的應用程式已安裝在執行 Android 13 的裝置上。
  2. 使用者已授予應用程式 READ_MEDIA_IMAGES 權限和 READ_MEDIA_VIDEO 權限。
  3. 接著,您為安裝有該應用程式的裝置升級至 Android 14。

在此情況下,您的應用程式仍可完整存取使用者的相片和影片。 系統也會自動保留授予應用程式的 READ_MEDIA_IMAGESREAD_MEDIA_VIDEO 權限。

Android 12 以下版本的權限

請考慮以下狀況:

  1. 您的應用程式已安裝在執行 Android 13 的裝置上。
  2. 使用者已授予應用程式 READ_EXTERNAL_STORAGE 權限或 WRITE_EXTERNAL_STORAGE 權限。
  3. 接著,您為安裝有該應用程式的裝置升級至 Android 14。

在此情況下,您的應用程式仍可完整存取使用者的相片和影片。 系統也會自動為您的應用程式授予 READ_MEDIA_IMAGES 權限和 READ_MEDIA_VIDEO 權限。

最佳做法

本節包含使用 READ_MEDIA_VISUAL_USER_SELECTED 權限的若干最佳做法。詳情請參閱權限最佳做法

不要永久儲存權限狀態

請勿以永久方式儲存權限狀態,包括 SharedPreferencesDataStore。儲存的狀態可能不會與實際狀態同步。權限狀態可能在權限重設應用程式休眠、使用者對應用程式設定進行變更,或應用程式進入背景執行狀態後改變。請改為使用 ContextCompat.checkSelfPermission() 檢查儲存空間權限。

不要為相片和影片假定完整存取權限

根據 Android 14 所導入的變更,您的應用程式可能只具備裝置相片庫的部分存取權。如果應用程式在使用 ContentResolver 進行查詢時快取 MediaStore 資料,則快取可能不是最新版本。

  • 一律使用 ContentResolver 查詢 MediaStore,勿依賴儲存的快取。
  • 應用程式於前景運作時,將結果保留在記憶體中。
  • 在應用程式進入 onResume 應用程式生命週期時重新整理結果,因為使用者可能會透過權限設定從完整存取權切換為部分存取權。

將 URI 存取權視為臨時權限處理

如果使用者在系統權限對話方塊中選擇「選取相片和影片」,應用程式最終對所選相片和影片的存取權最終就會失效。您的應用程式應一律處理無法存取任何 Uri 的情況,不論其授權為何。

依權限篩選可選取的媒體類型

選取對話方塊對要求的權限類型敏感:

  • 僅要求 READ_MEDIA_IMAGES 僅會顯示可選取的圖片。
  • 如果只要求 READ_MEDIA_VIDEO,系統只會顯示可選取的影片。
  • 要求 READ_MEDIA_IMAGESREAD_MEDIA_VIDEO 會顯示可選取整個相片庫。

根據應用程式的用途,請務必要求正確的權限,避免造成使用者體驗不佳。如果功能只想選取影片,請確保您只要求 READ_MEDIA_VIDEO

在單次作業中要求權限

如要避免使用者看到多個系統執行階段對話方塊,請在單次操作中,提出 READ_MEDIA_VISUAL_USER_SELECTEDACCESS_MEDIA_LOCATION 以及「讀取媒體」權限 (READ_MEDIA_IMAGESREAD_MEDIA_VIDEO 或同時指定兩者) 請求。

允許使用者管理自己的選項

當使用者選擇部分存取模式時,應用程式不應假設裝置的相片庫沒有任何內容,且應允許使用者授予更多檔案。

使用者可能會決定透過權限設定從完整存取權切換至部分存取權,而不授予部分視覺媒體檔案的存取權。

相容性模式

如果您使用儲存空間權限保有自己的圖片庫挑選器,但尚未調整應用程式以使用新的 READ_MEDIA_VISUAL_USER_SELECTED 權限,則當使用者需要選取或重新選取媒體時,系統會以相容模式執行應用程式。

初始選取媒體時的行為

在初始選取期間,如果使用者選擇「選取相片和影片」(請見圖 1),系統會在應用程式工作階段期間授予 READ_MEDIA_IMAGESREAD_MEDIA_VIDEO 權限,藉此授予暫時權限,並暫時授予使用者所選相片和影片的臨時存取權。當應用程式移至背景,或使用者主動終止應用程式時,系統最終會拒絕這些權限。原理就和其他一次性權限一樣。

選取媒體重新選取期間的行為

如果您的應用程式稍後需要存取其他相片和影片,您必須再次以手動方式要求 READ_MEDIA_IMAGES 權限或 READ_MEDIA_VIDEO 權限。系統會按照與初始權限要求相同的流程,提示使用者選取相片和影片 (請參閱圖 2)。

如果您的應用程式遵循權限最佳做法,則這項變更不應中斷應用程式。如果應用程式未假設 URI 存取權已保留、儲存系統權限狀態,或是在權限變更後重新整理顯示的圖片組合,就特別重要。不過,視應用程式的用途而定,此行為可能不太理想。為提供使用者最佳體驗,建議您實作相片挑選工具調整應用程式的圖片庫挑選器,以便使用 READ_MEDIA_VISUAL_USER_SELECTED 權限直接處理此行為。