أخبار المنتجات

أداة اختيار الصور المضمّنة

مدّة القراءة: 8 دقائق

"أداة اختيار الصور" المضمّنة: طريقة أكثر سلاسة لطلب الصور والفيديوهات بشكل خاص في تطبيقك

photopicker.png

استعِدّ لتحسين تجربة المستخدم في تطبيقك من خلال طريقة جديدة ومثيرة لاستخدام أداة اختيار الصور على Android. توفّر "أداة اختيار الصور" المضمّنة الجديدة طريقة سلسة تركّز على الخصوصية تتيح للمستخدمين اختيار الصور والفيديوهات مباشرةً من واجهة تطبيقك. يمكن لتطبيقك الآن الاستفادة من جميع المزايا نفسها المتاحة في "أداة اختيار الصور"، بما في ذلك الوصول إلى المحتوى على السحابة الإلكترونية، والمدمجة مباشرةً في تجربة تطبيقك.

لماذا نستخدم المحتوى المضمَّن؟

ندرك أنّ العديد من التطبيقات تهدف إلى توفير تجربة متكاملة وسلسة للمستخدمين عند اختيار الصور أو الفيديوهات. تم تصميم "أداة اختيار الصور" المضمّنة لتنفيذ ذلك تحديدًا، ما يتيح للمستخدمين الوصول بسرعة إلى صورهم الأخيرة بدون مغادرة تطبيقك، واستكشاف مكتبتهم الكاملة في مقدّم خدمة الوسائط على السحابة الإلكترونية المفضّل لديهم (مثل "صور Google")، بما في ذلك الصور المفضّلة والألبومات ووظائف البحث. وهذا يغني المستخدمين عن الحاجة إلى التبديل بين التطبيقات أو القلق بشأن ما إذا كانت الصورة التي يريدونها مخزّنة على الجهاز أو في السحابة الإلكترونية.

دمج سلس وخصوصية محسّنة

باستخدام "أداة اختيار الصور" المضمّنة، لا يحتاج تطبيقك إلى الوصول إلى صور المستخدم أو فيديوهاته إلا بعد أن يختار المستخدم شيئًا منها. ويعني ذلك توفير خصوصية أكبر للمستخدمين وتجربة أكثر سلاسة. بالإضافة إلى ذلك، تتيح "أداة اختيار الصور" المضمّنة للمستخدمين الوصول إلى مكتبة الوسائط المستندة إلى السحابة الإلكترونية بالكامل، في حين يقتصر إذن الوصول العادي إلى الصور على الملفات المحلية فقط.

"أداة اختيار الصور" المضمّنة في تطبيق "رسائل Google"

يعرض تطبيق "رسائل Google" إمكانات "أداة اختيار الصور" المضمّنة. إليك كيفية دمجها:

  • موضع بديهي: تقع "أداة اختيار الصور" أسفل زر الكاميرا مباشرةً، ما يمنح المستخدمين خيارًا واضحًا بين التقاط صورة جديدة أو اختيار صورة حالية.
  • المعاينة الديناميكية: بعد أن ينقر المستخدم على صورة، تظهر له معاينة كبيرة على الفور، ما يسهّل عليه تأكيد اختياره. وإذا ألغى اختيار الصورة، ستختفي المعاينة، ما يحافظ على تجربة سلسة ومنظَّمة.
  • توسيع العرض للاطّلاع على المزيد من المحتوى: يتم تبسيط العرض الأولي، ما يتيح الوصول بسهولة إلى الصور الحديثة. ومع ذلك، يمكن للمستخدمين توسيع "أداة اختيار الصور" بسهولة لتصفُّح جميع الصور والفيديوهات في مكتبتهم واختيار ما يريدون، بما في ذلك المحتوى السحابي من "صور Google".
  • احترام خيارات المستخدمين: لا تمنح "أداة اختيار الصور" المضمّنة إذن الوصول إلا إلى الصور أو الفيديوهات المحدّدة التي يختارها المستخدم، ما يعني أنّه يمكنه إيقاف طلب أذونات الوصول إلى الصور والفيديوهات تمامًا. يؤدي ذلك أيضًا إلى تجنُّب حاجة تطبيق "رسائل Google" إلى التعامل مع الحالات التي يمنح فيها المستخدمون إذن وصول محدودًا إلى الصور والفيديوهات.
gif1.gif
gif2.gif

التنفيذ

يمكن دمج أداة اختيار الصور المضمّنة بسهولة باستخدام مكتبة Jetpack لأداة اختيار الصور.  

Jetpack Compose

أولاً، عليك تضمين مكتبة "أداة اختيار الصور" في Jetpack كأحد التبعيات.

implementation("androidx.photopicker:photopicker-compose:1.0.0-alpha01")

توفّر الدالة المركّبة EmbeddedPhotoPicker آلية لتضمين واجهة مستخدم "أداة اختيار الصور" المضمّنة مباشرةً في شاشة Compose. تنشئ هذه الدالة المركّبة SurfaceView الذي يستضيف واجهة مستخدم أداة اختيار الصور المضمّنة. وتدير هذه الواجهة الاتصال بخدمة EmbeddedPhotoPicker، وتتعامل مع تفاعلات المستخدمين، وتُرسل معرّفات الموارد المنتظمة (URI) للوسائط المحدّدة إلى التطبيق الذي يطلبها.  

@Composable
fun EmbeddedPhotoPickerDemo() {
    // We keep track of the list of selected attachments
    var attachments by remember { mutableStateOf(emptyList<Uri>()) }

    val coroutineScope = rememberCoroutineScope()
    // We hide the bottom sheet by default but we show it when the user clicks on the button
    val scaffoldState = rememberBottomSheetScaffoldState(
        bottomSheetState = rememberStandardBottomSheetState(
            initialValue = SheetValue.Hidden,
            skipHiddenState = false
        )
    )

    // Customize the embedded photo picker
    val photoPickerInfo = EmbeddedPhotoPickerFeatureInfo
        .Builder()
        // Set limit the selection to 5 items
        .setMaxSelectionLimit(5)
        // Order the items selection (each item will have an index visible in the photo picker)
        .setOrderedSelection(true)
        // Set the accent color (red in this case, otherwise it follows the device's accent color)
        .setAccentColor(0xFF0000)
        .build()

    // The embedded photo picker state will be stored in this variable
    val photoPickerState = rememberEmbeddedPhotoPickerState(
        onSelectionComplete = {
            coroutineScope.launch {
                // Hide the bottom sheet once the user has clicked on the done button inside the picker
                scaffoldState.bottomSheetState.hide()
            }
        },
        onUriPermissionGranted = {
            // We update our list of attachments with the new Uris granted
            attachments += it
        },
        onUriPermissionRevoked = {
            // We update our list of attachments with the Uris revoked
            attachments -= it
        }
    )

       SideEffect {
        val isExpanded = scaffoldState.bottomSheetState.targetValue == SheetValue.Expanded

        // We show/hide the embedded photo picker to match the bottom sheet state
        photoPickerState.setCurrentExpanded(isExpanded)
    }

    BottomSheetScaffold(
        topBar = {
            TopAppBar(title = { Text("Embedded Photo Picker demo") })
        },
        scaffoldState = scaffoldState,
        sheetPeekHeight = if (scaffoldState.bottomSheetState.isVisible) 400.dp else 0.dp,
        sheetContent = {
            Column(Modifier.fillMaxWidth()) {
                // We render the embedded photo picker inside the bottom sheet
                EmbeddedPhotoPicker(
                    state = photoPickerState,
                    embeddedPhotoPickerFeatureInfo = photoPickerInfo
                )
            }
        }
    ) { innerPadding ->
        Column(Modifier.padding(innerPadding).fillMaxSize().padding(horizontal = 16.dp)) {
            Button(onClick = {
                coroutineScope.launch {
                    // We expand the bottom sheet, which will trigger the embedded picker to be shown
                    scaffoldState.bottomSheetState.partialExpand()
                }
            }) {
                Text("Open photo picker")
            }
            LazyVerticalGrid(columns = GridCells.Adaptive(minSize = 64.dp)) {
                // We render the image using the Coil library
                itemsIndexed(attachments) { index, uri ->
                    AsyncImage(
                        model = uri,
                        contentDescription = "Image ${index + 1}",
                        contentScale = ContentScale.Crop,
                        modifier = Modifier.clickable {
                            coroutineScope.launch {
                                // When the user clicks on the media from the app's UI, we deselect it
                                // from the embedded photo picker by calling the method deselectUri
                                photoPickerState.deselectUri(uri)
                            }
                        }
                    )
                }
            }
        }
    }
}

المشاهدات

أولاً، عليك تضمين مكتبة "أداة اختيار الصور" في Jetpack كأحد التبعيات.

implementation("androidx.photopicker:photopicker:1.0.0-alpha01")

لإضافة "أداة اختيار الصور" المضمّنة، عليك إضافة إدخال إلى ملف التنسيق.  

<view class="androidx.photopicker.EmbeddedPhotoPickerView"
    android:id="@+id/photopicker"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

And initialize it in your activity/fragment.

// We keep track of the list of selected attachments
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) {
        openSession = newSession
    }

    override fun onSessionError (throwable: Throwable) {}

    override fun onUriPermissionGranted(uris: List<Uri>) {
        _attachments += uris
    }

    override fun onUriPermissionRevoked (uris: List<Uri>) {
        _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)
    
    //
    // Add the embedded photo picker to a bottom sheet to allow the dragging to display the full photo library
    //

    picker = findViewById(R.id.photopicker)
    picker.addEmbeddedPhotoPickerStateChangeListener(pickerListener)
    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)

من المهم ملاحظة أنّ تجربة "أداة اختيار الصور" المضمّنة متاحة للمستخدمين الذين يعملون بالإصدار Android 14 (مستوى واجهة برمجة التطبيقات 34) أو الإصدارات الأحدث مع الإصدار 15 من إضافات حزمة تطوير البرامج (SDK) أو الإصدارات الأحدث. مزيد من المعلومات حول توفّر "أداة اختيار الصور" على الأجهزة

لتعزيز خصوصية المستخدم وأمانه، يعرض النظام أداة اختيار الصور المضمّنة بطريقة تمنع أي رسم أو تراكب. يعني هذا الخيار المتعمّد في التصميم أنّ تجربة المستخدم يجب أن تأخذ في الاعتبار مساحة عرض أداة اختيار الصور كعنصر مميّز ومخصّص، تمامًا كما تخطّط لإعلان بانر.

إذا كانت لديك أي ملاحظات أو اقتراحات، يُرجى إرسال طلبات إلى Issue Tracker.

متابعة القراءة