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

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

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

توفّر "أداة اختيار الصور" المضمّنة تكاملاً أكثر سلاسة مع واجهة المستخدم، ولكنّها تحافظ على ميزات الأمان والخصوصية نفسها التي توفّرها "أداة اختيار الصور" العادية لأنّها تظهر على SurfaceView خاص.

توفر الجهاز

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

أما الأجهزة التي لا تتوفّر فيها هذه الإمكانات، فيمكنها الاعتماد على أداة اختيار الصور الكلاسيكية أو الإصدار المتوافق مع الإصدارات السابقة باستخدام "خدمات Google Play".

الاعتماد على مكتبة 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 (يُنصح به) أو طرق العرض.

دمج 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 لإعلام "أداة الاختيار" المضمّنة بأنّ المستخدم قد ألغى اختيار عنصر من واجهة مستخدم التطبيق. من الضروري تعديل حالة واجهة مستخدم تطبيقك يدويًا، لأنّ استدعاء هذه الطرق لن يُعلم تطبيقك بأي معرّفات موارد منتظمة تم إبطالها حديثًا من خلال دالة الاستدعاء 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
}

تخصيص أداة اختيار الصور

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

لون التمييز

By default, the embedded photo picker is relying on the dynamic colors provided by the system that the user can set across apps in the device theming options. سيتم استخدام لون التمييز في عناصر أساسية مختلفة في أداة اختيار الصور. سيتم ضبط جميع الألوان الأخرى استنادًا إلى إرشادات Material Design في Android. لتخصيص لون التمييز في أداة الاختيار، حدِّد الخيار EmbeddedPhotoPickerFeatureInfo:

val info = EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

بدون ضبط لون التمييز	مع لون تمييز (الذروة)	مع لون تمييز (موسَّع)

يجب أن يكون لون التمييز معتمًا بالكامل. يتم تجاهل قيمة ألفا (الشفافية). يُسمح فقط بالألوان التي تتراوح قيمة إضاءتها (سطوعها) بين 0.05 و0.9.

الأبعاد

By default, the size of the embedded picker isn't limited but you can specify a modifier to limit it:

EmbeddedPhotoPicker(
    modifier = Modifier.height(500.dp),
    ...
)

بلا حدود (موسَّعة)	مع حدّ أقصى يبلغ 500 وحدة بكسل مستقلة الكثافة (موسَّع)

دمج المشاهدات

لإضافة "أداة اختيار الصور" المضمّنة باستخدام 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)