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

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

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

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

توفُّر جهاز

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

يمكن للأجهزة التي لا تتوافق مع هذه الإمكانات الاعتماد على أداة اختيار الصور الكلاسيكية أو الإصدار المتوافق مع الإصدارات السابقة باستخدام "خدمات 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(يُنصح بذلك) أو 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 تم إبطالها حديثًا من خلال معاودة الاتصال 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
}

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

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

لون التمييز

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

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

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

بدون ضبط لون التمييز	مع لون التمييز (الحد الأقصى)	مع لون التمييز (موسَّع)

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

الأبعاد

بشكلٍ تلقائي، لا يكون حجم أداة الاختيار المضمّنة محدودًا، ولكن يمكنك تحديد معدِّل للحدّ من حجمها:

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

بدون حد (موسّع)	مع حدّ 500 وحدة بكسل مستقلة عن الكثافة (تم توسيعه)

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

لإضافة أداة اختيار الصور المضمّنة باستخدام "طرق العرض"، أضِف إدخالاً إلى ملف التصميم:

<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)