Nutzer lieben Bilder, Videos und andere ausdrucksstarke Inhalte. Das Einfügen und Verschieben dieser Inhalte in Apps ist jedoch nicht immer einfach. Damit Apps Rich-Inhalte einfacher empfangen können, wird in Android 12 (API-Level 31) eine einheitliche API eingeführt, mit der Ihre App Inhalte aus jeder Quelle akzeptieren kann: Zwischenablage, Tastatur oder Ziehen.
Sie können eine Benutzeroberfläche wie OnReceiveContentListener an UI-Komponenten anhängen und einen Rückruf erhalten, wenn Inhalte über einen beliebigen Mechanismus eingefügt werden. Der Rückruf ist der einzige Ort, an dem Ihr Code den Empfang aller Inhalte verarbeiten kann, von einfachem und formatiertem Text über Markup, Bilder, Videos, Audiodateien und mehr.
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. Wir empfehlen, diese Versionen bei der Implementierung dieser Funktion zu verwenden.
Übersicht
Bei anderen vorhandenen APIs hat jeder UI-Mechanismus – z. B. das Menü „Berühren und halten“ oder das Ziehen – eine eigene entsprechende API. Das bedeutet, dass Sie jede API separat einbinden und für jeden Mechanismus, mit dem Inhalte eingefügt werden, ähnlichen Code hinzufügen müssen:
Die OnReceiveContentListener API konsolidiert diese verschiedenen Codepfade, indem eine einzige API implementiert wird. So können Sie sich auf Ihre appspezifische Logik konzentrieren und die Plattform erledigt den Rest:
Dieser Ansatz bedeutet auch, dass Sie keine zusätzlichen Codeänderungen vornehmen müssen, wenn der Plattform neue Möglichkeiten zum Einfügen von Inhalten hinzugefügt werden, um die Unterstützung in Ihrer App zu aktivieren. Wenn in Ihrer App für einen bestimmten Anwendungsfall eine vollständige Anpassung implementiert werden muss, können Sie weiterhin die vorhandenen APIs verwenden, die weiterhin auf dieselbe Weise funktionieren.
Implementierung
Die API ist eine Listener-Schnittstelle mit einer einzigen Methode, OnReceiveContentListener.
Für die Unterstützung älterer Versionen der Android-Plattform empfehlen wir die Verwendung der entsprechenden OnReceiveContentListener-Schnittstelle in der AndroidX Core Library.
Wenn Sie die API verwenden möchten, implementieren Sie den Listener, indem Sie angeben, welche Arten von Inhalten Ihre App verarbeiten kann:
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 MIME-Typen für Inhalte angegeben haben, die von Ihrer App unterstützt werden, implementieren Sie 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<ContentInfoCompat, ContentInfoCompat> 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 Content-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 auf die entsprechenden UI-Elemente in Ihrer App fest:
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 Inhalts-URIs in der an die OnReceiveContentListener übergebenen Nutzlast gewährt und freigegeben.
Normalerweise verarbeitet Ihre App Inhalts-URIs in einem Dienst oder einer Aktivität. Verwenden Sie für lang andauernde Verarbeitungen WorkManager. Wenn Sie diese Funktion implementieren, erweitern Sie die Berechtigungen auf den Zieldienst oder die Zielaktivität, indem Sie die Inhalte mit Intent.setClipData übergeben und das Flag FLAG_GRANT_READ_URI_PERMISSION setzen.
Alternativ können Sie einen Hintergrund-Thread im aktuellen Kontext verwenden, um die Inhalte zu verarbeiten. In diesem Fall musst du einen Verweis auf das vom Listener empfangene payload-Objekt beibehalten, damit die Berechtigungen nicht vorzeitig von der Plattform widerrufen werden.
Benutzerdefinierte Ansichten
Wenn Ihre App eine benutzerdefinierte View-Unterklasse verwendet, achten Sie darauf, dass die OnReceiveContentListener nicht umgangen wird.
Wenn die View-Klasse die Methode onCreateInputConnection überschreibt, verwenden Sie die Jetpack API InputConnectionCompat.createWrapper, um die InputConnection zu konfigurieren.
Wenn die View-Klasse die Methode onTextContextMenuItem überschreibt, delegieren Sie an super, wenn das Menüelement R.id.paste oder R.id.pasteAsPlainText ist.
Vergleich mit der Keyboard Image API
Die OnReceiveContentListener API ist die nächste Version der bestehenden Tastaturbild-API. Diese einheitliche API unterstützt die Funktionen der Keyboard Image API sowie einige zusätzliche Funktionen. Die Geräte- und Funktionskompatibilität hängt davon ab, ob Sie die Jetpack-Bibliothek oder die nativen APIs aus dem Android SDK verwenden.
| Aktion oder Funktion | Von der Keyboard Image API unterstützt | Von der einheitlichen API unterstützt |
|---|---|---|
| Über die Tastatur einfügen | Ja (API-Level 13 und höher) | Ja (API-Level 13 und höher) |
| Einfügen über das Menü „Berühren und halten“ | Nein | Ja |
| Per Drag-and-drop einfügen | Nein | Ja (API-Level 24 und höher) |
| Aktion oder Funktion | Von der Keyboard Image API unterstützt | Von der einheitlichen API unterstützt |
|---|---|---|
| Über die Tastatur einfügen | Ja (API-Level 25 und höher) | Ja (Android 12 und höher) |
| Einfügen über das Menü „Berühren und halten“ | Nein | |
| Per Drag-and-drop einfügen | Nein |