DropHelper לגרירה ושחרור פשוטים

השיעור DropHelper הופך לפשוט יותר הטמעת יכולות של גרירה ושחרור. חבר/ה ב-Jetpack DragAndDrop ספרייה, DropHelper תאימות לאחור עד לרמת API 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);

הקריאה השנייה לא תכיל את אפשרויות ההגדרה של היעד הגיאוגרפי. במקרה כזה צבע היעד של ההדגשה מוגדר לצבע המשני (או המשני) של העיצוב. הרדיוס של פינת ההדגשה מוגדר כ-16dp והרשימה של EditText ריקים. פרטים נוספים זמינים בקטע הבא.

הגדרת יעדי ירידה

DropHelper.Options במחלקה הפנימית אפשר להגדיר יעדים שיושמטו. צריך לספק מופע של הכיתה כדי DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener) . מידע נוסף זמין בקטע הקודם.

התאמה אישית של ההדגשה של יעדי המודעות

DropHelper מגדיר יעדים של שחרור כדי להציג הדגשה כשמשתמשים גוררים תוכן מעל היעדים. DropHelper מספק עיצוב שמוגדר כברירת מחדל באמצעות DropHelper.Options אפשר להגדיר את צבע ההדגשה ולציין את של מלבן ההדגשה.

משתמשים ב DropHelper.Options.Builder class כדי ליצור מכונה של 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 רכיבים ביעד בענן כדי לטפל בנתוני הטקסט. הבחירה מבוססת על סדר הקדימות הבא:

1. ה-EditText שעליו ה-ClipData הושמט.
2. השדה EditText שמכיל את סמן הטקסט (סמן).
3. ה-EditText הראשון סופק לשיחה ל- DropHelper.Options.Builder.addInnerEditTexts(EditText...).

כדי להגדיר EditText כ-handler של נתוני טקסט כברירת מחדל, צריך להעביר את 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.

אזהרה: ב-DropHelper מגדירים את יעד הפלה כדי להאזין לגרירה ושחרור אירועים וכדי לטפל בנתונים שהושמטו. לא לצרף View.OnDragListener או OnReceiveContentListener כדי להקטין את היעדים כשמשתמשים ב-DropHelper.

השדה OnReceiveContentListener מטפל גם בנתונים שסופקו ליעד לירידה באמצעות אינטראקציות של משתמשים שאינן גרירה ושחרור - כמו העתקה להדביק – כשנעשה שימוש ב-DropHelper.configureView() כדי להגדיר סוגי צפיות:

• כל התצוגות, אם למשתמש פועלת מערכת Android מגרסה 12 ואילך.
• AppCompatEditText אם למשתמש פועלת גרסה של Android עד Android 7.0.

הערה: DropHelper תומך ב-Jetpack OnReceiveContentListener תואם לאחור עד לרמת API 24. DropHelper לא תומך בפלטפורמה OnReceiveContentListener בממשק API ברמת 31.

סוגי MIME, הרשאות ואימות תוכן

הבדיקה של סוג MIME על ידי DropHelper מבוססת על גרירה ושחרור ClipDescription, שהוא שנוצרה על ידי האפליקציה שמספקת את הנתונים מסוג 'גרירה ושחרור'. אימות של ClipDescription כדי לוודא שסוגי ה-MIME מוגדרים כראוי.

DropHelper מבקש את כל הרשאות הגישה למזהי URI של תוכן הכלולים ClipData גוררים ומשחררים. מידע נוסף זמין במאמר הבא: DragAndDropPermissions הרשאות מאפשרות לכם לזהות את מזהי ה-URI של התוכן במהלך עיבוד הגרירה והשחרור .

DropHelper לא מאמת את הנתונים שמוחזרים על ידי ספקי התוכן כאשר התאמת מזהי URI בנתונים שהושמטו. בדוק אם הערך הוא null ואמת את נכונות כל הנתונים שנסגרו.