La classe DropHelper
semplifica l'implementazione delle funzionalità di trascinamento. Membro della libreria Jetpack DragAndDrop
, DropHelper
fornisce la compatibilità con le versioni precedenti fino al livello API 24.
Usa DropHelper
per specificare i target di rilascio, personalizzare l'evidenziazione dei target di rilascio e definire le modalità di gestione dei dati eliminati.
Imposta l'origine del trascinamento
Per iniziare, crea DragStartHelper
trascinando la vista origine e
OnDragStartListener
.
In OnDragStartListener
, esegui l'override del metodo onDragStart()
. Crea un oggetto ClipData
e un oggetto ClipData.Item
per i dati da spostare. Come parte di ClipData
, fornisci i metadati archiviati in un oggetto ClipDescription
all'interno di ClipData
. Per un'operazione di trascinamento che non rappresenta lo spostamento di dati,
è consigliabile utilizzare null
anziché un oggetto reale.
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); } });
Specifica i target di rilascio
Quando un utente rilascia un'ombra su una vista, quest'ultima deve essere configurata correttamente per accettare i dati e rispondere correttamente.
DropHelper.configureView()
è un metodo statico e sovraccarico che ti consente di specificare i target di rilascio. I suoi parametri includono:
- L'attuale
Activity
, utilizzato per le autorizzazioni URI. - Opzioni di configurazione per la destinazione di lancio, in particolare un elenco di campi
EditText
incorporati. - Un elemento
OnReceiveContentListener
per gestire i dati eliminati.
Ad esempio, per creare una destinazione che accetti le immagini, utilizza una delle seguenti chiamate al metodo:
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);
Nella seconda chiamata le opzioni di configurazione della destinazione del rilascio sono omesse, nel qual caso il colore di evidenziazione della destinazione di rilascio è impostato sul colore secondario (o intenso) del tema, il raggio dell'angolo di evidenziazione è impostato su 16 dp e l'elenco di componenti EditText
è vuoto. Per informazioni dettagliate, consulta la sezione che segue.
Configura target di rilascio
La classe interna DropHelper.Options
consente di configurare le destinazioni di rilascio. Fornisci un'istanza della classe al metodo DropHelper.configureView(Activity, View, String[], Options,
OnReceiveContentListener
). Per saperne di più, consulta la sezione precedente.
Personalizza l'evidenziazione del target di rilascio
DropHelper
configura i rilasci dei target in modo da visualizzare un'evidenziazione quando gli utenti trascinano i contenuti sopra i target. DropHelper
fornisce uno stile predefinito e
DropHelper.Options
consente di impostare il colore dell'evidenziazione e specificare il
raggio angolare del rettangolo dell'evidenziazione.
Utilizza la classe DropHelper.Options.Builder
per creare un'istanza DropHelper.Options
e impostare le opzioni di configurazione, come mostrato nell'esempio seguente:
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();
Gestire i componenti EditText nelle destinazioni di rilascio
DropHelper
controlla anche lo stato attivo all'interno della destinazione di rilascio quando quest'ultima contiene campi di testo modificabili.
Le destinazioni possono essere una singola visualizzazione o una gerarchia di viste. Se la gerarchia della vista della destinazione di rilascio contiene uno o più componenti EditText
, fornisci un elenco dei componenti per DropHelper.Options.Builder.addInnerEditTexts(EditText...)
per assicurarti che l'evidenziazione della destinazione e la gestione dei dati di testo funzionino correttamente.
DropHelper
impedisce che i componenti EditText
all'interno della gerarchia della visualizzazione della destinazione di rilascio sottraggano lo stato attivo alla vista contenitore durante le interazioni con il trascinamento.
Inoltre, se il trascinamento ClipData
include dati di testo e URI, DropHelper
seleziona uno dei componenti EditText
nella destinazione del rilascio per gestire i dati di testo. La selezione si basa sul seguente ordine di precedenza:
- L'elemento
EditText
in cui viene rilasciato il valoreClipData
. EditText
che contiene il cursore di testo (accento circonflesso).- Il primo elemento
EditText
fornito alla chiamata aDropHelper.Options.Builder.addInnerEditTexts(EditText...)
.
Per impostare un EditText
come gestore dei dati di testo predefinito, passa EditText
come primo argomento della chiamata a DropHelper.Options.Builder.addInnerEditTexts(EditText...)
. Ad esempio, se la destinazione del lancio gestisce le immagini, ma contiene i campi di testo modificabili T1
, T2
e T3
, rendi T2
il valore predefinito come segue:
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();
Gestire i dati nelle destinazioni di rilascio
Il metodo DropHelper.configureView()
accetta un OnReceiveContentListener
che crei per gestire i ClipData
di trascinamento. I dati di trascinamento vengono forniti al listener in un oggetto ContentInfoCompat
.
Nell'oggetto sono presenti dati di testo. I contenuti multimediali, come le immagini, sono rappresentati da URI.
L'OnReceiveContentListener
gestisce anche i dati forniti alla destinazione del rilascio anche da interazioni dell'utente diverse dal trascinamento, ad esempio copia e incolla, quando DropHelper.configureView()
viene utilizzato per configurare i seguenti tipi di viste:
- Tutte le visualizzazioni, se l'utente utilizza Android 12 o versioni successive.
AppCompatEditText
, se l'utente utilizza una versione di Android fino ad Android 7.0.
Tipi MIME, autorizzazioni e convalida dei contenuti
Il controllo del tipo MIME da parte di DropHelper
si basa sul trascinamento
ClipDescription
, creato dall'app che fornisce i dati di trascinamento. Convalida ClipDescription
per assicurarti che i tipi MIME siano impostati correttamente.
DropHelper
richiede tutte le autorizzazioni di accesso per gli URI dei contenuti contenuti nella funzionalità ClipData
di trascinamento. Per maggiori informazioni, consulta
DragAndDropPermissions
. Le autorizzazioni consentono di risolvere gli URI dei contenuti durante l'elaborazione dei dati di trascinamento.
DropHelper
non convalida i dati restituiti dai fornitori di contenuti durante la risoluzione degli URI nei dati eliminati. Controllate che non ci siano valori nulli e verificate la correttezza
di tutti i dati risolti.