Umfassende Inhalte erhalten

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
Abbildung 1: Die einheitliche API bietet einen zentralen unabhängig vom jeweiligen UI-Mechanismus wie durch Berührung und oder per Drag-and-drop auswählen.

Nutzer mögen Bilder, Videos und andere ausdrucksstarke Inhalte, aber das Einfügen und Es ist nicht immer einfach, diese Inhalte in Apps zu verschieben. Damit Apps einfacher Rich Content empfangen, wird mit Android 12 (API-Level 31) eine einheitliche API eingeführt, die ermöglicht deine App, Inhalte aus jeder Quelle zu akzeptieren: Zwischenablage, Tastatur oder Ziehvorgang.

Sie können eine Schnittstelle anhängen, z. B. OnReceiveContentListener, an UI-Komponenten übergeben und einen Callback erhalten, wenn Inhalte über eine beliebige Mechanismus zur Verfügung. Der Callback wird zur einzigen Stelle, an der Ihr Code die alle Inhalte empfangen, von einfachem Text bis hin zu Markup, Bildern, Videos Audiodateien usw.

Aus Gründen der Abwärtskompatibilität mit früheren Android-Versionen ist diese API auch in AndroidX verfügbar, ab Core 1.7 und Appcompat 1.4 die wir für die Implementierung dieser Funktion empfehlen.

Übersicht

Bei anderen vorhandenen APIs kann jeder UI-Mechanismus, wie der Touch- und Menü „Halten“ oder Ziehen – hat eine eigene entsprechende API. Das bedeutet, dass Sie in jede API integriert werden, wobei für jeden Mechanismus ähnlicher Code fügt Inhalt ein:

<ph type="x-smartling-placeholder">
</ph> Ein Bild, das die verschiedenen zu implementierenden Aktionen und die entsprechende API zeigt <ph type="x-smartling-placeholder">
</ph> Abbildung 2: Bisher wurde in Apps für jede Benutzeroberfläche eine andere API implementiert. zum Einfügen von Inhalten.

Die OnReceiveContentListener API konsolidiert diese verschiedenen Codepfade, indem Sie brauchen nur eine API zu implementieren, damit Sie sich auf die App-spezifische Logik konzentrieren können. Den Rest übernimmt die Plattform:

<ph type="x-smartling-placeholder">
</ph> Ein Bild, das die vereinfachte einheitliche API zeigt <ph type="x-smartling-placeholder">
</ph> Abbildung 3: Mit der einheitlichen API können Sie ein einzelnes API, die alle UI-Mechanismen unterstützt.

Dieser Ansatz bedeutet auch, dass neue Möglichkeiten zum Einfügen von Inhalten müssen Sie keine zusätzlichen Codeänderungen vornehmen, in Ihrer App. Wenn Ihre App eine vollständige Anpassung für eine können Sie weiterhin die vorhandenen APIs verwenden, auf die gleiche Weise.

Implementierung

Die API ist eine Listener-Schnittstelle mit einer einzigen Methode, OnReceiveContentListener Zur Unterstützung älterer Versionen der Android-Plattform empfehlen wir die Verwendung des Übereinstimmung OnReceiveContentListener in der AndroidX Core-Bibliothek.

Implementieren Sie den Listener zur Verwendung der API, indem Sie angeben, welche Inhaltstypen kann Folgendes verarbeiten:

Kotlin

object MyReceiver : OnReceiveContentListener {
    val MIME_TYPES = arrayOf("image/*", "video/*")
    
    // ...
    
    override fun onReceiveContent(view: View, payload: ContentInfoCompat): ContentInfoCompat? {
        TODO("Not yet implemented")
    }
}

Java

public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};
     // ...
}

Nachdem Sie alle von Ihrer App unterstützten Inhalts-MIME-Typen angegeben haben, implementieren Sie für den Rest des Listeners:

Kotlin

class MyReceiver : OnReceiveContentListener {
    override fun onReceiveContent(view: View, contentInfo: ContentInfoCompat): ContentInfoCompat {
        val split = contentInfo.partition { item: ClipData.Item -> item.uri != null }
        val uriContent = split.first
        val remaining = split.second
        if (uriContent != null) {
            // App-specific logic to handle the URI(s) in uriContent.
        }
        // Return anything that your app didn't handle. This preserves the
        // default platform behavior for text and anything else that you aren't
        // implementing custom handling for.
        return remaining
    }

    companion object {
        val MIME_TYPES = arrayOf("image/*", "video/*")
    }
}

Java

 public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};

     @Override
     public ContentInfoCompat onReceiveContent(View view, ContentInfoCompat contentInfo) {
         Pair split = contentInfo.partition(
                 item -> item.getUri() != null);
         ContentInfo uriContent = split.first;
         ContentInfo remaining = split.second;
         if (uriContent != null) {
             // App-specific logic to handle the URI(s) in uriContent.
         }
         // Return anything that your app didn't handle. This preserves the
         // default platform behavior for text and anything else that you aren't
         // implementing custom handling for.
         return remaining;
     }
 }

Wenn Ihre App die Freigabe mit Intents bereits unterstützt, können Sie Ihre app-spezifische Logik für die Verarbeitung von Inhalts-URIs. Verbleibende Daten zurückgeben an die Verarbeitung dieser Daten an die Plattform delegieren.

Legen Sie den Listener nach der Implementierung für die entsprechenden UI-Elemente in Ihre App:

Kotlin

class MyActivity : Activity() {
    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        val myInput = findViewById(R.id.my_input)
        ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, MyReceiver())
    }
}

Java

public class MyActivity extends Activity {
     @Override
     public void onCreate(Bundle savedInstanceState) {
         // ...

         AppCompatEditText myInput = findViewById(R.id.my_input);
         ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, new MyReceiver());
     }
}

URI-Berechtigungen

Leseberechtigungen werden von der Plattform automatisch für alle content-URIs im Feld an OnReceiveContentListener übergebene Nutzlast.

Normalerweise verarbeitet Ihre App Inhalts-URIs in einem Dienst oder einer Aktivität. Für lang andauernde Verarbeitung, verwenden Sie WorkManager Wenn Sie die Erweitern Sie die Berechtigungen auf den Zieldienst oder die Zielaktivität, indem Sie den Parameter Inhalte mit Intent.setClipData und Festlegen des Flags FLAG_GRANT_READ_URI_PERMISSION

Alternativ können Sie einen Hintergrundthread im aktuellen Kontext verwenden, um um die Inhalte zu verarbeiten. In diesem Fall müssen Sie einen Verweis auf die payload-Objekt, das vom Listener empfangen wird, um sicherzustellen, dass Berechtigungen nicht von der Plattform frühzeitig widerrufen werden.

Benutzerdefinierte Ansichten

Wenn Ihre App eine benutzerdefinierte abgeleitete View-Klasse verwendet, achten Sie darauf, dass die OnReceiveContentListener wird nicht umgangen.

Wenn Ihre View-Klasse die onCreateInputConnection Jetpack API InputConnectionCompat.createWrapper um InputConnection zu konfigurieren.

Wenn Ihre View-Klasse die onTextContextMenuItem und an Super delegieren, wenn das Menüelement R.id.paste oder R.id.pasteAsPlainText

Vergleich mit der Keyboard Image API

Sie können sich die OnReceiveContentListener API als die nächste Version des vorhandene Keyboard Image API. Diese einheitliche Die API unterstützt die Funktionen der Keyboard Image API sowie einige zusätzliche Funktionen. Die Kompatibilität von Geräten und Funktionen ist abhängig von unabhängig davon, ob Sie die Jetpack-Bibliothek oder die nativen APIs des Android SDK verwenden.

Tabelle 1 Unterstützte Funktionen und API-Ebenen für Jetpack.
Aktion oder Funktion Unterstützt von der Keyboard Image API Von einheitlicher API unterstützt
Über die Tastatur einfügen Ja (API-Level 13 und höher) Ja (API-Level 13 und höher)
Einfügen durch Tippen &Einfügen Menü „Halten“ Nein Ja
Elemente per Drag-and-drop einfügen Nein Ja (API-Level 24 und höher)
Tabelle 2 Unterstützte Funktionen und API-Ebenen für native Anzeigen APIs.
Aktion oder Funktion Unterstützt von der Keyboard Image API Von einheitlicher API unterstützt
Über die Tastatur einfügen Ja (API-Level 25 und höher) Ja (Android 12 und höher)
Einfügen durch Tippen &Einfügen Menü „Halten“ Nein
Elemente per Drag-and-drop einfügen Nein