DropHelper للسحب والإفلات بشكل مبسّط

تعمل الفئة DropHelper على تبسيط تنفيذ إمكانيات السحب والإفلات. توفّر DropHelper، وهي عضو في مكتبة Jetpack DragAndDrop، توافقًا مع الأنظمة القديمة وصولاً إلى المستوى 24 من واجهة برمجة التطبيقات.

استخدِم DropHelper لتحديد أهداف الإفلات وتخصيص تمييز الهدف وتحديد كيفية معالجة البيانات التي تم إفلاتها.

ضبط مصدر السحب

للبدء، أنشئ DragStartHelper مع عرض مصدر السحب وOnDragStartListener.

في OnDragStartListener، يمكنك إلغاء الطريقة onDragStart(). إنشاء كائن ClipData وكائن ClipData.Item للبيانات التي يتم نقلها كجزء من ClipData، يجب توفير البيانات الوصفية المخزّنة في عنصر ClipDescription ضمن ClipData. بالنسبة إلى عملية السحب والإفلات التي لا تمثل حركة البيانات، قد تحتاج إلى استخدام null بدلاً من كائن فعلي.

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

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 للتعامل مع البيانات المسقطة

على سبيل المثال، لإنشاء هدف إفلات يقبل الصور، استخدِم إحدى الطريقتين التاليتين:

configureView(
    myActivity,
    targetView,
    arrayOf("image/*"),
    options,
    onReceiveContentListener)

// or

configureView(
    myActivity,
    targetView,
    arrayOf("image/*"),
    onReceiveContentListener)

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 وضبط خيارات الضبط، كما هو موضَّح في المثال التالي:

val options: DropHelper.Options = DropHelper.Options.Builder()
                                      .setHighlightColor(getColor(R.color.purple_300))
                                      .setHighlightCornerRadiusPx(resources.getDimensionPixelSize(R.dimen.drop_target_corner_radius))
                                      .build()

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 في هدف الإفلات لمعالجة البيانات النصية. يعتمد التحديد على الترتيب التالي للأولوية:

1. تمثّل هذه السمة EditText الذي تم إسقاط ClipData عليه.
2. EditText الذي يحتوي على مؤشر النص (علامة الإقحام).
3. تم توفير أول EditText للمكالمة إلى DropHelper.Options.Builder.addInnerEditTexts(EditText...).

لضبط EditText كمعالج تلقائي للبيانات النصية، عليك ضبط EditText كوسيطة أولى من الطلب إلى DropHelper.Options.Builder.addInnerEditTexts(EditText...). على سبيل المثال، إذا كان هدف الإفلات يعالج الصور ولكنه يحتوي على حقول نصية قابلة للتعديل T1 وT2 وT3، اجعل T2 الوجهة التلقائية على النحو التالي:

val options: DropHelper.Options = DropHelper.Options.Builder()
                                      .addInnerEditTexts(T2, T1, T3)
                                      .build()

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) في البيانات التي تم إفلاتها. تحقق من عدم وجود قيمة فارغة وتحقق من صحة أي بيانات تم حلها.