כלי מוטמע לבחירת תמונות

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

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

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

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

כלי בחירת התמונות המוטמע נתמך במכשירים עם Android 14 (API ברמה 34) עם SDK Extensions מגרסה 15 ואילך.

במכשירים שלא עומדים בדרישות האלה אפשר להשתמש בכלי לבחירת תמונות בגרסה הקלאסית או בגרסה שכוללת תיקוני באגים באמצעות 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 פיתוח נייטיב

הפונקציה EmbeddedPhotoPicker composable מספקת מנגנון להכללת ממשק המשתמש של בוחר התמונות המוטמע ישירות במסך Jetpack Compose. רכיב ה-Composable הזה יוצר 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" />

לאחר מכן, מאתחלים את הכלי לבחירת תמונות בשיטה onCreate של הפעילות באופן הבא:

1. קבלת הפניה ל-EmbeddedPhotoPickerView מהפריסה
2. מוסיפים את התג EmbeddedPhotoPickerStateChangeListener כדי לטפל באירועי בחירה
3. הגדרת בורר התמונות באמצעות 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)