La classe DropHelper
simplifie l'implémentation des fonctionnalités de glisser-déposer. Membre de la bibliothèque Jetpack DragAndDrop
, DropHelper
offre une rétrocompatibilité jusqu'au niveau d'API 24.
Utilisez DropHelper
pour spécifier des cibles de dépôt, personnaliser leur mise en surbrillance et définir la manière dont les données supprimées sont traitées.
Définir la source du déplacement
Pour commencer, créez DragStartHelper
en faisant glisser la vue source et en OnDragStartListener
.
Dans OnDragStartListener
, remplacez la méthode onDragStart()
. Créez un objet ClipData
et un objet ClipData.Item
pour les données à déplacer. Dans le cas de ClipData
, fournissez les métadonnées stockées dans un objet ClipDescription
au sein du ClipData
. Pour une opération de glisser-déposer qui ne représente pas un déplacement de données, vous pouvez utiliser null
au lieu d'un objet réel.
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); } });
Spécifier des cibles de dépôt
Lorsqu'un utilisateur libère une ombre projetée sur une vue, celle-ci doit être correctement configurée pour accepter les données et répondre correctement.
DropHelper.configureView()
est une méthode statique surchargée qui vous permet de spécifier des cibles de dépôt. Ses paramètres incluent les suivants:
- Le
Activity
actuel, utilisé pour les autorisations d'URI.- Un élément
View
qui sert de cible de lancement.- Types MIME que la cible de suppression peut accepter à partir des données supprimées.
- Un élément
- Options de configuration de la cible de suppression, en particulier une liste de champs
EditText
intégrés. - Un objet
OnReceiveContentListener
pour gérer les données supprimées.
Par exemple, pour créer une cible de dépôt qui accepte les images, utilisez l'un des appels de méthode suivants:
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);
Le deuxième appel omet les options de configuration de la cible de dépôt. Dans ce cas, la couleur de mise en surbrillance de la cible de chute est définie sur la couleur secondaire (ou d'accentuation) du thème, le rayon de l'angle de mise en surbrillance est défini sur 16 dp et la liste des composants EditText
est vide. Pour en savoir plus, consultez la section suivante.
Configurer les cibles de dépôt
La classe interne DropHelper.Options
vous permet de configurer des cibles de dépôt. Fournissez une instance de la classe à la méthode DropHelper.configureView(Activity, View, String[], Options,
OnReceiveContentListener
). Pour en savoir plus, consultez la section précédente.
Personnaliser la mise en surbrillance des cibles de dépôt
DropHelper
configure les cibles de dépôt pour afficher une mise en surbrillance lorsque les utilisateurs font glisser du contenu sur les cibles. DropHelper
fournit un style par défaut, et DropHelper.Options
vous permet de définir la couleur de la mise en surbrillance et de spécifier l'arrondi d'angle de ce rectangle.
Utilisez la classe DropHelper.Options.Builder
pour créer une instance DropHelper.Options
et définir les options de configuration, comme illustré dans l'exemple suivant:
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();
Gérer les composants EditText dans les cibles de dépôt
DropHelper
contrôle également le ciblage dans la cible de dépôt lorsque celle-ci contient des champs de texte modifiables.
Les cibles de suppression peuvent être une vue unique ou une hiérarchie de vues. Si la hiérarchie des vues des cibles de dépôt contient un ou plusieurs composants EditText
, fournissez une liste des composants à DropHelper.Options.Builder.addInnerEditTexts(EditText...)
pour vous assurer que la mise en surbrillance de la cible de dépôt et la gestion des données textuelles fonctionnent correctement.
DropHelper
empêche les composants EditText
de la hiérarchie des vues des cibles de dépôt de prendre le focus de la vue parent lors des interactions de déplacement.
De plus, si le glisser-déposer ClipData
inclut du texte et des données d'URI, DropHelper
sélectionne l'un des composants EditText
de la cible de dépôt pour gérer les données textuelles. La sélection est basée sur l'ordre de priorité suivant:
- Le
EditText
sur lequel leClipData
est supprimé. EditText
contenant le curseur de texte (signe d'insertion).- Le premier
EditText
fourni à l'appel deDropHelper.Options.Builder.addInnerEditTexts(EditText...)
.
Pour définir EditText
comme gestionnaire de données textuelles par défaut, transmettez EditText
comme premier argument de l'appel à DropHelper.Options.Builder.addInnerEditTexts(EditText...)
. Par exemple, si votre cible de dépôt gère les images, mais contient les champs de texte modifiables T1
, T2
et T3
, définissez T2
comme valeur par défaut:
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();
Gérer les données dans les cibles de dépôt
La méthode DropHelper.configureView()
accepte un OnReceiveContentListener
que vous créez pour gérer le ClipData
de glisser-déposer. Les données de glisser-déposer sont fournies à l'écouteur dans un objet ContentInfoCompat
.
L'objet contient des données textuelles. Les contenus multimédias, tels que les images, sont représentés par des URI.
OnReceiveContentListener
gère également les données fournies à la cible de dépôt par les interactions utilisateur autres que le glisser-déposer (comme le copier-coller) lorsque DropHelper.configureView()
est utilisé pour configurer les types de vues suivants:
- Toutes les vues, si l'utilisateur est équipé d'Android 12 ou version ultérieure
AppCompatEditText
, si l'utilisateur exécute une version d'Android antérieure à Android 7.0.
Types MIME, autorisations et validation du contenu
La vérification du type MIME par DropHelper
est basée sur le glisser-déposer ClipDescription
, qui est créé par l'application fournissant les données de glisser-déposer. Validez ClipDescription
pour vous assurer que les types MIME sont correctement définis.
DropHelper
demande toutes les autorisations d'accès pour les URI de contenu contenus dans le ClipData
glisser-déposer. Pour en savoir plus, consultez DragAndDropPermissions
. Les autorisations vous permettent de résoudre les URI de contenu lors du traitement des données par glisser-déposer.
DropHelper
ne valide pas les données renvoyées par les fournisseurs de contenu lors de la résolution des URI dans les données supprimées. Recherchez la valeur nulle et vérifiez l'exactitude des données résolues.