DropHelper untuk tarik lalu lepas yang disederhanakan

Class DropHelper menyederhanakan implementasi kemampuan tarik lalu lepas. Anggota library Jetpack DragAndDrop, DropHelper menyediakan kompatibilitas mundur hingga API level 24.

Gunakan DropHelper untuk menentukan target operasi lepas, menyesuaikan sorotan target lepas, serta menentukan cara penanganan data yang dilepas.

Setel sumber tarik

Untuk memulai, buat DragStartHelper dengan tampilan sumber tarik dan OnDragStartListener.

Di OnDragStartListener, ganti metode onDragStart(). Buat objek ClipData dan objek ClipData.Item untuk data yang sedang dipindahkan. Sebagai bagian dari ClipData, berikan metadata yang disimpan di objek ClipDescription dalam ClipData. Untuk operasi tarik lalu lepas yang tidak merepresentasikan perpindahan data, Anda dapat menggunakan null, bukan objek yang sebenarnya.

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

Menentukan target operasi lepas

Saat pengguna merilis drop shadow ke atas tampilan, tampilan harus dikonfigurasi dengan benar agar dapat menerima data dan merespons dengan benar.

DropHelper.configureView() adalah metode statis yang kelebihan beban, yang memungkinkan Anda menentukan target operasi lepas. Parameternya meliputi:

• Activity saat ini—digunakan untuk izin URI.
  • View yang berfungsi sebagai target operasi lepas.
    • Jenis MIME yang dapat diterima target lepas dari data yang dilepas.
• Opsi konfigurasi untuk target operasi lepas—khususnya, daftar kolom EditText yang disematkan.
• OnReceiveContentListener untuk menangani data yang dilepaskan.

Misalnya, untuk membuat target lepas yang menerima gambar, gunakan salah satu panggilan metode berikut:

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

Panggilan kedua menghilangkan opsi konfigurasi target operasi lepas, dalam hal ini warna sorotan target lepas disetel ke warna sekunder (atau aksen) tema, radius sudut sorotan disetel ke 16 dp, dan daftar komponen EditText kosong. Lihat bagian berikut untuk mengetahui detailnya.

Mengonfigurasi target operasi lepas

Class dalam DropHelper.Options memungkinkan Anda mengonfigurasi target operasi lepas. Berikan instance class ke metode DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener). Lihat bagian sebelumnya untuk informasi selengkapnya.

Menyesuaikan penyorotan target operasi lepas

DropHelper mengonfigurasi target operasi lepas untuk menampilkan sorotan saat pengguna menarik konten ke target. DropHelper menyediakan gaya visual default, dan DropHelper.Options memungkinkan Anda menetapkan warna sorotan dan menentukan radius sudut persegi panjang sorotan.

Gunakan class DropHelper.Options.Builder untuk membuat instance DropHelper.Options dan menetapkan opsi konfigurasi, seperti yang ditunjukkan dalam contoh berikut:

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

Menangani komponen EditText dalam target operasi lepas

DropHelper juga mengontrol fokus dalam target operasi lepas saat target berisi kolom teks yang dapat diedit.

Target lepas dapat berupa tampilan tunggal atau hierarki tampilan. Jika hierarki tampilan target operasi lepas berisi satu atau beberapa komponen EditText, berikan daftar komponen ke DropHelper.Options.Builder.addInnerEditTexts(EditText...) untuk memastikan bahwa penandaan target dan penanganan data teks berfungsi dengan benar.

DropHelper mencegah komponen EditText dalam hierarki tampilan target lepas agar tidak mencuri fokus dari tampilan yang memuatnya selama interaksi tarik.

Selain itu, jika tarik lalu lepas ClipData menyertakan data teks dan URI, DropHelper akan memilih salah satu komponen EditText dalam target operasi lepas untuk menangani data teks. Pemilihan ini didasarkan pada urutan prioritas berikut:

1. EditText tempat ClipData dilepas.
2. EditText yang berisi kursor teks (tanda sisipan).
3. EditText pertama yang diberikan ke panggilan ke DropHelper.Options.Builder.addInnerEditTexts(EditText...).

Untuk menetapkan EditText sebagai pengendali data teks default, teruskan EditText sebagai argumen pertama dari panggilan tersebut ke DropHelper.Options.Builder.addInnerEditTexts(EditText...). Misalnya, jika target lepas Anda menangani gambar, tetapi berisi kolom teks yang dapat diedit T1, T2, dan T3, buat T2 sebagai default sebagai berikut:

val options: DropHelper.Options = DropHelper.Options.Builder()
                                      .addInnerEditTexts(T2, T1, T3)
                                      .build()

DropHelper.Options options = new DropHelper.Options.Builder()
                                     .addInnerEditTexts(T2, T1, T3)
                                     .build();

Menangani data di target operasi lepas

Metode DropHelper.configureView() menerima OnReceiveContentListener yang Anda buat untuk menangani ClipData tarik lalu lepas. Data tarik lalu lepas disediakan ke pemroses dalam objek ContentInfoCompat. Data teks ada di objek. Media, seperti gambar, direpresentasikan oleh URI.

OnReceiveContentListener juga menangani data yang disediakan ke target lepas oleh interaksi pengguna selain tarik lalu lepas—seperti salin dan tempel—saat DropHelper.configureView() digunakan untuk mengonfigurasi jenis tampilan berikut:

• Semua tampilan, jika pengguna menjalankan Android 12 atau yang lebih tinggi.
• AppCompatEditText, jika pengguna menjalankan versi Android hingga Android 7.0.

Jenis MIME, izin, dan validasi konten

Pemeriksaan jenis MIME oleh DropHelper didasarkan pada ClipDescription tarik lalu lepas yang dibuat oleh aplikasi yang menyediakan data tarik lalu lepas. Validasi ClipDescription untuk memastikan jenis MIME disetel dengan benar.

DropHelper meminta semua izin akses untuk URI konten yang terdapat dalam ClipData tarik lalu lepas. Untuk mengetahui informasi selengkapnya, lihat DragAndDropPermissions. Izin ini memungkinkan Anda me-resolve URI konten saat memproses data tarik lalu lepas.

DropHelper tidak memvalidasi data yang ditampilkan oleh penyedia konten saat menyelesaikan URI dalam data yang dilepaskan. Periksa null dan verifikasi ketepatan data yang telah diselesaikan.