تعمل الفئة DropHelper
على تبسيط
تنفيذ إمكانيات السحب والإفلات. توفّر DropHelper
، وهي عضو في مكتبة Jetpack
DragAndDrop
، توافقًا مع الأنظمة القديمة وصولاً إلى المستوى 24 من واجهة برمجة التطبيقات.
استخدِم DropHelper
لتحديد أهداف الإفلات وتخصيص تمييز الهدف
وتحديد كيفية معالجة البيانات التي تم إفلاتها.
ضبط مصدر السحب
للبدء، أنشئ DragStartHelper
مع عرض مصدر السحب وOnDragStartListener
.
في OnDragStartListener
،
يمكنك إلغاء الطريقة onDragStart()
. إنشاء كائن ClipData
وكائن ClipData.Item
للبيانات التي يتم نقلها كجزء من ClipData
،
يجب توفير البيانات الوصفية المخزّنة في عنصر ClipDescription
ضمن
ClipData
. بالنسبة إلى عملية السحب والإفلات التي لا تمثل حركة البيانات،
قد تحتاج إلى استخدام null
بدلاً من كائن فعلي.
Kotlin
DragStartHelper(draggableView) { view: View, _: DragStartHelper -> val item = ClipData.Item(view.tag as? CharSequence) val dragData = ClipData( view.tag as? CharSequence, arrayOf(ClipDescription.MIMETYPE_TEXT_PLAIN), item ) view.startDragAndDrop( dragData, View.DragShadowBuilder(view), null, 0 ) }.attach()
Java
new DragStartHelper(draggableView, new DragStartHelper.OnDragStartListener() { @Override public void onDragStart(View view, DragStartHelper helper) { CharSequence tag = (CharSequence) view.getTag(); ClipData.Item item = new ClipData.Item(tag); ClipData dragData = new ClipData( tag, new String[]{ClipDescription.MIMETYPE_TEXT_PLAIN}, item); view.startDragAndDrop( dragData, new View.DragShadowBuilder(view), null, 0); } });
تحديد أهداف الانخفاض
عندما يصدر المستخدم الظل الخلفي في أحد العروض، يجب تهيئة العرض بشكل صحيح لقبول البيانات والاستجابة بشكل صحيح.
DropHelper.configureView()
هي طريقة ثابتة ومحمَّلة بشكل زائد تسمح لك بتحديد الاستهدافات الواردة. وتشمل معلماتها ما يلي:
Activity
الحالي: يتم استخدامه لأذونات معرّف الموارد المنتظم (URI).- تمثّل هذه السمة
View
كهدف لانخفاض عدد الزيارات.- أنواع MIME التي يمكن أن يقبلها هدف الانخفاض من البيانات التي تم إسقاطها.
- تمثّل هذه السمة
- خيارات الإعداد لهدف الإفلات، على وجه التحديد، قائمة
بحقول
EditText
المضمّنة. OnReceiveContentListener
للتعامل مع البيانات المسقطة
على سبيل المثال، لإنشاء هدف إفلات يقبل الصور، استخدِم إحدى الطريقتين التاليتين:
Kotlin
configureView( myActivity, targetView, arrayOf("image/*"), options, onReceiveContentListener) // or configureView( myActivity, targetView, arrayOf("image/*"), onReceiveContentListener)
Java
DropHelper.configureView( myActivity, targetView, new String[] {"image/*"}, options, onReceiveContentlistener); // or DropHelper.configureView( myActivity, targetView, new String[] {"image/*"}, onReceiveContentlistener);
يحذف الاستدعاء الثاني خيارات ضبط "انخفاض الكثافة"، وفي هذه الحالة، يتم ضبط
لون تمييز الهدف على اللون الثانوي (أو لون التمييز) للمظهر،
وضبط نصف قطر زاوية التمييز على 16 وحدة بكسل مستقلة الكثافة،
وقائمة مكوّنات EditText
فارغة. راجِع القسم التالي للاطّلاع على التفاصيل.
ضبط أهداف الانخفاض
تتيح لك الفئة الداخلية DropHelper.Options
ضبط أهداف الإفلات. قدم مثيلاً من الفئة إلى
الطريقة DropHelper.configureView(Activity, View, String[], Options,
OnReceiveContentListener
). راجِع القسم السابق للحصول على مزيد من المعلومات.
تخصيص إبراز هدف الإفلات
يضبط DropHelper
استهدافات الإفلات لعرض اللحظات المميزة أثناء سحب المستخدمين للمحتوى فوق الأهداف. توفّر السمة DropHelper
النمط التلقائي، وتتيح لك السمة DropHelper.Options
ضبط لون التمييز وتحديد
نصف قطر الزاوية لمستطيل التمييز.
استخدِم الفئة
DropHelper.Options.Builder
لإنشاء مثيل DropHelper.Options
وضبط خيارات الضبط،
كما هو موضَّح في المثال التالي:
Kotlin
val options: DropHelper.Options = DropHelper.Options.Builder() .setHighlightColor(getColor(R.color.purple_300)) .setHighlightCornerRadiusPx(resources.getDimensionPixelSize(R.dimen.drop_target_corner_radius)) .build()
Java
DropHelper.Options options = new DropHelper.Options.Builder() .setHighlightColor(getColor(R.color.purple_300)) .setHighlightCornerRadiusPx(getResources().getDimensionPixelSize(R.dimen.drop_target_corner_radius)) .build();
التعامل مع مكونات EditText في أهداف الإفلات
تتحكّم DropHelper
أيضًا في التركيز ضمن هدف الانخفاض عندما يحتوي الهدف على حقول نصية قابلة للتعديل.
يمكن أن تتمثل الأهداف المنسدلة في مشاهدة واحدة أو تسلسل هرمي لطريقة العرض. إذا كان التدرّج الهرمي لعرض هدف الإفلات
يحتوي على مكوِّن واحد أو أكثر من
مكوّنات EditText
، قدِّم قائمة بالمكوّنات إلى
DropHelper.Options.Builder.addInnerEditTexts(EditText...)
لضمان حذف تحديد الهدف ومعالجة بيانات النص بشكلٍ صحيح.
تمنع DropHelper
مكوّنات EditText
ضمن التدرّج الهرمي لطريقة الإفلات المستهدفة
من سرقة التركيز من العرض الذي يتضمّن السحب أثناء تفاعلات السحب.
بالإضافة إلى ذلك، إذا كان رمز السحب والإفلات ClipData
يتضمّن بيانات نص ومعرّف الموارد المنتظم (URI)، سيختار DropHelper
أحد المكوّنات EditText
في هدف الإفلات لمعالجة البيانات النصية. يعتمد التحديد على الترتيب التالي للأولوية:
- تمثّل هذه السمة
EditText
الذي تم إسقاطClipData
عليه. EditText
الذي يحتوي على مؤشر النص (علامة الإقحام).- تم توفير أول
EditText
للمكالمة إلىDropHelper.Options.Builder.addInnerEditTexts(EditText...)
.
لضبط EditText
كمعالج تلقائي للبيانات النصية، عليك ضبط EditText
كوسيطة أولى من الطلب إلى DropHelper.Options.Builder.addInnerEditTexts(EditText...)
. على سبيل المثال، إذا كان هدف الإفلات يعالج الصور ولكنه يحتوي على حقول نصية قابلة للتعديل T1
وT2
وT3
، اجعل T2
الوجهة التلقائية على النحو التالي:
Kotlin
val options: DropHelper.Options = DropHelper.Options.Builder() .addInnerEditTexts(T2, T1, T3) .build()
Java
DropHelper.Options options = new DropHelper.Options.Builder() .addInnerEditTexts(T2, T1, T3) .build();
معالجة البيانات في أهداف الانخفاض
تقبل الطريقة DropHelper.configureView()
عنصر OnReceiveContentListener
الذي تنشئه للتعامل مع ClipData
للسحب والإفلات. يتم توفير بيانات السحب والإفلات
إلى المستمع في كائن ContentInfoCompat
.
البيانات النصية موجودة في الكائن. يتم تمثيل الوسائط، مثل الصور،
بمعرّفات الموارد المنتظمة (URI).
تعالج OnReceiveContentListener
أيضًا البيانات المقدَّمة إلى هدف الإفلات من خلال تفاعلات المستخدم بخلاف السحب والإفلات، مثل النسخ واللصق، عند استخدام DropHelper.configureView()
لضبط أنواع طرق العرض التالية:
- كل المشاهدات إذا كان المستخدم يعمل بالإصدار 12 من نظام التشغيل Android أو إصدار أحدث
AppCompatEditText
، إذا كان المستخدم يعمل بإصدار Android وصولاً إلى Android 7.0.
أنواع MIME والأذونات والتحقق من المحتوى
يعتمد التحقّق من نوع MIME بواسطة DropHelper
على دالة السحب والإفلات
ClipDescription
التي ينشئها التطبيق الذي يوفر بيانات السحب والإفلات. تحقَّق من صحة ClipDescription
للتأكّد من ضبط أنواع MIME بشكل صحيح.
يطلب DropHelper
جميع أذونات الوصول لمعرّفات الموارد المنتظمة (URI) للمحتوى المضمّنة في
ClipData
للسحب والإفلات. لمزيد من المعلومات، يُرجى الاطّلاع على
DragAndDropPermissions
. وتتيح لك الأذونات حل معرفات الموارد المنتظمة (URI) للمحتوى عند معالجة بيانات السحب والإفلات.
لا يتحقّق DropHelper
من صحة البيانات التي يعرضها موفّرو المحتوى عند حلّ معرّفات الموارد المنتظمة (URI) في البيانات التي تم إفلاتها. تحقق من عدم وجود قيمة فارغة
وتحقق من صحة أي بيانات تم حلها.