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.
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); } });
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. - 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:
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);
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:
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();
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:
EditText
, na którym spadaClipData
.- Element
EditText
zawierający kursor tekstowy (znak wstawienia). - Pierwszy typ
EditText
podany w wywołaniuDropHelper.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:
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();
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 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.