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

تبسّط فئة DropHelper وتنفيذ إمكانات السحب والإفلات. عضو في Jetpack مكتبة DragAndDrop، DropHelper توفّر التوافق مع الأنظمة القديمة وصولاً إلى المستوى 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);

حذف الاستدعاء الثاني خيارات تهيئة drop target، وفي هذه الحالة تم تعيين لون تمييز هدف الإفلات على اللون الثانوي (أو التمييز) للموضوع، يتم ضبط نصف قطر زاوية التمييز على 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) في البيانات التي تم استبعادها. تحقق من وجود قيمة فارغة وتحقق من صحة وأي بيانات تم حلها.