
相片挑選工具會提供可瀏覽且可供搜尋的介面,向使用者顯示媒體庫,並由新到舊為檔案排序。如隱私權最佳做法程式碼研究室所示,相片挑選工具提供內建的安全方法,以便使用者僅授予所選圖片和影片的存取權,而非整個媒體庫。
這項工具會自動更新,為應用程式使用者提供更完整的功能,不必變更任何程式碼。
裝置必須符合以下條件,才能使用相片挑選工具:
- 搭載 Android 11 (API 級別 30) 以上版本
- 透過 Google 系統更新接收模組化系統元件變更內容
使用 Jetpack Activity 合約
如要簡化相片挑選工具整合功能,請加入 androidx.activity
程式庫 1.6.1 或以上版本。
使用下列活動結果合約來發布相片挑選工具:
如果裝置上沒有相片挑選工具,資料庫會改為自動叫用 ACTION_OPEN_DOCUMENT
意圖動作。搭載 Android 4.4 (API 級別 19) 以上版本的裝置支援這個意圖。您可以呼叫 isPhotoPickerAvailable()
,確認特定裝置是否支援相片挑選工具。
選取單一媒體項目
如要選取單一媒體項目,請使用 PickVisualMedia
Activity Result 合約,如以下程式碼片段所示:
Kotlin
// Registers a photo picker activity launcher in single-select mode. val pickMedia = registerForActivityResult(PickVisualMedia()) { uri -> // Callback is invoked after the user selects a media item or closes the // photo picker. if (uri != null) { Log.d("PhotoPicker", "Selected URI: $uri") } else { Log.d("PhotoPicker", "No media selected") } } // Include only one of the following calls to launch(), depending on the types // of media that you want to allow the user to choose from. // Launch the photo picker and allow the user to choose images and videos. pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo)) // Launch the photo picker and allow the user to choose only images. pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageOnly)) // Launch the photo picker and allow the user to choose only videos. pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.VideoOnly)) // Launch the photo picker and allow the user to choose only images/videos of a // specific MIME type, such as GIFs. val mimeType = "image/gif" pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.SingleMimeType(mimeType)))
Java
// Registers a photo picker activity launcher in single-select mode. ActivityResultLauncher<PickVisualMediaRequest> pickMedia = registerForActivityResult(new PickVisualMedia(), uri -> { // Callback is invoked after the user selects a media item or closes the // photo picker. if (uri != null) { Log.d("PhotoPicker", "Selected URI: " + uri); } else { Log.d("PhotoPicker", "No media selected"); } }); // Include only one of the following calls to launch(), depending on the types // of media that you want to allow the user to choose from. // Launch the photo picker and allow the user to choose images and videos. pickMedia.launch(new PickVisualMediaRequest.Builder() .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE) .build()); // Launch the photo picker and allow the user to choose only images. pickMedia.launch(new PickVisualMediaRequest.Builder() .setMediaType(PickVisualMedia.ImageOnly.INSTANCE) .build()); // Launch the photo picker and allow the user to choose only videos. pickMedia.launch(new PickVisualMediaRequest.Builder() .setMediaType(PickVisualMedia.VideoOnly.INSTANCE) .build()); // Launch the photo picker and allow the user to choose only images/videos of a // specific MIME type, such as GIFs. String mimeType = "image/gif"; pickMedia.launch(new PickVisualMediaRequest.Builder() .setMediaType(new PickVisualMedia.SingleMimeType(mimeType)) .build());
選取多個媒體項目
如要選取多個媒體項目,請設定可選取的媒體檔案數量上限,如以下程式碼片段所示。
Kotlin
// Registers a photo picker activity launcher in multi-select mode. // In this example, the app allows the user to select up to 5 media files. val pickMultipleMedia = registerForActivityResult(PickMultipleVisualMedia(5)) { uris -> // Callback is invoked after the user selects media items or closes the // photo picker. if (uris.isNotEmpty()) { Log.d("PhotoPicker", "Number of items selected: ${uris.size}") } else { Log.d("PhotoPicker", "No media selected") } } // For this example, launch the photo picker and allow the user to choose images // and videos. If you want the user to select a specific type of media file, // use the overloaded versions of launch(), as shown in the section about how // to select a single media item. pickMultipleMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))
Java
// Registering Photo Picker activity launcher with multiple selects (5 max in this example) ActivityResultLauncher<PickVisualMediaRequest> pickMultipleMedia = registerForActivityResult(new PickMultipleVisualMedia(5), uris -> { // Callback is invoked after the user selects media items or closes the // photo picker. if (!uris.isEmpty()) { Log.d("PhotoPicker", "Number of items selected: " + uris.size()); } else { Log.d("PhotoPicker", "No media selected"); } }); // For this example, launch the photo picker and allow the user to choose images // and videos. If you want the user to select a specific type of media file, // use the overloaded versions of launch(), as shown in the section about how // to select a single media item. pickMultipleMedia.launch(new PickVisualMediaRequest.Builder() .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE) .build());
平台會限制使用者可在相片挑選工具中選取的檔案數目上限。如要使用這項限制,請呼叫 getPickImagesMaxLimit()
。在不支援相片挑選工具的裝置上,系統會忽略此項限制。
保留媒體檔案存取權
根據預設,系統會授予應用程式對媒體檔案的存取權,直到裝置重新啟動或應用程式停止為止。如果應用程式執行的是長時間執行的工作 (例如在背景上傳大型檔案),則可能需要延長此存取權的保留時間。如要延長,請呼叫 takePersistableUriPermission()
方法:
Kotlin
val flag = Intent.FLAG_GRANT_READ_URI_PERMISSION context.contentResolver.takePersistableUriPermission(uri, flag)
Java
int flag = Intent.FLAG_GRANT_READ_URI_PERMISSION; context.contentResolver.takePersistableUriPermission(uri, flag);
確認相片挑選工具是否可用
以下章節將說明如何使用架構程式庫,檢查特定裝置是否提供相片挑選工具。此工作流程可讓您自訂相片挑選工具的啟動行為,而非依賴支援資料庫。
如要使用相片挑選工具的架構佈建版本,請在應用程式中加入下列邏輯:
Kotlin
import android.os.ext.SdkExtensions.getExtensionVersion private fun isPhotoPickerAvailable(): Boolean { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { true } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { getExtensionVersion(Build.VERSION_CODES.R) >= 2 } else { false } } fun handlePhotoPickerLaunch() { if (isPhotoPickerAvailable()) { // To launch the system photo picker, invoke an intent that includes the // ACTION_PICK_IMAGES action. Consider adding support for the // EXTRA_PICK_IMAGES_MAX intent extra. } else { // Consider implementing fallback functionality so that users can still // select images and videos. } }
Java
import android.os.ext.SdkExtensions.getExtensionVersion; private boolean isPhotoPickerAvailable() { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { return true; } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) { return getExtensionVersion(Build.VERSION_CODES.R) >= 2; } else return false; } } public void launchPhotoPicker() { if (isPhotoPickerAvailable()) { // To launch the system photo picker, invoke an intent that includes the // ACTION_PICK_IMAGES action. Consider adding support for the // EXTRA_PICK_IMAGES_MAX intent extra. } else { // Consider implementing fallback functionality so that users can still // select images and videos. } }