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

การเรียกใช้ครั้งที่ 2 ละเว้นตัวเลือกการกำหนดค่าเป้าหมายแบบเลื่อนลง ซึ่งในกรณีนี้ สีไฮไลต์เป้าหมายแบบเลื่อนลงจะเป็นสีรอง (หรือสีเฉพาะจุด) ของธีม รัศมีของมุมไฮไลต์กำหนดไว้ที่ 16 dp และแสดงรายการ EditText คอมโพเนนต์ว่างเปล่า ดูรายละเอียดในส่วนต่อไปนี้

กำหนดค่าเป้าหมายการลดลง

DropHelper.Options คลาสภายในช่วยให้คุณกำหนดค่าเป้าหมายการลดลงได้ ระบุอินสแตนซ์ของชั้นเรียนเพื่อ DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener) ดูข้อมูลเพิ่มเติมได้ในส่วนก่อนหน้า

ปรับแต่งการไฮไลต์เป้าหมายแบบเลื่อนลง

DropHelper กำหนดค่าเป้าหมายการวางเพื่อแสดงไฮไลต์ขณะที่ผู้ใช้ลาก เนื้อหาสูงกว่าเป้าหมาย DropHelper มีการจัดรูปแบบเริ่มต้นและ DropHelper.Options ให้คุณตั้งค่าสีของไฮไลต์และระบุ รัศมีมุมของสี่เหลี่ยมผืนผ้าของไฮไลต์

ใช้เมนู DropHelper.Options.Builder ในการสร้างอินสแตนซ์ 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 อย่างน้อย 1 รายการ ให้รายการของคอมโพเนนต์เพื่อ 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 เป็นค่าเริ่มต้นดังนี้

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

OnReceiveContentListener ยังจัดการข้อมูลที่ให้ไว้กับเป้าหมายการลดลงโดย การโต้ตอบของผู้ใช้นอกเหนือจากการลากและวาง เช่น การคัดลอกและ วาง เมื่อใช้ DropHelper.configureView() เพื่อกำหนดค่ารายการต่อไปนี้ ประเภทของมุมมอง:

  • การดูทั้งหมดหากผู้ใช้ใช้ Android 12 ขึ้นไป
  • AppCompatEditText หากผู้ใช้ใช้ Android ตั้งแต่เวอร์ชัน Android 7.0 ขึ้นไป

ประเภท สิทธิ์ และการตรวจสอบเนื้อหา MIME

การตรวจสอบประเภท MIME โดย DropHelper จะอิงตามการลากและวาง ClipDescription ซึ่งก็คือ ที่สร้างขึ้นโดยแอปที่ให้ข้อมูลการลากและวาง ตรวจสอบความถูกต้องของ ClipDescriptionเพื่อให้มั่นใจว่าตั้งค่าประเภท MIME ไว้อย่างถูกต้อง

DropHelper ขอสิทธิ์ทั้งหมดสำหรับ URI เนื้อหาที่มีอยู่ใน ลากและวาง ClipData สำหรับข้อมูลเพิ่มเติม โปรดดู DragAndDropPermissions สิทธิ์ช่วยให้คุณแก้ไข URI ของเนื้อหาได้เมื่อประมวลผลการลากและวาง

DropHelper ไม่ได้ตรวจสอบข้อมูลที่ผู้ให้บริการเนื้อหาส่งคืนมา การแปลง URI ในข้อมูลที่ลดลง ตรวจหาค่า Null และยืนยันความถูกต้องของ ข้อมูลใดๆ ที่แก้ไขแล้ว