DropHelper برای کشیدن و رها کردن ساده

کلاس DropHelper اجرای قابلیت‌های کشیدن و رها کردن را ساده می‌کند. DropHelper که عضوی از کتابخانه Jetpack DragAndDrop است، سازگاری رو به عقب را تا سطح 24 API فراهم می کند.

از DropHelper برای مشخص کردن اهداف افت، سفارشی کردن برجسته کردن هدف افت، و تعریف نحوه مدیریت داده های حذف شده استفاده کنید.

منبع کشیدن را تنظیم کنید

توجه: برای یک نمونه پیاده سازی کامل به Drag and Drop Demo مراجعه کنید.

برای شروع، 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() یک روش ثابت و بارگذاری شده است که به شما امکان می دهد اهداف drop را مشخص کنید. پارامترهای آن شامل موارد زیر است:

• Activity فعلی — برای مجوزهای URI استفاده می شود.
  • View که به عنوان هدف حذف عمل می کند.
    • انواع MIME که هدف drop می تواند از داده های حذف شده بپذیرد.
• گزینه‌های پیکربندی برای هدف حذف - به‌ویژه، فهرستی از فیلدهای 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 را حذف می کند، در این صورت رنگ برجسته هدف drop بر روی رنگ ثانویه (یا تاکیدی) موضوع تنظیم می شود، شعاع گوشه برجسته روی 16 dp تنظیم می شود و لیست اجزای EditText خالی است. برای جزئیات بیشتر به بخش زیر مراجعه کنید.

اهداف رها را پیکربندی کنید

کلاس داخلی DropHelper.Options به شما امکان می دهد تا اهداف drop را پیکربندی کنید. نمونه ای از کلاس را به متد DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener ) ارائه دهید. برای اطلاعات بیشتر به بخش قبلی مراجعه کنید.

برجسته کردن هدف افت را سفارشی کنید

DropHelper اهداف drop را پیکربندی می کند تا زمانی که کاربران محتوا را روی اهداف می کشند، برجسته نشان دهد. 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 فوکوس را در هدف قطره کنترل می کند.

اهداف Drop می توانند یک نما یا یک سلسله مراتب نمایش باشند. اگر سلسله‌مراتب نمای هدف شامل یک یا چند جزء EditText است، فهرستی از مؤلفه‌ها را به DropHelper.Options.Builder.addInnerEditTexts(EditText...) ارائه دهید تا مطمئن شوید برجسته‌سازی هدف drop و مدیریت داده‌های متن به درستی کار می‌کنند.

DropHelper از ربودن فوکوس از نماهای حاوی در طول تعاملات کشیدن توسط اجزای EditText در سلسله مراتب نمای هدف جلوگیری می کند.

همچنین، اگر ClipData با کشیدن و رها کردن شامل متن و داده‌های URI باشد، DropHelper یکی از اجزای EditText را در هدف رها کردن برای مدیریت داده‌های متنی انتخاب می‌کند. انتخاب بر اساس ترتیب اولویت زیر انجام می شود:

1. EditText که ClipData روی آن رها شده است.
2. EditText که حاوی مکان‌نمای متن (caret) است.
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 ها نمایش داده می شوند.

هشدار: DropHelper هدف رها کردن را برای گوش دادن به رویدادهای کشیدن و رها کردن و مدیریت داده های رها شده پیکربندی می کند. هنگام استفاده از DropHelper View.OnDragListener یا OnReceiveContentListener برای رها کردن اهداف پیوست نکنید.

OnReceiveContentListener همچنین داده‌هایی را که توسط تعاملات کاربر به غیر از کشیدن و رها کردن به هدف رها می‌شود مدیریت می‌کند - مانند کپی و چسباندن - زمانی که DropHelper.configureView() برای پیکربندی انواع نماهای زیر استفاده می‌شود:

• همه نماها، در صورتی که کاربر از اندروید 12 یا بالاتر استفاده می کند.
• AppCompatEditText ، اگر کاربر نسخه‌ای از اندروید را تا اندروید 7.0 اجرا می‌کند.

توجه: DropHelper از رابط Jetpack OnReceiveContentListener پشتیبانی می کند که تا سطح API 24 سازگار است. DropHelper از رابط OnReceiveContentListener که در سطح API 31 معرفی شده است پشتیبانی نمی کند.

انواع MIME، مجوزها و اعتبارسنجی محتوا

بررسی نوع MIME توسط DropHelper بر اساس کشیدن و رها کردن ClipDescription است که توسط برنامه ارائه داده‌های کشیدن و رها کردن ایجاد می‌شود. برای اطمینان از اینکه انواع MIME به درستی تنظیم شده اند، ClipDescription اعتبارسنجی کنید.

DropHelper تمام مجوزهای دسترسی را برای URIهای محتوای موجود در کشیدن و رها کردن ClipData درخواست می کند. برای اطلاعات بیشتر، DragAndDropPermissions را ببینید. مجوزها به شما این امکان را می دهند که URI های محتوا را هنگام پردازش داده های کشیدن و رها کردن، حل کنید.

DropHelper داده های بازگردانده شده توسط ارائه دهندگان محتوا را هنگام حل URI در داده های حذف شده تأیید نمی کند. تهی بودن را بررسی کنید و صحت هر گونه داده حل شده را بررسی کنید.