בורר התמונות

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

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

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

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

שימוש בחוזים של Jetpack Activity

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

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

• PickVisualMedia כדי לבחור תמונה אחת או סרטון אחד.
• PickMultipleVisualMedia כדי לבחור כמה תמונות או סרטונים.

אם הכלי לבחירת תמונות לא זמין במכשיר, הספרייה מפעילה באופן אוטומטי את פעולת הכוונה ACTION_OPEN_DOCUMENT במקום זאת. Intent זה נתמך במכשירים עם Android מגרסה 4.4 (API ברמה 19) ואילך. כדי לבדוק אם הכלי לבחירת תמונות זמין במכשיר מסוים, אפשר להפעיל את הפונקציה 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 single-select mode.
val pickMedia = rememberLauncherForActivityResult(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)))

הערה: כשמשתמשים ב-PickVisualMedia, חלון הבחירה של התמונות נפתח במצב חצי מסך.

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

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

צפיות

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

פיתוח נייטיב

// 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 =
        rememberLauncherForActivityResult(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))

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

הערה: אם בורר התמונות לא זמין וספריית התמיכה מפעילה את פעולת הכוונה ACTION_OPEN_DOCUMENT, המערכת מתעלמת ממספר הקבצים המקסימלי שאפשר לבחור.

זמינות למכשירים

הכלי לבחירת תמונות זמין במכשירים שעומדים בקריטריונים הבאים:

• מערכת ההפעלה Android בגרסה 11 (רמת API 30) ואילך
• לקבל שינויים ברכיבי המערכת המודולרית דרך עדכוני המערכת של Google

במכשירים ישנים יותר עם 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>

שמירה של הגישה לקובצי מדיה

כברירת מחדל, המערכת מעניקה לאפליקציה גישה לקובצי מדיה עד שהמכשיר מופעל מחדש או עד שהאפליקציה מפסיקה. אם האפליקציה מבצעת משימות ממושכות, כמו העלאת קובץ גדול ברקע, יכול להיות שתצטרכו לשמור את הגישה הזו לפרק זמן ארוך יותר. כדי לעשות זאת, צריך לבצע קריאה ל-method‏ 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);