DropHelper für vereinfachtes Drag-and-drop

Die Klasse DropHelper vereinfacht die Implementierung von Drag-and-drop-Funktionen. DropHelper ist ein Mitglied der Jetpack-Bibliothek DragAndDrop und bietet Abwärtskompatibilität bis API-Level 24.

Verwenden Sie DropHelper, um Drop-Ziele anzugeben, die Hervorhebung von Drop-Zielen anzupassen und zu definieren, wie gelöschte Daten verarbeitet werden sollen.

Ziehquelle festlegen

Erstellen Sie zuerst DragStartHelper mit der Quellansicht per Drag-and-drop und OnDragStartListener.

Überschreiben Sie in OnDragStartListener die Methode onDragStart(). Erstellen Sie ein ClipData- und ein ClipData.Item-Objekt für die zu verschiebenden Daten. Geben Sie als Teil des ClipData Metadaten an, die in einem ClipDescription-Objekt innerhalb des ClipData gespeichert werden. Bei einem Drag-and-drop-Vorgang, der keine Datenbewegung darstellt, können Sie null anstelle eines tatsächlichen Objekts verwenden.

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

Drop-Ziele angeben

Wenn ein Nutzer einen Schlagschatten über einer Ansicht loslässt, muss die Ansicht so konfiguriert werden, dass sie die Daten akzeptiert und korrekt reagiert.

DropHelper.configureView() ist eine statische, überlastete Methode, mit der Sie Drop-Ziele angeben können. Zu den Parametern gehören:

• Das aktuelle Activity, das für URI-Berechtigungen verwendet wird.
  • Ein View, das als Drop-Ziel dient.
    • Die MIME-Typen, die das Ablageziel aus den gelöschten Daten akzeptieren kann.
• Konfigurationsoptionen für das Drop-Ziel, insbesondere eine Liste von eingebetteten EditText-Feldern.
• Ein OnReceiveContentListener zur Verarbeitung gelöschter Daten.

Wenn Sie beispielsweise ein Drop-Ziel erstellen möchten, das Bilder akzeptiert, verwenden Sie einen der folgenden Methodenaufrufe:

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

Beim zweiten Aufruf werden die Konfigurationsoptionen für das Drop-Ziel weggelassen. In diesem Fall wird die Markierungsfarbe des abgelegten Ziels auf die sekundäre (oder Akzentfarbe) des Designs festgelegt, der Radius der Hervorhebung wird auf 16 dp festgelegt und die Liste der EditText-Komponenten ist leer. Weitere Informationen dazu finden Sie im folgenden Abschnitt.

Drop-Ziele konfigurieren

Mit der inneren Klasse DropHelper.Options können Sie Drop-Ziele konfigurieren. Geben Sie eine Instanz der Klasse für die Methode DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener) an. Weitere Informationen finden Sie im vorherigen Abschnitt.

Hervorhebung von Drop-Zielen anpassen

DropHelper konfiguriert Drop-Ziele so, dass ein Highlight angezeigt wird, wenn Nutzer Inhalte über die Ziele ziehen. Mit DropHelper wird der Standardstil festgelegt. Mit DropHelper.Options können Sie die Farbe der Markierung festlegen und den Eckenradius des Rechtecks angeben.

Verwenden Sie die Klasse DropHelper.Options.Builder, um eine DropHelper.Options-Instanz zu erstellen und Konfigurationsoptionen festzulegen, wie im folgenden Beispiel gezeigt:

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

EditText-Komponenten in Drop-Zielen verarbeiten

DropHelper steuert auch den Fokus innerhalb des Drop-down-Ziels, wenn das Ziel bearbeitbare Textfelder enthält.

Abgelegte Ziele können eine einzelne Datenansicht oder eine Ansichtshierarchie sein. Wenn die Hierarchie der Drop-Zielansicht eine oder mehrere EditText-Komponenten enthält, stellen Sie eine Liste der Komponenten für DropHelper.Options.Builder.addInnerEditTexts(EditText...) bereit, damit die Markierung von Drop-Zielen und die Verarbeitung von Textdaten korrekt funktionieren.

DropHelper verhindert, dass EditText-Komponenten innerhalb der Hierarchie der Zielansicht den Fokus von der beinhaltenden Ansicht während Drag-Interaktionen stehlen.

Wenn das Drag-and-drop ClipData Text- und URI-Daten enthält, wählt DropHelper eine der EditText-Komponenten im Drop-Ziel aus, um die Textdaten zu verarbeiten. Die Auswahl erfolgt nach der folgenden Rangfolge:

1. Das EditText, auf dem das ClipData-Objekt abgelegt wird.
2. Das EditText, das den Textcursor (Caret) enthält.
3. Die erste EditText, die für den Aufruf von DropHelper.Options.Builder.addInnerEditTexts(EditText...) bereitgestellt wurde.

Wenn Sie ein EditText als Standard-Textdaten-Handler festlegen möchten, übergeben Sie EditText als erstes Argument des Aufrufs an DropHelper.Options.Builder.addInnerEditTexts(EditText...). Wenn das Drop-Ziel beispielsweise Bilder verarbeitet, aber die bearbeitbaren Textfelder T1, T2 und T3 enthält, legen Sie T2 als Standard fest:

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

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

Daten in Drop-Zielen verarbeiten

Die Methode DropHelper.configureView() akzeptiert ein OnReceiveContentListener, das Sie für die Verarbeitung der Drag-and-drop-Funktion ClipData erstellen. Die Drag-and-drop-Daten werden für den Listener in einem ContentInfoCompat-Objekt bereitgestellt. Im Objekt sind Textdaten vorhanden. Medien wie Bilder werden durch URIs dargestellt.

Der OnReceiveContentListener verarbeitet auch Daten, die von anderen Nutzerinteraktionen als Drag-and-drop (z. B. Kopieren und Einfügen) an das Ablageziel gesendet werden, wenn DropHelper.configureView() zum Konfigurieren der folgenden Ansichten verwendet wird:

• Alle Aufrufe, wenn der Nutzer Android 12 oder höher verwendet
• AppCompatEditText, wenn der Nutzer eine Android-Version bis Android 7.0 ausführt.

MIME-Typen, Berechtigungen und Inhaltsvalidierung

Die MIME-Typ-Prüfung durch DropHelper basiert auf ClipDescription per Drag-and-drop, das von der App erstellt wird, die die Drag-and-drop-Daten bereitstellt. Prüfen Sie ClipDescription, ob die MIME-Typen richtig festgelegt sind.

DropHelper fordert alle Zugriffsberechtigungen für Inhalts-URIs an, die im Drag-and-drop-ClipData enthalten sind. Weitere Informationen findest du unter DragAndDropPermissions. Mit den Berechtigungen können Sie die Inhalts-URIs bei der Verarbeitung der Drag-and-drop-Daten auflösen.

DropHelper validiert nicht die Daten, die von Contentanbietern bei der Auflösung von URIs in den gelöschten Daten zurückgegeben werden. Prüfen Sie auf NULL-Werte und verifizieren Sie die Richtigkeit aller aufgelösten Daten.