السحب والإفلات

تتيح Jetpack Compose السحب والإفلات باستخدام معدِّلَين:

  • ‫dragAndDropSource: تحدّد دالة مركّبة كنقطة بداية لإيماءة السحب
  • ‫dragAndDropTarget: تحدّد دالة مركّبة تقبل البيانات التي تم إسقاطها

على سبيل المثال، للسماح للمستخدمين بسحب صورة في تطبيقك، أنشئ دالة مركّبة للصورة وأضِف المعدِّل dragAndDropSource. لإعداد هدف إسقاط، أنشئ دالة مركّبة أخرى للصورة وأضِف المُعدِّل dragAndDropTarget.

يمكن تطبيق المُعدِّلات على مصادر سحب متعددة وأهداف إفلات متعددة.

تتيح المُعدِّلات للتطبيقات مشاركة البيانات بين دالتَين مركّبتَين أو أكثر باستخدام ClipData، وهو قابل للتشغيل التفاعلي مع عمليات تنفيذ View.

تحديد مصدر السحب

لتفعيل أحداث السحب داخل مكوّن، أضِف المُعدِّل dragAndDropSource. يأخذ هذا دالة كمعلمة. داخل هذه الدالة، استخدِم DragAndDropTransferData لتمثيل البيانات القابلة للنقل. يمكن أن تكون البيانات معرّف موارد منتظم (URI) عن بُعد أو بيانات نص منسَّق في الحافظة أو ملفًا على الجهاز أو غير ذلك، ولكن يجب تضمينها كلها في عنصر ClipData. قدِّم نصًا عاديًا، على سبيل المثال، على النحو التالي:

Modifier.dragAndDropSource { _ ->
    DragAndDropTransferData(
        ClipData.newPlainText(
            "image Url", url
        )
    )
}

للسماح بإجراء السحب عبر حدود التطبيق، يقبل المُنشئ DragAndDropTransferData الوسيطة flags. في المثال التالي، يحدّد الثابت DRAG_FLAG_GLOBAL أنّه يمكن سحب البيانات من تطبيق إلى آخر:

Modifier.dragAndDropSource { _ ->
    DragAndDropTransferData(
        ClipData.newPlainText(
            "image Url", url
        ),
        flags = View.DRAG_FLAG_GLOBAL
    )
}

يقبل DragAndDropTransferData العلامات المتوافقة مع نظام Android View. يمكنك الاطّلاع على قائمة ثوابت العرض للحصول على قائمة شاملة بالعلامات المتاحة.

تلقّي بيانات الإفلات

يمكنك تخصيص المُعدِّل dragAndDropTarget لدالة مركّبة لتفعيلها من أجل تلقّي أحداث السحب والإفلات. يحتوي المُعدِّل على مَعلمتَين: الأولى تعمل كفلتر وتحدّد نوع البيانات التي يمكن للمُعدِّل قبولها، والثانية تقدّم البيانات في دالة رد اتصال.

يُرجى العِلم أنّه يجب تذكُّر مثيل معاودة الاتصال. يوضّح المقتطف التالي كيفية تذكُّر معاودة الاتصال:

val callback = remember {
    object : DragAndDropTarget {
        override fun onDrop(event: DragAndDropEvent): Boolean {
            // Parse received data
            return true
        }
    }
}

لقبول البيانات من التطبيقات الأخرى، استخدِم requestDragAndDropPermission لتفعيل الاستلام، ثم أوقِفها بعد الانتهاء:

val externalAppCallback = remember {
    object : DragAndDropTarget {
        override fun onDrop(event: DragAndDropEvent): Boolean {
            val permission =
                activity.requestDragAndDropPermissions(event.toAndroidDragEvent())
            // Parse received data
            permission?.release()
            return true
        }
    }
}

من المهم تذكُّر أنّ DragAndDropEvent الذي يتم عرضه من دالة الاستدعاء Compose يختلف عن الذي تتوقعه طريقة requestDragAndDropPermission، لذا عليك استدعاء دالة الإضافة toAndroidDragEvent() في المَعلمة قبل تمريرها إلى طلب الحصول على الإذن.

يوضّح المقتطف التالي كيفية التعامل مع النص العادي الذي تم إفلاته:

Modifier.dragAndDropTarget(
    shouldStartDragAndDrop = { event ->
        event.mimeTypes().contains(ClipDescription.MIMETYPE_TEXT_PLAIN)
    }, target = callback // or externalAppCallback
)

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

التعامل مع أحداث السحب والإفلات

يمكنك إلغاء عمليات الاستدعاء في واجهة DragAndDropTarget لمراقبة وقت بدء حدث السحب والإفلات أو انتهائه أو دخوله أو خروجه من مكوّن معيّن للتحكّم بدقة في واجهة المستخدم وسلوك التطبيق:

object : DragAndDropTarget {
    override fun onStarted(event: DragAndDropEvent) {
        // When the drag event starts
    }

    override fun onEntered(event: DragAndDropEvent) {
        // When the dragged object enters the target surface
    }

    override fun onEnded(event: DragAndDropEvent) {
        // When the drag event stops
    }

    override fun onExited(event: DragAndDropEvent) {
        // When the dragged object exits the target surface
    }

    override fun onDrop(event: DragAndDropEvent): Boolean = true
}

مراجع إضافية

الدرس التطبيقي حول الترميز: السحب والإفلات في Compose