المفاهيم الرئيسيّة

توضح الأقسام التالية بعض المفاهيم الأساسية لعملية السحب والإفلات.

عملية السحب والإفلات

هناك أربع خطوات أو حالات في عملية السحب والإفلات: واصلت، وانخفضت، وانتهت.

قيد التشغيل

استجابة لإيماءة السحب لدى المستخدم، يستدعي تطبيقك startDragAndDrop() لإخبار النظام ببدء عملية سحب وإفلات. تشير رسالة الأشكال البيانية توفر وسيطات الطريقة ما يلي:

• البيانات المطلوب سحبها.
• استدعاء لرسم ظل السحب
• بيانات التعريف التي تصف البيانات التي تم سحبها
• يستجيب النظام من خلال معاودة الاتصال بالتطبيق للحصول على سحب الظل. يعرض النظام بعد ذلك ظل السحب على الجهاز.
• بعد ذلك، يرسل النظام حدث سحب بنوع الإجراء ACTION_DRAG_STARTED إلى حدث السحب مستمع إلى جميع كائنات View في التنسيق الحالي. إلى مواصلة تلقّي أحداث السحب، بما في ذلك أي انخفاض محتمل حدث - يجب أن يعرض مستمع حدث السحب true. يؤدي هذا إلى تسجيل المستمع مع النظام. يمكن للمستمعين المسجّلين فقط مواصلة تلقي أحداث السحب. في هذه المرحلة، يمكن للمستمعين أيضًا تغيير مظهر عنصر View الذي تستهدفه ميزة الانخفاض لإظهار أنّ العرض يمكن قبول حدث طرح المنتج.
• إذا عرض أداة معالجة حدث السحب false، فلن يتم سحبها أحداث للعملية الحالية إلى أن يُرسِل النظام حدث سحب من خلال نوع الإجراء ACTION_DRAG_ENDED. من خلال عرض false، يخبر المستمع النظام بأنه غير مهتم في عملية السحب والإفلات ولا يريد قبول البيانات التي يتم سحبها.

جارٍ المتابعة

يواصل المستخدم إجراء السحب. وعندما يتقاطع ظل السحب مع حدود هدف الإفلات، يرسل النظام حدثًا أو أكثر من أحداث السحب إلى أداة معالجة حدث السحب للهدف. قد يغير المستمع مظهر قيمة الانخفاض في السعر المستهدف View استجابةً للحدث. على سبيل المثال، إذا كان الحدث يشير إلى أن ظل السحب يدخل إلى المربع المحيط للقطرة الهدف - نوع الإجراء ACTION_DRAG_ENTERED —يمكن للمستمِع التفاعل من خلال تمييز View.

تم الإسقاط

يحرر المستخدم ظل السحب داخل مربع حدود نقطة الإفلات الهدف. يرسل النظام لمستمعي الإفلات حدث سحب مزودًا بإجراء اكتب ACTION_DROP. يحتوي كائن حدث السحب على البيانات التي تمر إلى النظام في طلب startDragAndDrop() الذي يبدأ العملية. المستمع من المتوقع عرض القيمة المنطقية true إلى النظام إذا نجح المستمع يعالج البيانات المُسقطة. : تحدث هذه الخطوة فقط إذا قام المستخدم بإسقاط ظل السحب داخل مربّع حدود لـ "View" الذي تم تسجيل المستمِع لديه لتلقّي أحداث السحب (انخفاض في الهدف). إذا قام المستخدم بتحرير ظل السحب في أي جهاز آخر لن يتم إرسال أي حدث سحب بنسبة ACTION_DROP.

انتهى

بعد أن يحرر المستخدم ظل السحب، وبعد أن يرسل النظام

حدث سحب بنوع الإجراء ACTION_DROP، إذا لزم الأمر، فسيقوم النظام إرسال حدث سحب بنوع الإجراء ACTION_DRAG_ENDED للإشارة إلى أن انتهت عملية السحب والإفلات. يتم ذلك بغض النظر عن مكان المستخدم وتحرير ظل السحب. ويتم إرسال الحدث إلى كل مستمع تسجيل لتلقي أحداث السحب، حتى إذا استلم المستمع أيضًا حدث واحد (ACTION_DROP).

يتم وصف كل خطوة من هذه الخطوات بمزيد من التفصيل في القسم المسمى عملية سحب وإفلات:

سحب الأحداث

ويرسل النظام حدث سحب على شكل كائن DragEvent، يحتوي على نوع إجراء يصف ما يحدث في عملية السحب والإفلات الدفع. استنادًا إلى نوع الإجراء، يمكن أن يحتوي العنصر أيضًا على بيانات أخرى.

تتلقى أدوات معالجة الأحداث في السحب كائن DragEvent. للحصول على نوع الإجراء، ينادي المستمعين DragEvent.getAction() هناك ست قيم محتملة محددة بالثوابت في الفئة DragEvent، والموضحة في الجدول 1:

الجدول 1. أنواع إجراءات DragEvent

نوع الإجراء	المعنى
ACTION_DRAG_STARTED	يطلب التطبيق startDragAndDrop() ويحصل على ظل سحب. إذا أراد المستمع مواصلة تلقي أحداث السحب في هذه العملية، يجب عرض القيمة المنطقية true إلى .
ACTION_DRAG_ENTERED	يدخل ظل السحب في المربع المحيط بأداة معالجة أحداث السحب View هذا هو نوع إجراء الحدث الأول الذي يبثه المستمع عندما يدخل ظل السحب إلى المربع المحيط.
ACTION_DRAG_LOCATION	بعد حدث ACTION_DRAG_ENTERED، لا يزال ظل السحب داخل المربع المحيط بأداة معالجة أحداث السحب View
ACTION_DRAG_EXITED	تتم متابعة ACTION_DRAG_ENTERED ومنشور واحد على الأقل. حدث ACTION_DRAG_LOCATION، يتحرك ظل السحب خارج مربع الإحاطة بأداة معالجة أحداث السحب View
ACTION_DROP	يتم إطلاق ظل السحب فوق واجهة برمجة التطبيقات View يتم إرسال نوع الإجراء هذا إلى View مستمع الكائن فقط إذا عرض المستمع قيمة منطقية true ردًا على ACTION_DRAG_STARTED حدث سحب. نوع الإجراء هذا ليس يتم إرساله إذا طرح المستخدم ظل السحب على View الذي لم يتم تسجيل المستمع إليه أو إذا أصدر المستخدم سحب الظل على أي شيء ليس جزءًا من التخطيط الحالي. يعرض المستمع القيمة true المنطقية إذا كان يعالج الانخفاض بنجاح. بخلاف ذلك، يجب أن يعرض false
ACTION_DRAG_ENDED	ينهي النظام عملية السحب والإفلات. هذا النوع من الإجراءات ليس بالضرورة أن يسبقه حدث ACTION_DROP. في حال حذف يرسل النظام ACTION_DROP، مع استلام نوع الإجراء ACTION_DRAG_ENDED لا يشير ضمنًا إلى أن الهبوط بنجاح. يجب على المستمع الاتصال getResult(), كما هو موضح في الجدول 2، للحصول على القيمة تم إرجاعه استجابةً لـ ACTION_DROP. إذا كانت لم يتم إرسال حدث واحد (ACTION_DROP)، ثمّ تُرجع getResult() مبلغ false.

يحتوي عنصر DragEvent أيضًا على البيانات والبيانات الوصفية التي يستخدمها تطبيقك. إلى النظام في المكالمة إلى startDragAndDrop(). بعض البيانات صالحة فقط لأنواع إجراءات معينة كما هو موضح في الجدول 2. لمزيد من المعلومات، الأحداث والبيانات المرتبطة بها، راجِع القسم المسمى أ عملية السحب والإفلات.

الجدول 2. بيانات DragEvent الصالحة حسب نوع الإجراء

قيمة getAction()	قيمة getClipDescription()	قيمة getLocalState()	قيمة getX()	قيمة getY()	قيمة getClipData()	قيمة getResult()
ACTION_DRAG_STARTED	✓	✓
ACTION_DRAG_ENTERED	✓	✓
ACTION_DRAG_LOCATION	✓	✓	✓	✓
ACTION_DRAG_EXITED	✓	✓
ACTION_DROP	✓	✓	✓	✓	✓
ACTION_DRAG_ENDED		✓				✓

طرق DragEvent getAction()، describeContents()، writeToParcel()، وtoString() دائمًا إرجاع بيانات صالحة.

إذا كانت الطريقة لا تحتوي على بيانات صالحة لنوع إجراء معين، فستُرجع null أو 0، حسب نوع النتيجة.

سحب الظل

أثناء عملية السحب والإفلات، يعرض النظام صورة يمكن للمستخدم يسحب. لحركة البيانات، تمثل هذه الصورة البيانات التي يتم سحبها. بالنسبة العمليات الأخرى، تمثل الصورة بعض جوانب عملية السحب.

يُطلق على الصورة اسم ظل السحب. يتم إنشاؤه بالطرق التي تعلن عنها CANNOT TRANSLATE View.DragShadowBuilder الخاص بك. يمكنك تمرير أداة الإنشاء إلى النظام عند بدء عملية السحب والإفلات عملية باستخدام startDragAndDrop(). وكجزء من استجابته على startDragAndDrop()، يستدعي النظام طرق معاودة الاتصال التي تحددها في View.DragShadowBuilder للحصول على ظل سحب.

تشتمل الفئة View.DragShadowBuilder على اثنين من الدوال الإنشائية:

View.DragShadowBuilder(View)

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

إذا كنت تستخدم دالة الإنشاء هذه، فلن تضطر إلى تمديد View.DragShadowBuilder أو إلغاء طرقه. بشكل افتراضي، تحصل على سحب ظل له نفس مظهر View الذي تمريرته كوسيطة، تحت الموقع الذي يلمس فيه المستخدم الشاشة.

View.DragShadowBuilder()

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

تستخدم الفئة View.DragShadowBuilder طريقتين تنشئان معًا السحب الظل:

onProvideShadowMetrics()

يطلب النظام هذه الطريقة مباشرةً بعد طلب startDragAndDrop(). استخدم الطريقة لإرسال الأبعاد ونقطة اللمس لظل السحب إلى النظام. تحتوي الطريقة على معاملين:

outShadowSize: Point الخاص بك. يدخل عرض ظل السحب داخل x، ويدخل ارتفاعه في y

outShadowTouchPoint: كائن Point نقطة الاتصال هي الموقع داخل ظل السحب الذي يجب أن يكون تحت إصبع المستخدم أثناء السحب. موضع العنصر X في x وموضعه Y في y.

onDrawShadow()

يستدعي النظام onProvideShadowMetrics() بعد الاتصال مباشرةً بـ onDrawShadow() لإنشاء ظل السحب. تتضمن الطريقة الوسيطة، وهو كائن Canvas بُنى النظام من المعاملات التي تقدمها في onProvideShadowMetrics() ترسم الطريقة ظل السحب على العنصر المقدم Canvas

لتحسين الأداء، اجعل حجم ظل السحب صغيرًا. لشخص واحد عنصر واحد، قد ترغب في استخدام أيقونة. لتحديد عناصر متعددة، يمكنك ترغب في استخدام الأيقونات في مكدس بدلاً من الصور الكاملة المنتشرة على الشاشة.

سحب أدوات معالجة الأحداث وطرق معاودة الاتصال

تتلقّى View أحداث السحب باستخدام أداة معالجة أحداث السحب التي تنفّذها. View.OnDragListener أو باستخدام طريقة معاودة الاتصال onDragEvent() لطريقة العرض. فعندما يستدعي النظام الطريقة أو المستمع، فإنه يوفر الوسيطة DragEvent.

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

وكحل بديل، يمكنك تغيير طريقة التنفيذ التلقائية للسياسة onDragEvent(). دون تجاوز الطريقة. تحديد OnReceiveContentListener في إحدى المشاهدات لمزيد من التفاصيل، يُرجى مراجعة setOnReceiveContentListener() بعد ذلك، تنفّذ طريقة onDragEvent() ما يلي تلقائيًا:

• تعرض القيمة "true" استجابةً لاستدعاء startDragAndDrop().

• المكالمات performReceiveContent() في حالة إسقاط بيانات السحب والإفلات في العرض. يتم تمرير البيانات إلى كطريقة كائن ContentInfo. تشير رسالة الأشكال البيانية تستدعي الطريقة OnReceiveContentListener.

• لعرض true إذا تم إسقاط بيانات السحب والإفلات في طريقة العرض تستهلك ميزة "OnReceiveContentListener" أيًا من المحتوى.

حدِّد OnReceiveContentListener لمعالجة البيانات المخصَّصة التطبيق. للتوافق مع الأنظمة القديمة وصولاً إلى المستوى 24 لواجهة برمجة التطبيقات، استخدِم إصدار Jetpack من OnReceiveContentListener

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

الجمع بين طريقة onDragEvent() وView.OnDragListener هو مماثلة للمزيج onTouchEvent() وView.OnTouchListener المستخدم مع أحداث اللمس.