Ab Android 8.0 (API-Level 26) können Aktivitäten im Bild-im-Bild-Modus (BiB) gestartet werden. Der Bild-im-Bild-Modus ist ein spezieller Multifenstermodus, der hauptsächlich für die Videowiedergabe verwendet wird. Mit der Funktion „Bild im Bild“ können Nutzer sich ein Video in einem kleinen Fenster ansehen, das an einer Ecke des Bildschirms angepinnt ist, während sie zwischen Apps wechseln oder sich Inhalte auf dem Hauptbildschirm ansehen.
Für den BiB-Modus werden die in Android 7.0 eingeführten APIs für den Mehrfenstermodus verwendet, um das Overlayfenster für das angepinnte Video bereitzustellen. Wenn Sie Ihrer App den PiP-Modus hinzufügen möchten, müssen Sie Ihre Aktivitäten, die den PiP-Modus unterstützen, registrieren, Ihre Aktivität bei Bedarf in den PiP-Modus wechseln und dafür sorgen, dass UI-Elemente ausgeblendet werden und die Videowiedergabe fortgesetzt wird, wenn sich die Aktivität im PiP-Modus befindet.
Das BiB-Fenster wird in der obersten Ebene des Bildschirms in einer vom System ausgewählten Ecke angezeigt.
Die Bild-im-Bild-Funktion wird auch auf kompatiblen Android TV OS-Geräten mit Android 14 (API‑Level 34) oder höher unterstützt. Es gibt viele Ähnlichkeiten, aber auch zusätzliche Aspekte, die bei der Verwendung von Bild-im-Bild auf dem Fernseher zu berücksichtigen sind.
So können Nutzer mit dem BiB-Fenster interagieren
Nutzer können das BiB-Fenster an einen anderen Ort ziehen. Ab Android 12 haben Nutzer außerdem folgende Möglichkeiten:
Tippen Sie einmal auf das Fenster, um eine Vollbild-Umschaltfläche, eine Schließen-Schaltfläche, eine Einstellungen-Schaltfläche und benutzerdefinierte Aktionen anzuzeigen, die von Ihrer App bereitgestellt werden (z. B. Wiedergabesteuerelemente).
Doppeltippen Sie auf das Fenster, um zwischen der aktuellen BiB-Größe und der maximalen oder minimalen BiB-Größe zu wechseln. Wenn Sie beispielsweise auf ein maximiertes Fenster doppeltippen, wird es minimiert. Das Gegenteil ist ebenfalls möglich.
Sie können das Fenster verbergen, indem Sie es an den linken oder rechten Rand ziehen. Wenn Sie das Fenster wiederherstellen möchten, tippen Sie entweder auf den sichtbaren Teil des minimierten Fensters oder ziehen Sie es heraus.
Passen Sie die Größe des BiB-Fensters durch Auseinander- und Zusammenziehen an.
Ihre App steuert, wann die aktuelle Aktivität in den PiP-Modus wechselt. Hier einige Beispiele:
Eine Aktivität kann in den BiB-Modus wechseln, wenn der Nutzer auf den Home-Button tippt oder nach oben zum Home-Bildschirm wischt. So kann Google Maps weiterhin Wegbeschreibungen anzeigen, während der Nutzer gleichzeitig eine andere Aktivität ausführt.
Deine App kann ein Video in den BiB-Modus verschieben, wenn der Nutzer vom Video zurückkehrt, um andere Inhalte zu suchen.
Ihre App kann ein Video in den BiB-Modus wechseln, während ein Nutzer das Ende einer Folge ansieht. Auf dem Hauptbildschirm werden Werbe- oder Zusammenfassungsinformationen zur nächsten Folge der Serie angezeigt.
Ihre App kann Nutzern die Möglichkeit bieten, zusätzliche Inhalte in die Warteschlange zu stellen, während sie sich ein Video ansehen. Das Video wird im BiB-Modus weiter abgespielt, während auf dem Hauptbildschirm eine Aktivität zur Auswahl von Inhalten angezeigt wird.
BiB-Unterstützung deklarieren
Standardmäßig unterstützt das System PiP für Apps nicht automatisch. Wenn du die Bild-im-Bild-Funktion in deiner App unterstützen möchtest, registriere deine Videoaktivität in deinem Manifest, indem du android:supportsPictureInPicture
auf true
festlegst. Geben Sie außerdem an, dass Ihre Aktivität Änderungen an der Layoutkonfiguration verarbeitet, damit sie nicht neu gestartet wird, wenn während der Übergänge in den PiP-Modus Layoutänderungen auftreten.
<activity android:name="VideoActivity"
android:supportsPictureInPicture="true"
android:configChanges=
"screenSize|smallestScreenSize|screenLayout|orientation"
...
Aktivität in den Bild-im-Bild-Modus wechseln
Ab Android 12 können Sie Ihre Aktivität in den BiB-Modus versetzen, indem Sie das Flag setAutoEnterEnabled
auf true
setzen. Mit dieser Einstellung wird eine Aktivität bei Bedarf automatisch in den BiB-Modus versetzt, ohne dass enterPictureInPictureMode()
in onUserLeaveHint
explizit aufgerufen werden muss. Das hat den zusätzlichen Vorteil, dass die Übergänge viel flüssiger sind. Weitere Informationen finden Sie unter Übergänge in den BiB-Modus bei der Gestennavigation optimieren.
Wenn Sie Android 11 oder niedriger als Zielgruppe haben, muss eine Aktivität enterPictureInPictureMode()
aufrufen, um in den BiB-Modus zu wechseln. Mit dem folgenden Code wird beispielsweise eine Aktivität in den BiB-Modus versetzt, wenn der Nutzer in der Benutzeroberfläche der App auf eine entsprechende Schaltfläche klickt:
Kotlin
override fun onActionClicked(action: Action) { if (action.id.toInt() == R.id.lb_control_picture_in_picture) { activity?.enterPictureInPictureMode() return } }
Java
@Override public void onActionClicked(Action action) { if (action.getId() == R.id.lb_control_picture_in_picture) { getActivity().enterPictureInPictureMode(); return; } ... }
Möglicherweise möchten Sie Logik einfügen, die eine Aktivität in den BiB-Modus schaltet, anstatt sie in den Hintergrund zu verschieben. Google Maps wechselt beispielsweise in den BiB-Modus, wenn der Nutzer die Startbildschirm- oder die Taste für zuletzt verwendete Apps drückt, während die App eine Navigation durchführt. Sie können diesen Fall abfangen, indem Sie onUserLeaveHint()
überschreiben:
Kotlin
override fun onUserLeaveHint() { if (iWantToBeInPipModeNow()) { enterPictureInPictureMode() } }
Java
@Override public void onUserLeaveHint () { if (iWantToBeInPipModeNow()) { enterPictureInPictureMode(); } }
Empfohlen: Nutzern einen reibungslosen PiP-Übergang bieten
In Android 12 wurden die animierten Übergänge zwischen Vollbild- und BiB-Fenstern deutlich verbessert. Wir empfehlen dringend, alle anwendbaren Änderungen zu implementieren. Sobald Sie dies getan haben, werden diese Änderungen automatisch auf große Bildschirme wie Falt-Smartphones und Tablets skaliert, ohne dass weitere Maßnahmen erforderlich sind.
Wenn Ihre App keine entsprechenden Updates enthält, funktionieren PiP-Übergänge weiterhin, die Animationen sind jedoch weniger ausgereift. Wenn Sie beispielsweise vom Vollbild- in den BiB-Modus wechseln, kann es passieren, dass das BiB-Fenster während des Übergangs verschwindet, bevor es nach Abschluss des Übergangs wieder angezeigt wird.
Diese Änderungen umfassen Folgendes:
- Übergänge in den BiB-Modus bei der Bedienung über Gesten optimiert
- Geeignete
sourceRectHint
für den Wechsel in den und aus dem BiB-Modus festlegen - Nahtlose Größenanpassung für Inhalte, die keine Videos sind, deaktivieren
Im Android-Kotlin-Beispiel für den Bild-im-Bild-Modus finden Sie Informationen dazu, wie Sie einen reibungslosen Übergang ermöglichen.
Übergänge in den BiB-Modus bei der Bedienung über Gesten flüssiger gestalten
Ab Android 12 sorgt das Flag setAutoEnterEnabled
für eine viel flüssigere Animation beim Übergang zu Videoinhalten im BiB-Modus mit Gestensteuerung, z. B. beim Hochwischen vom Vollbildmodus zum Startbildschirm.
Führen Sie die folgenden Schritte aus, um diese Änderung vorzunehmen. Hier finden Sie ein Beispiel:
Verwenden Sie
setAutoEnterEnabled
, umPictureInPictureParams.Builder
zu erstellen:Kotlin
setPictureInPictureParams(PictureInPictureParams.Builder() .setAspectRatio(aspectRatio) .setSourceRectHint(sourceRectHint) .setAutoEnterEnabled(true) .build())
Java
setPictureInPictureParams(new PictureInPictureParams.Builder() .setAspectRatio(aspectRatio) .setSourceRectHint(sourceRectHint) .setAutoEnterEnabled(true) .build());
Rufe
setPictureInPictureParams
mit dem aktuellenPictureInPictureParams
frühzeitig an. Die App wartet nicht auf denonUserLeaveHint
-Callback (wie in Android 11).Beispiel: Sie möchten
setPictureInPictureParams
beim ersten Abspielen und bei jedem weiteren Abspielen aufrufen, wenn sich das Seitenverhältnis ändert.Rufen Sie
setAutoEnterEnabled(false)
nur an, wenn es nötig ist. Beispiel: Du möchtest wahrscheinlich nicht in den BiB-Modus wechseln, wenn die aktuelle Wiedergabe pausiert ist.
Geeigneten sourceRectHint
für den Wechsel in den und aus dem BiB-Modus festlegen
Seit der Einführung von BiB in Android 8.0 gibt setSourceRectHint
den Bereich der Aktivität an, der nach dem Übergang in den Bild-im-Bild-Modus sichtbar ist, z. B. die Grenzen der Videoansicht in einem Videoplayer.
Unter Android 12 verwendet das System sourceRectHint
, um sowohl beim Aufrufen als auch beim Beenden des BiB-Modus eine viel flüssigere Animation zu implementieren.
So legen Sie sourceRectHint
für den Wechsel in den und aus dem BiB-Modus richtig fest:
Konstruieren Sie
PictureInPictureParams
mit den richtigen Grenzen alssourceRectHint
. Wir empfehlen, dem Videoplayer auch einen Listener für Layoutänderungen anzuhängen:Kotlin
val mOnLayoutChangeListener = OnLayoutChangeListener { v: View?, oldLeft: Int, oldTop: Int, oldRight: Int, oldBottom: Int, newLeft: Int, newTop: Int, newRight: Int, newBottom: Int -> val sourceRectHint = Rect() mYourVideoView.getGlobalVisibleRect(sourceRectHint) val builder = PictureInPictureParams.Builder() .setSourceRectHint(sourceRectHint) setPictureInPictureParams(builder.build()) } mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener)
Java
private final View.OnLayoutChangeListener mOnLayoutChangeListener = (v, oldLeft, oldTop, oldRight, oldBottom, newLeft, newTop, newRight, newBottom) -> { final Rect sourceRectHint = new Rect(); mYourVideoView.getGlobalVisibleRect(sourceRectHint); final PictureInPictureParams.Builder builder = new PictureInPictureParams.Builder() .setSourceRectHint(sourceRectHint); setPictureInPictureParams(builder.build()); }; mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener);
Aktualisieren Sie bei Bedarf die
sourceRectHint
, bevor das System mit dem Übergang zum Beenden beginnt. Wenn das System den BiB-Modus beendet, wird die View-Hierarchie der Aktivität entsprechend der Zielkonfiguration (z. B. Vollbild) angeordnet. Die App kann einen Listener für Layoutänderungen an die Root-Ansicht oder die Zielansicht (z. B. die Videoplayer-Ansicht) anhängen, um das Ereignis zu erkennen undsourceRectHint
vor Beginn der Animation zu aktualisieren.Kotlin
// Listener is called immediately after the user exits PiP but before animating. playerView.addOnLayoutChangeListener { _, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom -> if (left != oldLeft || right != oldRight || top != oldTop || bottom != oldBottom) { // The playerView's bounds changed, update the source hint rect to // reflect its new bounds. val sourceRectHint = Rect() playerView.getGlobalVisibleRect(sourceRectHint) setPictureInPictureParams( PictureInPictureParams.Builder() .setSourceRectHint(sourceRectHint) .build() ) } }
Java
// Listener is called right after the user exits PiP but before animating. playerView.addOnLayoutChangeListener((v, left, top, right, bottom, oldLeft, oldTop, oldRight, oldBottom) -> { if (left != oldLeft || right != oldRight || top != oldTop || bottom != oldBottom) { // The playerView's bounds changed, update the source hint rect to // reflect its new bounds. final Rect sourceRectHint = new Rect(); playerView.getGlobalVisibleRect(sourceRectHint); setPictureInPictureParams( new PictureInPictureParams.Builder() .setSourceRectHint(sourceRectHint) .build()); } });
Nahtloses Anpassen der Größe für Inhalte, die keine Videos sind, deaktivieren
In Android 12 wurde das Flag setSeamlessResizeEnabled
eingeführt, das eine viel flüssigere Überblendungsanimation beim Anpassen der Größe von Nicht-Videoinhalten im BiB-Fenster ermöglicht. Bisher konnte es beim Anpassen der Größe von Nicht-Videoinhalten in einem BiB-Fenster zu störenden visuellen Artefakten kommen.
So aktivieren Sie die nahtlose Größenanpassung für Videoinhalte:
Kotlin
setPictureInPictureParams(PictureInPictureParams.Builder() .setSeamlessResizeEnabled(true) .build())
Java
setPictureInPictureParams(new PictureInPictureParams.Builder() .setSeamlessResizeEnabled(true) .build());
Benutzeroberfläche während der Bild-im-Bild-Wiedergabe verarbeiten
Wenn die Aktivität in den BiB-Modus (Bild im Bild) wechselt oder diesen verlässt, ruft das System Activity.onPictureInPictureModeChanged()
oder Fragment.onPictureInPictureModeChanged()
auf.
In Android 15 wurden Änderungen eingeführt, die für einen noch reibungsloseren Übergang beim Wechsel in den BiB-Modus sorgen. Das ist nützlich für Apps, deren Haupt-UI in den PiP-Modus wechselt und über die UI-Elemente gelegt werden.
Entwickler verwenden den onPictureInPictureModeChanged()
-Callback, um Logik zu definieren, mit der die Sichtbarkeit der überlagerten UI-Elemente umgeschaltet wird.
Dieser Callback wird ausgelöst, wenn die Animation für den PiP-Modus abgeschlossen ist.
Ab Android 15 enthält die Klasse PictureInPictureUiState
einen neuen Status.
Bei diesem neuen UI-Status wird für Apps, die auf Android 15 ausgerichtet sind, der Activity#onPictureInPictureUiStateChanged()
-Callback mit isTransitioningToPip()
aufgerufen, sobald die BiB-Animation beginnt.
Viele UI-Elemente sind für die App im BiB-Modus nicht relevant, z. B. Ansichten oder Layouts mit Informationen wie Vorschlägen, dem nächsten Video, Bewertungen und Titeln. Wenn die App in den BiB-Modus wechselt, verwenden Sie den onPictureInPictureUiStateChanged()
-Callback, um diese UI-Elemente auszublenden. Wenn die App vom BiB-Fenster in den Vollbildmodus wechselt, verwenden Sie den onPictureInPictureModeChanged()
-Callback, um diese Elemente wieder einzublenden, wie in den folgenden Beispielen gezeigt:
Kotlin
override fun onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) { if (pipState.isTransitioningToPip()) { // Hide UI elements. } }
Java
@Override public void onPictureInPictureUiStateChanged(PictureInPictureUiState pipState) { if (pipState.isTransitioningToPip()) { // Hide UI elements. } }
Kotlin
override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean) { if (isInPictureInPictureMode) { // Unhide UI elements. } }
Java
@Override public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) { if (isInPictureInPictureMode) { // Unhide UI elements. } }
Durch das schnelle Ein- und Ausblenden irrelevanter UI-Elemente (für ein BiB-Fenster) wird eine flüssigere und flimmerfreie BiB-Eingangsanimation ermöglicht.
Überschreiben Sie diese Callbacks, um die UI-Elemente der Aktivität neu zu zeichnen. Im BiB-Modus wird Ihre Aktivität in einem kleinen Fenster angezeigt. Nutzer können nicht mit den UI-Elementen Ihrer App interagieren, wenn sich die App im BiB-Modus befindet. Außerdem sind die Details kleiner UI-Elemente möglicherweise schwer zu erkennen. Video-Wiedergabeaktivitäten mit minimaler Benutzeroberfläche bieten die beste Nutzererfahrung.
Wenn Ihre App benutzerdefinierte Aktionen für den BiB-Modus bereitstellen muss, lesen Sie den Abschnitt Steuerelemente hinzufügen auf dieser Seite. Entfernen Sie andere UI-Elemente, bevor Ihre Aktivität in den BiB-Modus wechselt, und stellen Sie sie wieder her, wenn Ihre Aktivität wieder im Vollbildmodus angezeigt wird.
Steuerelemente hinzufügen
Im BiB-Fenster können Steuerelemente angezeigt werden, wenn der Nutzer das Menü des Fensters öffnet (indem er auf einem Mobilgerät auf das Fenster tippt oder das Menü über die TV-Fernbedienung auswählt).
Wenn eine App eine aktive Mediensitzung hat, werden die Steuerelemente „Wiedergabe“, „Pause“, „Weiter“ und „Zurück“ angezeigt.
Sie können benutzerdefinierte Aktionen auch explizit angeben, indem Sie PictureInPictureParams
mit PictureInPictureParams.Builder.setActions()
erstellen, bevor Sie in den BiB-Modus wechseln, und die Parameter übergeben, wenn Sie mit enterPictureInPictureMode(android.app.PictureInPictureParams)
oder setPictureInPictureParams(android.app.PictureInPictureParams)
in den BiB-Modus wechseln.
Sei vorsichtig. Wenn Sie versuchen, mehr als getMaxNumPictureInPictureActions()
hinzuzufügen, wird nur die maximale Anzahl hinzugefügt.
Videowiedergabe im BiB-Modus fortsetzen
Wenn Ihre Aktivität in den BiB-Modus wechselt, wird sie vom System pausiert und die Methode onPause()
der Aktivität wird aufgerufen. Die Videowiedergabe sollte nicht pausiert werden, sondern weiterlaufen, wenn die Aktivität beim Übergang in den BiB-Modus pausiert wird.
In Android 7.0 und höher sollten Sie die Videowiedergabe pausieren und fortsetzen, wenn das System die Methoden onStop()
und onStart()
Ihrer Aktivität aufruft. So müssen Sie nicht prüfen, ob sich Ihre App im PiP-Modus befindet, und die Wiedergabe nicht explizit fortsetzen.onPause()
Wenn Sie das Flag setAutoEnterEnabled
nicht auf true
gesetzt haben und die Wiedergabe in Ihrer onPause()
-Implementierung pausieren müssen, rufen Sie isInPictureInPictureMode()
auf, um den BiB-Modus zu prüfen, und passen Sie die Wiedergabe entsprechend an. Beispiel:
Kotlin
override fun onPause() { super.onPause() // If called while in PiP mode, do not pause playback. if (isInPictureInPictureMode) { // Continue playback. } else { // Use existing playback logic for paused activity behavior. } }
Java
@Override public void onPause() { // If called while in PiP mode, do not pause playback. if (isInPictureInPictureMode()) { // Continue playback. ... } else { // Use existing playback logic for paused activity behavior. ... } }
Wenn Ihre Aktivität aus dem BiB-Modus zurück in den Vollbildmodus wechselt, wird sie vom System fortgesetzt und Ihre onResume()
-Methode wird aufgerufen.
Einzelne Wiedergabeaktivität für BiB verwenden
In Ihrer App wählt ein Nutzer möglicherweise ein neues Video aus, während er auf dem Hauptbildschirm nach Inhalten sucht und die Videowiedergabe im BiB-Modus läuft. Spiele das neue Video im Vollbildmodus in der vorhandenen Wiedergabeaktivität ab, anstatt eine neue Aktivität zu starten, die den Nutzer verwirren könnte.
Damit für Videowiedergabeanfragen eine einzelne Aktivität verwendet wird und bei Bedarf in den BiB-Modus gewechselt wird oder der BiB-Modus beendet wird, legen Sie android:launchMode
der Aktivität in Ihrem Manifest auf singleTask
fest:
<activity android:name="VideoActivity"
...
android:supportsPictureInPicture="true"
android:launchMode="singleTask"
...
Überschreibe in deinen Aktivitäten onNewIntent()
und verarbeite das neue Video. Beende bei Bedarf die Wiedergabe des aktuellen Videos.
Best Practices
Auf Geräten mit wenig RAM ist die Bild-im-Bild-Funktion möglicherweise deaktiviert. Bevor deine App den BiB-Modus verwendet, solltest du mit dem Aufruf von hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE)
prüfen, ob er verfügbar ist.
Der BiB-Modus ist für Aktivitäten vorgesehen, bei denen Videos im Vollbildmodus abgespielt werden. Wenn Sie Ihre Aktivität in den BiB-Modus wechseln, sollten Sie nur Videoinhalte anzeigen. Verfolge, wann deine Aktivität in den BiB-Modus wechselt, und blende UI-Elemente aus, wie unter UI im BiB-Modus verarbeiten beschrieben.
Wenn sich eine Aktivität im BiB-Modus befindet, erhält sie standardmäßig keinen Eingabefokus. Wenn Sie Eingabeereignisse im BiB-Modus empfangen möchten, verwenden Sie MediaSession.setCallback()
.
Weitere Informationen zur Verwendung von setCallback()
finden Sie unter Now Playing-Card anzeigen.
Wenn sich Ihre App im BiB-Modus befindet, kann die Videowiedergabe im BiB-Fenster zu Audio-Interferenzen mit einer anderen App führen, z. B. einer Musikplayer-App oder einer Sprachsuch-App. Um dies zu vermeiden, fordern Sie den Audiofokus an, wenn Sie die Videowiedergabe starten, und verarbeiten Sie Benachrichtigungen über Änderungen des Audiofokus, wie unter Audiofokus verwalten beschrieben. Wenn Sie im BiB-Modus eine Benachrichtigung über den Verlust des Audiofokus erhalten, pausieren oder beenden Sie die Videowiedergabe.
Wenn Ihre App in den PiP-Modus wechselt, wird nur die oberste Aktivität im Bild-im-Bild-Modus angezeigt. In einigen Situationen, z. B. auf Geräten mit mehreren Fenstern, kann es sein, dass die Aktivität unten jetzt angezeigt wird und neben der PiP-Aktivität wieder sichtbar ist. Sie sollten diesen Fall entsprechend bearbeiten. Das gilt auch für die Aktivität unten, bei der ein onResume()
- oder onPause()
-Callback erfolgt. Es ist auch möglich, dass der Nutzer mit der Aktivität interagiert. Wenn beispielsweise eine Videolistenaktivität und die Aktivität des wiedergegebenen Videos im BiB-Modus angezeigt werden, kann der Nutzer ein neues Video aus der Liste auswählen. Die BiB-Aktivität sollte dann entsprechend aktualisiert werden.
Zusätzlicher Beispielcode
Eine in Kotlin geschriebene Beispiel-App finden Sie unter Android PictureInPicture Sample (Kotlin).