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

کلاس DropHelper پیاده‌سازی قابلیت‌های کشیدن و رها کردن را ساده می‌کند. عضوی از کتابخانه Jetpack DragAndDrop، DropHelper سازگاری با نسخه‌های قدیمی را تا سطح میانای برنامه‌سازی کاربردی ۲۴ ارائه می‌دهد.

از 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);

در تماس دوم، گزینه‌های پیکربندی هدف رها کردن حذف می‌شود که در این حالت، رنگ برجسته هدف رها کردن روی رنگ ثانویه (یا رنگ تأکیدی) زمینه تنظیم می‌شود، شعاع گوشه برجسته روی ۱۶ dp تنظیم می‌شود، و فهرست مؤلفه‌های 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) نشان داده می‌شوند.

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

OnReceiveContentListener همچنین داده‌های ارائه‌شده به مقصد رها کردن را ازطریق تعاملات کاربر به‌جز کشیدن و رها کردن (مانند کپی و جای‌گذاری) مدیریت می‌کند، زمانی که از DropHelper.configureView() برای پیکربندی انواع نماهای زیر استفاده می‌شود:

• همه نماها، اگر کاربر از Android نسخه ۱۲ یا بالاتر استفاده می‌کند.
• AppCompatEditText، اگر کاربر از نسخه‌ای از Android تا Android 7.0 استفاده می‌کند.

توجه: DropHelper از میانای OnReceiveContentListener Jetpack پشتیبانی می‌کند که با نسخه‌های قدیمی‌تر تا سطح میانای برنامه‌سازی کاربردی ۲۴ سازگار است. DropHelper از میانای پلاتفرم OnReceiveContentListener معرفی‌شده در سطح میانای برنامه‌سازی کاربردی ۳۱ پشتیبانی نمی‌کند.

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

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

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

‫DropHelper داده‌های برگردانده‌شده توسط ارائه‌دهندگان محتوا را هنگام حل کردن URI در داده‌های رهاشده اعتبارسنجی نمی‌کند. مقادیر تهی را بررسی کنید و درستی هرگونه داده حل‌شده را تأیید کنید.