เครื่องมือเลือกรูปภาพ

เครื่องมือเลือกรูปภาพมีอินเทอร์เฟซที่เรียกดูได้ซึ่งแสดงคลังสื่อของผู้ใช้โดยจัดเรียงตามวันที่จากใหม่สุดไปเก่าสุด ตามที่แสดงใน Codelab แนวทางปฏิบัติแนะนำด้านความเป็นส่วนตัว เครื่องมือเลือกรูปภาพเป็นวิธีที่ปลอดภัยในตัวสำหรับให้ผู้ใช้ให้สิทธิ์แอปของคุณในการเข้าถึง เฉพาะรูปภาพและวิดีโอที่เลือก แทนที่จะเป็นคลังสื่อทั้งหมด

ผู้ใช้ที่มีผู้ให้บริการสื่อระบบคลาวด์ที่มีสิทธิ์ในอุปกรณ์จะเลือกรูปภาพและวิดีโอที่จัดเก็บไว้จากระยะไกลได้เช่นกัน ดูข้อมูลเพิ่มเติมเกี่ยวกับสื่อในระบบคลาวด์ ผู้ให้บริการเครือข่าย

เครื่องมือจะอัปเดตโดยอัตโนมัติเพื่อมอบฟังก์ชันเพิ่มเติมให้กับแอปของคุณ ผู้ใช้ได้โดยที่ไม่ต้องเปลี่ยนแปลงโค้ดใดๆ เลย

ใช้สัญญากิจกรรม Jetpack

เพื่อให้การผสานรวมเครื่องมือเลือกรูปภาพทำได้ง่ายขึ้น ให้รวมแอปพลิเคชันเวอร์ชัน 1.7.0 ขึ้นไป คลัง androidx.activity

ใช้สัญญาผลกิจกรรมต่อไปนี้เพื่อเปิดใช้งานเครื่องมือเลือกรูปภาพ

• PickVisualMedia เพื่อเลือกรูปภาพหรือวิดีโอรายการเดียว
• PickMultipleVisualMedia เพื่อเลือกรูปภาพหรือวิดีโอหลายรายการ

หากเครื่องมือเลือกรูปภาพไม่พร้อมใช้งานบนอุปกรณ์ ไลบรารี จะเรียกฟังก์ชัน ACTION_OPEN_DOCUMENT ผ่าน Intent แทน อุปกรณ์ที่ใช้ Android 4.4 (API ระดับ 19) ขึ้นไปรองรับ Intent นี้ คุณสามารถตรวจสอบว่าเครื่องมือเลือกรูปภาพพร้อมใช้งานในอุปกรณ์หนึ่งๆ หรือไม่โดยเรียกใช้ isPhotoPickerAvailable()

เลือกรายการสื่อรายการเดียว

หากต้องการเลือกรายการสื่อรายการเดียว ให้ใช้ผลลัพธ์กิจกรรม PickVisualMedia สัญญา ตามที่ปรากฏในข้อมูลโค้ดต่อไปนี้

// 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 let the user choose from.

// Launch the photo picker and let the user choose images and videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

// Launch the photo picker and let the user choose only images.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageOnly))

// Launch the photo picker and let the user choose only videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.VideoOnly))

// Launch the photo picker and let the user choose only images/videos of a
// specific MIME type, such as GIFs.
val mimeType = "image/gif"
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.SingleMimeType(mimeType)))

// 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 let the user choose from.

// Launch the photo picker and let the user choose images and videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE)
        .build());

// Launch the photo picker and let the user choose only images.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageOnly.INSTANCE)
        .build());

// Launch the photo picker and let the user choose only videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.VideoOnly.INSTANCE)
        .build());

// Launch the photo picker and let the user 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());

เลือกสื่อหลายรายการ

หากต้องการเลือกสื่อหลายรายการ ให้กำหนดจำนวนไฟล์สื่อที่เลือกได้สูงสุด ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user 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 let the user 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))

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user select up to 5 media files.
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 let the user 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() ระบบจะไม่สนใจขีดจำกัดนี้ในอุปกรณ์ที่ไม่รองรับเครื่องมือเลือกรูปภาพ

อุปกรณ์ที่พร้อมจำหน่าย

เครื่องมือเลือกรูปภาพใช้งานได้บนอุปกรณ์ที่มีคุณสมบัติตรงตามเกณฑ์ต่อไปนี้

• ใช้ Android 11 (API ระดับ 30) ขึ้นไป
• รับการเปลี่ยนแปลง ส่วนประกอบของระบบโมดูล ผ่าน การอัปเดตระบบของ Google

อุปกรณ์รุ่นเก่าที่ใช้ Android 4.4 (API ระดับ 19) ถึง Android 10 (API ระดับ 29) และอุปกรณ์ Android Go ที่ใช้ Android 11 หรือ 12 ที่รองรับ บริการ Google Play สามารถติดตั้งเครื่องมือเลือกรูปภาพเวอร์ชันที่พอร์ตไปยังเวอร์ชันเก่าได้ ถึง เปิดใช้งานการติดตั้งอัตโนมัติของโมดูลตัวเลือกภาพถ่ายแบ็คพอร์ต บริการ Google Play ให้เพิ่มรายการต่อไปนี้ลงในแท็ก <application> ใน ไฟล์ Manifest ของแอป

<!-- Trigger Google Play services to install the backported photo picker module. -->
<service android:name="com.google.android.gms.metadata.ModuleDependencies"
         android:enabled="false"
         android:exported="false"
         tools:ignore="MissingClass">
    <intent-filter>
        <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
    </intent-filter>
    <meta-data android:name="photopicker_activity:0:required" android:value="" />
</service>

คงสิทธิ์เข้าถึงไฟล์สื่อ

โดยค่าเริ่มต้น ระบบจะให้สิทธิ์แอปเข้าถึงไฟล์สื่อจนกว่าอุปกรณ์จะ รีสตาร์ทหรือจนกว่าแอปจะหยุด หากแอปทำงานเป็นเวลานาน เช่น เมื่ออัปโหลดไฟล์ขนาดใหญ่ในพื้นหลัง คุณอาจต้องเข้าถึง คงอยู่เป็นระยะเวลานาน โดยโทร takePersistableUriPermission() วิธีการ:

val flag = Intent.FLAG_GRANT_READ_URI_PERMISSION
context.contentResolver.takePersistableUriPermission(uri, flag)

int flag = Intent.FLAG_GRANT_READ_URI_PERMISSION;
context.contentResolver.takePersistableUriPermission(uri, flag);