DropHelper per il trascinamento semplificato

La classe DropHelper semplifica delle funzionalità di trascinamento. Un membro del Jetpack Raccolta DragAndDrop, DropHelper fornisce la compatibilità con le versioni precedenti fino al livello API 24.

Usa DropHelper per specificare obiettivi di rilascio, personalizzare l'evidenziazione dei target di rilascio e definire le modalità di gestione dei dati eliminati.

Imposta origine di trascinamento

Nota: vedi Demo di trascinamento per un esempio completo di implementazione.

Per iniziare, crea DragStartHelper con trascinamento della visualizzazione delle origini e OnDragStartListener.

In OnDragStartListener, metodo di override onDragStart(). Crea un oggetto ClipData e ClipData.Item per i dati che vengono spostati. Nell'ambito di ClipData, fornisce metadati archiviati in un oggetto ClipDescription all'interno del ClipData. Per un'operazione di trascinamento che non rappresenta il movimento dei dati, potresti utilizzare null al posto di un oggetto effettivo.

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 obiettivi di rilascio

Quando un utente rilascia un'ombra su una vista, quest'ultima deve essere configurata. per accettare i dati e rispondere correttamente.

DropHelper.configureView() è un metodo statico e sovraccarico che ti consente di specificare i target di rilascio. È includono i seguenti:

• L'attuale Activity, utilizzato per URI autorizzazioni.
  • Un elemento View che funge da target per il rilascio.
    • I tipi MIME la destinazione può accettare dai dati rilasciati.
• Le opzioni di configurazione per il target del rilascio, in particolare un elenco incorporati EditText campi.
• Un OnReceiveContentListener per gestire i dati scartati.

Ad esempio, per creare una destinazione di rilascio che accetti immagini, utilizza uno dei due le 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 vengono omesse le opzioni di configurazione della destinazione del rilascio, nel qual caso il colore di evidenziazione target per il rilascio è impostato sul colore secondario (o di contrasto) del tema, il raggio dell'angolo di evidenziazione è impostato su 16 dp e l'elenco di EditText componenti è vuoto. Per informazioni dettagliate, consulta la sezione che segue.

Configura i punti di rilascio

La DropHelper.Options e ti consente di configurare i target di rilascio. fornisci un'istanza della classe 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 target di rilascio per mostrare un'evidenziazione durante il trascinamento degli utenti contenuti rispetto ai target. DropHelper fornisce uno stile predefinito e DropHelper.Options ti consente di impostare il colore dell'evidenziazione e di specificare raggio d'angolo del rettangolo di evidenziazione.

Utilizza la 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 nei target di rilascio

DropHelper controlla anche l'elemento attivo nel target del calo quando quest'ultimo contiene campi di testo modificabili.

Le destinazioni per il rilascio possono essere una visualizzazione singola o una gerarchia di visualizzazioni. Se la vista del target in calo la gerarchia contiene uno o più EditText componenti, fornire un elenco dei componenti DropHelper.Options.Builder.addInnerEditTexts(EditText...) per assicurarti che l'evidenziazione della destinazione del rilascio e la gestione dei dati di testo funzionino correttamente.

DropHelper impedisce i componenti EditText nella vista target di rilascio nella gerarchia di sottrarre lo stato attivo dalla vista contenitore durante le interazioni di trascinamento.

Inoltre, se l'icona di trascinamento ClipData include dati di testo e URI, DropHelper seleziona uno dei EditText nella destinazione del rilascio per gestire i dati di testo. La selezione si basa sul nel seguente ordine di precedenza:

1. EditText su cui viene rilasciato ClipData.
2. L'elemento EditText che contiene il cursore di testo (accento circonflesso).
3. Il primo EditText fornito per la chiamata a DropHelper.Options.Builder.addInnerEditTexts(EditText...).

Per impostare EditText come gestore di dati di testo predefinito, trasmetti EditText come il primo argomento della chiamata a DropHelper.Options.Builder.addInnerEditTexts(EditText...). Ad esempio, se la destinazione del rilascio gestisce le immagini, ma contiene i campi di testo modificabili T1, T2, e T3, imposta T2 come 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 nei target di rilascio

Il metodo DropHelper.configureView() accetta un OnReceiveContentListener che crei per gestire il trascinamento ClipData. I dati drag-and-drop viene fornito all'ascoltatore in un ContentInfoCompat. Nell'oggetto sono presenti dati di testo. I contenuti multimediali, come le immagini, sono rappresentati per gli URI.

Avviso: DropHelper configura la destinazione del rilascio per rimanere in ascolto del trascinamento eventi e gestire i dati rilasciati. Non allegare un View.OnDragListener oppure OnReceiveContentListener per abbassare i target quando utilizzi DropHelper.

OnReceiveContentListener gestisce anche i dati forniti al target del calo da interazioni degli utenti diverse dal trascinamento, ad esempio copia e Incolla: quando viene utilizzato DropHelper.configureView() per configurare quanto segue tipi di visualizzazioni:

• 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.

di Gemini Advanced.

Nota: DropHelper supporta Jetpack OnReceiveContentListener compatibile con le versioni precedenti fino al livello API 24. DropHelper non supporta la piattaforma OnReceiveContentListener introdotta nel livello API 31.

Convalida di tipi MIME, autorizzazioni e contenuti

Il controllo del tipo MIME da parte di DropHelper si basa sul trascinamento ClipDescription, ovvero creati 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 in trascina ClipData. Per ulteriori informazioni, vedi DragAndDropPermissions La le autorizzazioni consentono di risolvere gli URI dei contenuti durante l'elaborazione del trascinamento e i dati di Google Cloud.

DropHelper non convalida i dati restituiti dai fornitori di contenuti quando risolvere gli URI nei dati eliminati. Controlla che non ci sia alcun valore e verifica la correttezza di dati risolti.