בורר התמונות

תיבת הדו-שיח של הכלי לבחירת תמונות תופיע עם קובצי המדיה במכשיר. בוחרים תמונה לשיתוף עם האפליקציה.
איור 1. הכלי לבחירת תמונות מספק ממשק משתמש אינטואיטיבי לשיתוף תמונות עם האפליקציה.

הכלי לבחירת תמונות מספק ממשק שניתן לעיין בו, שמציג את משתמש עם ספריית המדיה שלו, ממוינת לפי תאריך מהחדש לישן ביותר. כפי שמוצג ב- בקוד Lab לשיטות מומלצות בנושא פרטיות, הכלי לבחירת תמונות מספק למשתמשים דרך מובנית בטוחה להעניק לאפליקציה גישה רק תמונות וסרטונים נבחרים, במקום את כל ספריית המדיה שלהם.

משתמשים שבמכשיר שלהם יש ספקי מדיה בענן שעומדים בדרישות יכולים גם: לבחור מתוך תמונות וסרטונים שמאוחסנים מרחוק. מידע נוסף על מדיה בענן ספקים.

הכלי מתעדכן באופן אוטומטי, ומציע פונקציונליות מורחבת משתמשים לאורך זמן בלי שיהיה צורך לבצע שינויים בקוד.

שימוש בחוזים של 'פעילות ב-Jetpack'

כדי לפשט את השילוב של בורר התמונות, צריך לכלול את גרסה 1.7.0 ואילך של androidx.activity.

השתמשו בחוזים של תוצאות הפעילות הבאים כדי להפעיל את בורר התמונות:

אם הכלי לבחירת תמונות לא זמין במכשיר, הספרייה מפעיל באופן אוטומטי ACTION_OPEN_DOCUMENT פעולת Intent במקום זאת. Intent זה נתמך במכשירים שבהם פועלת גרסת Android 4.4. (רמת API 19) ומעלה. אתם יכולים לבדוק אם הכלי לבחירת תמונות זמין במכשיר נתון באמצעות התקשרות isPhotoPickerAvailable()

בחירת פריט מדיה יחיד

כדי לבחור פריט מדיה אחד, צריך להשתמש בתוצאת הפעילות PickVisualMedia חוזה, כפי שמוצג בקטע הקוד הבא:

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

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

בחירה של כמה קובצי מדיה

כדי לבחור כמה פריטי מדיה, מגדירים מספר מקסימלי של קובצי מדיה לבחירה, כפי שמוצג בקטע הקוד הבא.

Kotlin

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

Java

// 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 4.4 (רמת API 19) עד Android 10 (רמת API 29) ולמכשירי Android Go עם Android 11 או 12 שתומכים ב- פלטפורמת Google Play Services יכולה להתקין גרסה קודמת של הכלי לבחירת תמונות. שפת תרגום להפעיל את ההתקנה האוטומטית של המודול לבחירת תמונות מהעבר באמצעות Google Play Services, מוסיפים את הרשומה הבאה לתג <application> ב- קובץ המניפסט של האפליקציה:

<!-- 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() method:

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