Umfassende Inhalte erhalten

Nutzer mögen Bilder, Videos und andere ausdrucksstarke Inhalte. Das Einfügen und Verschieben dieser Inhalte in Apps ist jedoch nicht immer einfach. In Android 12 (API-Level 31) wird eine einheitliche API eingeführt, mit der Ihre App Inhalte aus beliebigen Quellen – aus der Zwischenablage, über die Tastatur oder durch Ziehen – akzeptieren kann, um Apps das Empfangen von Rich Content zu erleichtern.

Sie können eine Schnittstelle wie OnReceiveContentListener an UI-Komponenten anhängen und einen Callback erhalten, wenn Inhalte mit einem beliebigen Mechanismus eingefügt werden. Der Callback wird der einzige Ort, an dem Ihr Code den Empfang aller Inhalte verarbeitet, 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 ab Core 1.7 und Appcompat 1.4 verfügbar. Wir empfehlen die Verwendung bei der Implementierung dieser Funktion.

Übersicht

Bei anderen vorhandenen APIs verfügt jeder UI-Mechanismus, z. B. das Menü zum Berühren und Halten oder das Ziehen, über eine eigene entsprechende API. Dies bedeutet, dass Sie die Integration in jede API separat vornehmen müssen und für jeden Mechanismus, der Inhalte einfügt, ähnlichen Code hinzufügen müssen:

Die OnReceiveContentListener API konsolidiert diese verschiedenen Codepfade, indem sie eine einzige zu implementierende API erstellt. So können Sie sich auf Ihre anwendungsspezifische Logik konzentrieren und der Plattform den Rest überlassen:

Dieser Ansatz bedeutet auch, dass du keine zusätzlichen Codeänderungen vornehmen musst, wenn die Plattform neue Möglichkeiten zum Einfügen von Inhalten bietet. Wenn deine App eine vollständige Anpassung für einen bestimmten Anwendungsfall implementieren muss, kannst du weiterhin die vorhandenen APIs verwenden, die weiterhin auf dieselbe Weise funktionieren.

Implementierung

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

Implementieren Sie den Listener zur Verwendung der API. Geben Sie dazu an, welche Inhaltstypen Ihre Anwendung verarbeiten kann:

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

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 den Rest des Listeners:

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/*")
    }
}

 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 für Intents bereits unterstützt, können Sie Ihre anwendungsspezifische Logik für die Verarbeitung von Inhalts-URIs wiederverwenden. Geben Sie alle verbleibenden Daten zurück, um die Verarbeitung dieser Daten an die Plattform zu delegieren.

Nachdem Sie den Listener implementiert haben, legen Sie ihn für die entsprechenden UI-Elemente in Ihrer App fest:

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

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 Inhalts-URIs in der Nutzlast gewährt und freigegeben, die an OnReceiveContentListener übergeben wird.

Normalerweise verarbeitet Ihre App Inhalts-URIs in einem Dienst oder einer Aktivität. Für eine Verarbeitung über einen längeren Zeitraum verwenden Sie WorkManager. Erweitern Sie bei der Implementierung die Berechtigungen auf den Zieldienst oder die Zielaktivität, indem Sie den Inhalt mit Intent.setClipData übergeben und das Flag FLAG_GRANT_READ_URI_PERMISSION festlegen.

Alternativ können Sie im aktuellen Kontext einen Hintergrundthread verwenden, um den Inhalt zu verarbeiten. In diesem Fall müssen Sie einen Verweis auf das payload-Objekt beibehalten, das der Listener empfangen hat, damit Berechtigungen nicht vorzeitig von der Plattform widerrufen werden.

Benutzerdefinierte Ansichten

Wenn Ihre Anwendung eine benutzerdefinierte abgeleitete View-Klasse verwendet, dürfen die OnReceiveContentListener nicht umgangen werden.

Wenn Ihre View-Klasse die Methode onCreateInputConnection überschreibt, verwenden Sie die Jetpack API InputConnectionCompat.createWrapper, um InputConnection zu konfigurieren.

Wenn Ihre View-Klasse die Methode onTextContextMenuItem überschreibt, delegieren Sie die Funktion für Super, wenn der Menüpunkt R.id.paste oder R.id.pasteAsPlainText lautet.

Vergleich mit der Keyboard Image API

Sie können sich die OnReceiveContentListener API als die nächste Version der vorhandenen Keyboard Image API vorstellen. Diese einheitliche API unterstützt die Funktionalität der Keyboard Image API sowie einige zusätzliche Funktionen. Die Kompatibilität von Geräten und Funktionen hängt davon ab, ob Sie die Jetpack-Bibliothek oder die nativen APIs aus dem Android SDK verwenden.