
הכלי המוטמע לבחירת תמונות הוא גרסה אחרת של הכלי לבחירת תמונות, שמאפשרת לבצע פעולות ישירות בממשקי המשתמש של האפליקציות. הוא מציע אפשרויות שילוב והתאמה אישית משופרות בהשוואה לכלי הקלאסי לבחירת תמונות. הוא מוצג ב-SurfaceView באמצעות השיטה setChildSurfacePackage, ולכן הוא שומר על אותן תכונות אבטחה ופרטיות של הגרסה הלא מוטמעת.
בעזרת הכלי המוטמע לבחירת תמונות, המשתמשים יכולים לבחור תמונות וסרטונים גם מהמכשיר וגם מספריית התמונות בענן, בלי לאבד את המיקוד באפליקציית הלקוח. אפליקציית הלקוח נשארת פעילה, הפעילות שלה במצב של המשך והיא יכולה להגיב לבחירות של המשתמשים בזמן אמת.
הכלי המוטמע לבחירת תמונות מציע שילוב חלק יותר של ממשק המשתמש, אבל שומר על אותן תכונות אבטחה ופרטיות כמו הכלי הרגיל לבחירת תמונות, כי הוא מוצג ב-SurfaceView מיוחד.
זמינות למכשירים
הכלי המוטמע לבחירת תמונות נתמך במכשירים עם Android מגרסה 14 (רמת API 34) עם SDK Extensions מגרסה 15 ואילך.
במכשירים שלא עומדים בדרישות האלה, אפשר להשתמש בכלי הקלאסי לבחירת תמונות או בגרסה שהוסבה לגרסאות מוקדמות יותר (backporting) באמצעות Google Play Services.
תלות בספריית Jetpack
מוסיפים את ספריית Jetpack של הכלי לבחירת תמונות כתלות:
// For apps using Jetpack Compose
implementation("androidx.photopicker:photopicker-compose:1.0.0-alpha01")
// For apps using Views
implementation("androidx.photopicker:photopicker:1.0.0-alpha01")
אתם יכולים לשלב את הכלי המוטמע לבחירת תמונות באמצעות Jetpack Compose (מומלץ) או Views.
שילוב של Jetpack Compose
הפונקציה הקומפוזבילית EmbeddedPhotoPicker מספקת מנגנון להכללת ממשק המשתמש של הכלי המוטמע לבחירת תמונות ישירות במסך Jetpack Compose. הפונקציה הזו שניתנת לשילוב יוצרת SurfaceView שמארח את ממשק המשתמש של הכלי המוטמע לבחירת תמונות. הוא מנהל את החיבור לשירות EmbeddedPhotoPicker, מטפל באינטראקציות של המשתמשים ומעביר את כתובות ה-URI של המדיה שנבחרה לאפליקציה שמפעילה את השירות, עם כמה פרמטרים שצריך להגדיר:
val coroutineScope = rememberCoroutineScope()
val pickerState = rememberEmbeddedPhotoPickerState()
EmbeddedPhotoPicker(
state = pickerState,
onUriPermissionGranted = { uris ->
_attachments.value += uris
},
onUriPermissionRevoked = { uris ->
_attachments.value -= uris
},
onSelectionComplete = {
// Hide the embedded photo picker as the user is done with the
// photo/video selection
},
)
בחירה רציפה

הכלי המוטמע לבחירת תמונות מאפשר למשתמשים לבחור פריטים מספריית התמונות ולבטל את הבחירה שלהם בלי לסגור את הכלי. הפריטים שנבחרו ושהבחירה שלהם בוטלה בממשק המשתמש של האפליקציה מסונכרנים עם הכלי לבחירת תמונות, וכך המשתמשים נהנים מחוויית שימוש חלקה.
מבטלים את הבחירה ב-Uri באמצעות השיטה deselectUri או deselectUris מ-pickerState כדי להודיע לכלי לבחירת קבצים שהמשתמש ביטל את הבחירה בפריט מממשק המשתמש של האפליקציה. צריך לעדכן את מצב ממשק המשתמש של האפליקציה באופן ידני, כי קריאה לשיטות האלה לא תשלח לאפליקציה התראה על מזהי URI חדשים שבוטלו באמצעות הקריאה החוזרת (callback) של onUriPermissionRevoked.
coroutineScope.launch {
// Signal unselected media to the picker
pickerState.deselectUris(uris)
// Remove them from the list of selected media to be reflected in the app's UI
_attachments.value -= uris
}
התאמה אישית של הכלי לבחירת תמונות
הכלי המוטמע לבחירת תמונות מציע אפשרויות להתאמה אישית, שמאפשרות לכם להתאים את המראה וההתנהגות שלו כדי לשלב אותו בצורה טובה יותר בעיצוב ובחוויית המשתמש של האפליקציה.
צבע משני
כברירת מחדל, הכלי המוטמע לבחירת תמונות מסתמך על הצבעים הדינמיים שהמערכת מספקת, שהמשתמש יכול להגדיר באפליקציות שונות באפשרויות העיצוב של המכשיר. הצבע המשני ישמש לרכיבים ראשיים שונים בכלי לבחירת תמונות. כל שאר הצבעים יוגדרו לפי ההנחיות של Android Material. כדי להתאים אישית את הצבע המשני של בורר התאריכים, מגדירים את האפשרות EmbeddedPhotoPickerFeatureInfo:
val info = EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()
EmbeddedPhotoPicker(
embeddedPhotoPickerFeatureInfo = info,
...
)
| בלי להגדיר צבע משני | עם צבע משני (שיא) | עם צבע משני (מורחב) |
|---|---|---|
|
|
|
הצבע המשני חייב להיות אטום לחלוטין. המערכת מתעלמת מערך האלפא (שקיפות). מותר להשתמש רק בצבעים עם ערך בהירות בין 0.05 ל-0.9.
מידות
כברירת מחדל, הגודל של בורר הקבצים המוטמע לא מוגבל, אבל אפשר לציין מגבלה:
EmbeddedPhotoPicker(
modifier = Modifier.height(500.dp),
...
)
| ללא הגבלה (מורחב) | עם מגבלה של 500dp (מורחב) |
|---|---|
|
|
שילוב של תצוגות
כדי להוסיף את כלי בחירת התמונות המוטמע באמצעות Views, מוסיפים רשומה לקובץ הפריסה:
<view class="androidx.photopicker.EmbeddedPhotoPickerView"
android:id="@+id/photopicker"
android:layout_width="match_parent"
android:layout_height="match_parent" />
אחר כך, מאתחלים את הכלי לבחירת תמונות ב-method onCreate של הפעילות:
- מקבלים הפניה ל-
EmbeddedPhotoPickerViewמהפריסה - מוסיפים את
EmbeddedPhotoPickerStateChangeListenerכדי לטפל באירועי בחירה - מגדירים את הכלי לבחירת תמונות באמצעות
EmbeddedPhotoPickerFeatureInfo, כולל הגדרות בהתאמה אישית כמו צבע משני
// Keep track of the selected media
private val _attachments = MutableStateFlow(emptyList<Uri>())
val attachments = _attachments.asStateFlow()
private lateinit var picker: EmbeddedPhotoPickerView
private var openSession: EmbeddedPhotoPickerSession? = null
val pickerListener = object : EmbeddedPhotoPickerStateChangeListener {
override fun onSessionOpened(newSession: EmbeddedPhotoPickerSession) {
// Keep reference to the session to notify the embedded picker of user
// interactions on the calling app
openSession = newSession
}
override fun onSessionError(throwable: Throwable) {}
override fun onUriPermissionGranted(uris: List<Uri>) {
// Add newly selected media to our tracked list
_attachments += uris
}
override fun onUriPermissionRevoked(uris: List<Uri>) {
// Remove newly unselected media from our tracked list
_attachments -= uris
}
override fun onSelectionComplete() {
// Hide the embedded photo picker as the user is done with the
// photo/video selection
}
}
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.main_view)
picker = findViewById(R.id.photopicker)
// Attach the embedded picker event listener to update the app's UI
picker.addEmbeddedPhotoPickerStateChangeListener(pickerListener)
// Customize embedded picker's features: accent color, max selectable items,
// pre-selected URIs, filter out mime types
picker.setEmbeddedPhotoPickerFeatureInfo(
// Set a custom accent color
EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()
)
}
אתם יכולים להפעיל את השיטות השונות של EmbeddedPhotoPickerSession כדי לבצע פעולות בכלי לבחירת קבצים:
// Notify the embedded picker of a configuration change
openSession.notifyConfigurationChanged(newConfig)
// Update the embedded picker to expand following a user interaction
openSession.notifyPhotoPickerExpanded(/* expanded: */ true)
// Resize the embedded picker
openSession.notifyResized(/* width: */ 512, /* height: */ 256)
// Show/hide the embedded picker (after a form has been submitted)
openSession.notifyVisibilityChanged(/* visible: */ false)
// Remove unselected media from the embedded picker after they have been
// unselected from the host app's UI
openSession.requestRevokeUriPermission(removedUris)