Halaman ini diterjemahkan oleh Cloud Translation API.

DropHelper untuk tarik lalu lepas sederhana

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.

Menyetel sumber tarik

Untuk memulai, buat DragStartHelper dengan {i>drag<i} {i>source view<i} dan OnDragStartListener.

Di OnDragStartListener, metode penggantian onDragStart(). Membuat objek ClipData dan ClipData.Item untuk data yang sedang dipindahkan. Sebagai bagian dari ClipData, menyediakan metadata yang disimpan di objek ClipDescription dalam ClipData. Untuk operasi tarik lalu lepas yang tidak mewakili perpindahan data, Anda mungkin ingin menggunakan null daripada objek yang sebenarnya.

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

Tentukan target operasi lepas

Jika pengguna melepaskan drop shadow di atas tampilan, tampilan tersebut perlu dikonfigurasi untuk menerima data dan merespons dengan benar.

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

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

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

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

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

Mengonfigurasi target operasi lepas

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

Sesuaikan penyorotan target lepas

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

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

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

Menangani komponen EditText dalam target operasi lepas

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

Target lepas dapat berupa tampilan tunggal atau hierarki tampilan. Jika tampilan target lepas hierarki berisi satu atau beberapa EditText menyediakan daftar komponen untuk DropHelper.Options.Builder.addInnerEditTexts(EditText...) untuk memastikan penghapusan penyorotan target dan penanganan data teks bekerja dengan benar.

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

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

EditText tempat ClipData dilepas.
EditText yang berisi kursor teks (tanda sisipan).
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:

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

Menangani data pada target operasi lepas

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

OnReceiveContentListener juga menangani data yang diberikan ke target operasi lepas dengan interaksi pengguna selain {i>drag and drop<i}—seperti menyalin dan tempel—saat DropHelper.configureView() digunakan untuk mengonfigurasi hal berikut jenis tampilan:

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

Jenis MIME, izin, dan validasi konten

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

DropHelper meminta semua izin akses untuk URI konten yang ada dalam tarik lalu lepas ClipData. Untuk informasi selengkapnya, lihat DragAndDropPermissions Tujuan memungkinkan Anda menangani URI konten saat memproses operasi tarik lalu lepas layanan otomatis dan data skalabel.

DropHelper tidak memvalidasi data yang ditampilkan oleh penyedia konten saat menyelesaikan URI dalam data yang dihapus. Periksa {i>null <i}dan verifikasi kebenarannya setiap data yang diselesaikan.