
הכלי לבחירת תמונות מספק ממשק שאפשר לעיין בו, שבו מוצגת ליד המשתמשים ספריית המדיה שלהם, ממוינת לפי תאריך מהחדש לישן. כפי שמתואר בcodelab בנושא שיטות מומלצות לשמירה על פרטיות, הכלי לבחירת תמונות מספק למשתמשים דרך בטוחה ומובנית להעניק לאפליקציה גישה רק לתמונות ולסרטונים שנבחרו, במקום לספריית המדיה כולה.
משתמשים שיש להם במכשיר ספקי מדיה מתאימים בענן יכולים גם לבחור מתוך התמונות והסרטונים שנשמרו מרחוק. מידע נוסף על ספקי מדיה בענן
הכלי מתעדכן באופן אוטומטי, ומציע פונקציונליות מורחבת למשתמשים באפליקציה לאורך זמן, בלי צורך בשינויים בקוד.
שימוש בחוזים של 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)))
בחירת כמה פריטי מדיה
כדי לבחור כמה פריטים של מדיה, מגדירים מספר מקסימלי של קובצי מדיה שאפשר לבחור, כמו בקטע הקוד הבא.
צפיות
// 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()
.
במכשירים שבהם אין תמיכה בבורר התמונות, המערכת מתעלמת מהמגבלה הזו.
זמינות למכשירים
הכלי לבחירת תמונות זמין במכשירים שעומדים בקריטריונים הבאים:
- 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);
טיפול בסרטוני HDR באמצעות המרת קידוד
ב-Android 13 (API 33) נוספה היכולת לצלם סרטונים בטווח דינמי גבוה (HDR). אמנם HDR מספק חוויה חזותית עשירה יותר, אבל יכול להיות שחלק מהאפליקציות הישנות לא יעבדו את הפורמטים החדשים האלה, וכתוצאה מכך יהיו בעיות כמו עיבוד צבעים לא טבעי במהלך ההפעלה (למשל, פנים עם גוון ירוק). כדי לטפל בפערים בתאימות, בורר התמונות מציע תכונת המרה שמאפשרת להמיר אוטומטית סרטוני HDR לפורמט טווח דינמי סטנדרטי (SDR) לפני שמספקים אותם לאפליקציה המבקשת.
המטרה העיקרית של ההמרה של הכלי לבחירת תמונות היא להבטיח חוויית מדיה עקבית ומדויקת מבחינה חזותית במגוון רחב יותר של אפליקציות, גם באפליקציות שעדיין אין בהן תמיכה מפורשת ב-HDR. כדי לשפר את תאימות האפליקציה ולספק חוויית משתמש חלקה, המערכת מבצעת המרה של סרטוני HDR ל-SDR.
איך פועלת ההמרה של הכלי לבחירת תמונות
המרת הקידוד של התמונות ב-HDR בכלי לבחירת תמונות לא מופעלת כברירת מחדל. כדי להפעיל את התכונה הזו, האפליקציה צריכה להצהיר באופן מפורש על היכולות שלה לטיפול בפורמטים של מדיה כשמפעילים את הכלי לבחירת תמונות.
האפליקציה מספקת את יכולות עיבוד המדיה שלה לכלי לבחירת תמונות. כדי לעשות זאת, מוסיפים את mediaCapabilities
ל-PickVisualMediaRequest.Builder
כשמפעילים את הכלי לבחירת תמונות באמצעות ספריית הפעילות של AndroidX. כדי להקל על כך, נוספו ל-PickVisualMediaRequest.Builder
ממשקי API חדשים, setMediaCapabilitiesForTranscoding(capabilities: MediaCapabilities?)
.
אפשר לשלוט בהתנהגות של המרת הקוד של HDR באמצעות הכיתה MediaCapabilities
.
מספקים אובייקט MediaCapabilities
שמציין בדיוק אילו סוגי HDR האפליקציה תומכת בהם (למשל, TYPE_HLG10
, TYPE_HDR10
, TYPE_HDR10_PLUS
,
TYPE_DOLBY_VISION
).
כדי להשבית את ההמרה לחלוטין, מעבירים את הערך null
עבור MediaCapabilities
. כל סוג HDR שלא מופיע במפורש ביכולות שציינתם יחשב כסוג לא נתמך. ה-API הזה נתמך ב-Android 13 (רמת API 33) ואילך ומסומן ב-@RequiresApi(Build.VERSION_CODES.TIRAMISU)
.
import androidx.activity.result.PickVisualMediaRequest
import androidx.activity.result.contract.ActivityResultContracts.PickVisualMedia
import androidx.annotation.RequiresApi
import android.os.Build
import android.util.Log
import android.provider.MediaStore
// Registers a photo picker activity launcher.
val pickMedia = registerForActivityResult(PickVisualMedia()) { uri ->
// Callback invoked after media selected or picker activity closed.
if (uri != null) {
Log.d("photo picker", "Selected URI: $uri")
} else {
Log.d("photo picker", "No media selected")
}
}
@RequiresApi(Build.VERSION_CODES.TIRAMISU)
fun launchPhotoPickerWithTranscodingSupport() {
val mediaCapabilities = MediaCapabilities.Builder()
.addSupportedHdrType(MediaCapabilities.HdrType.TYPE_HLG10)
.build()
// Launch the photo picker and let the user choose only videos with
// transcoding enabled.
pickMedia.launch(PickVisualMediaRequest.Builder()
.setMediaType(PickVisualMedia.VideoOnly)
.setMediaCapabilitiesForTranscoding(mediaCapabilities)
.build())
}
ההמרה של הכלי לבחירת תמונות מבוססת גם על יכולות המדיה של האפליקציה וגם על הסרטון שנבחר. אם מתבצע המרה, המערכת מחזירה URI לסרטון המומר.
שיקולים חשובים לגבי המרת HDR
- ביצועים ואחסון: תהליך ההמרה לקוד אחר דורש זמן עיבוד ויוצר קובץ חדש, שמשתמש בנפח אחסון.
- מגבלת אורך הסרטון: כדי לאזן בין חוויית המשתמש למגבלות האחסון, אורך הסרטון מוגבל לדקה אחת.
- ניהול קבצים שנשמרו במטמון: קבצים שעברו המרה ונשמרו במטמון נמחקים מדי פעם במהלך פעולות תחזוקה במצב חוסר פעילות, כדי למנוע שימוש מוגזם באחסון.
- זמינות במכשירים: הטרנסקוד של בורר התמונות נתמך ב-Android 13 (רמת API 33) ואילך.
- שילוב פעילות ב-AndroidX: חשוב לוודא שאתם משתמשים בגרסה 1.11.0-alpha01 או בגרסה מתקדמת יותר של ספריית הפעילות ב-AndroidX (alpha/beta/RC/stable), כי היא כוללת את ממשק ה-API הנדרש של
setMediaCapabilitiesForTranscoding
.