DropHelper do uproszczonego przeciągania i upuszczania

Klasa DropHelper upraszcza wdrażanie funkcji przeciągania i upuszczania. Należy do biblioteki Jetpack DragAndDrop i zapewnia zgodność wsteczną nawet do poziomu interfejsu API 24.DropHelper

Za pomocą funkcji DropHelper możesz określić wartości docelowe, dostosować ich wyróżnianie i określić sposób postępowania z usuniętymi danymi.

Ustaw źródło przeciągania

Aby rozpocząć, utwórz DragStartHelper z widokiem źródła przeciągania i OnDragStartListener.

W zadaniu OnDragStartListener zastąp metodę onDragStart(). Utwórz obiekt ClipData i obiekt ClipData.Item dla przenoszonych danych. W ramach ClipData podaj metadane przechowywane w obiekcie ClipDescription w obrębie ClipData. W przypadku operacji przeciągania i upuszczania, która nie odzwierciedla przenoszenia danych, można użyć metody null zamiast rzeczywistego obiektu.

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

Określ docelowe wartości

Gdy użytkownik nakłada cień na widok, należy go odpowiednio skonfigurować, aby zaakceptować dane i prawidłowo zareagować.

DropHelper.configureView() to statyczna, przeciążona metoda, która umożliwia określanie wartości docelowych. Jej parametry to między innymi:

• Bieżący identyfikator Activity – używany na potrzeby uprawnień identyfikatora URI.
  • View pełniący funkcję docelowej wartości docelowej.
    • Typy MIME, które może zaakceptować z utraconych danych.
• Opcje konfiguracji miejsca docelowego – w szczególności lista umieszczonych pól EditText.
• OnReceiveContentListener do obsługi utraconych danych.

Aby na przykład utworzyć obszar docelowy, który akceptuje obrazy, użyj jednego z tych wywołań metod:

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

Drugie wywołanie pomija opcje konfiguracji miejsca docelowego. W takim przypadku kolor zaznaczenia miejsca docelowego jest ustawiony na dodatkowy (lub uzupełniający) kolor motywu, promień narożnika wyróżnienia to 16 dp, a lista komponentów EditText jest pusta. Szczegółowe informacje znajdziesz w sekcji poniżej.

Skonfiguruj docelowe obszary

Klasa wewnętrzna DropHelper.Options pozwala konfigurować wartości docelowe. Podaj instancję klasy dla metody DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener). Więcej informacji znajdziesz w poprzedniej sekcji.

Dostosuj wyróżnianie obszaru docelowego

DropHelper konfiguruje docelowe elementy w taki sposób, aby wyświetlały podświetlenie, gdy użytkownicy przeciągają treści nad nimi. DropHelper zapewnia styl domyślny, a DropHelper.Options pozwala ustawić kolor zaznaczenia i określić promień narożnika prostokąta zaznaczenia.

Użyj klasy DropHelper.Options.Builder, aby utworzyć instancję DropHelper.Options i ustawić opcje konfiguracji, jak w tym przykładzie:

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

Obsługa komponentów EditText w obszarach docelowych

DropHelper kontroluje też obszar docelowy, gdy zawiera on pola tekstowe z możliwością edytowania.

Miejsca docelowe mogą być pojedynczym widokiem lub hierarchią widoków. Jeśli hierarchia widoku miejsca docelowego zawiera co najmniej 1 komponent EditText, podaj listę tych komponentów, aby DropHelper.Options.Builder.addInnerEditTexts(EditText...) zadbać o prawidłowe wyróżnianie miejsca docelowego i prawidłową obsługę danych tekstowych.

Funkcja DropHelper uniemożliwia komponentom EditText w hierarchii widoku miejsca docelowego rozproszenie uwagi z widoku zawierającego ten element podczas interakcji z przeciąganiem.

Poza tym jeśli przeciąganie i upuszczanie ClipData obejmuje dane tekstowe i identyfikator URI, DropHelper wybiera w obszarze docelowym jeden z komponentów EditText do obsługi danych tekstowych. Wybór zależy od tej kolejności:

1. EditText, na którym spada ClipData.
2. Element EditText zawierający kursor tekstowy (znak wstawienia).
3. Pierwszy typ EditText podany w wywołaniu DropHelper.Options.Builder.addInnerEditTexts(EditText...).

Aby ustawić EditText jako domyślny moduł obsługi danych tekstowych, przekaż EditText jako pierwszy argument wywołania DropHelper.Options.Builder.addInnerEditTexts(EditText...). Jeśli na przykład miejsce docelowe obsługuje obrazy, ale zawiera pola tekstowe T1, T2 i T3, które można edytować, ustaw T2 jako wartość domyślną w ten sposób:

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

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

Obsługuj dane w docelowych wartościach

Metoda DropHelper.configureView() akceptuje utworzony przez Ciebie element OnReceiveContentListener na potrzeby przeciągania i upuszczania elementów ClipData. Dane, które można przeciągnąć i upuścić, są przekazywane do odbiornika w obiekcie ContentInfoCompat. Obiekt zawiera dane tekstowe. Multimedia, takie jak obrazy, są reprezentowane przez identyfikatory URI.

Element OnReceiveContentListener obsługuje też dane przekazywane do miejsca docelowego w wyniku działań użytkowników innych niż przeciąganie i upuszczanie, np. kopiowanie i wklejanie, gdy DropHelper.configureView() służy do konfigurowania tych typów widoków:

• Wszystkie widoki, jeśli użytkownik korzysta z Androida 12 lub nowszego.
• AppCompatEditText, jeśli użytkownik ma Androida w wersji starszej do 7.0.

Typy MIME, uprawnienia i weryfikacja treści

Sprawdzanie typu MIME przez DropHelper odbywa się w ramach metody przeciągania i upuszczania ClipDescription, którą tworzy aplikacja dostarczająca dane. Sprawdź ClipDescription, aby mieć pewność, że typy MIME są ustawione prawidłowo.

DropHelper prosi o wszystkie uprawnienia dostępu do identyfikatorów URI treści zawartych w metodzie ClipData metodą przeciągania i upuszczania. Więcej informacji: DragAndDropPermissions. Uprawnienia umożliwiają rozpoznanie identyfikatorów URI treści podczas przetwarzania danych metodą „przeciągnij i upuść”.

DropHelper nie weryfikuje danych zwróconych przez dostawców treści podczas rozpoznawania identyfikatorów URI w usuniętych danych. Poszukaj wartości null i sprawdź poprawność wykrytych danych.