Diese Seite wurde von der Cloud Translation API übersetzt.

Videos mit Bild im Bild (BiB) hinzufügen

Ab Android 8.0 (API-Level 26) können Aktivitäten in Android im Bild-im-Bild-Modus (BiB) gestartet werden. BiB ist ein spezieller Mehrfenstermodus, der hauptsächlich für die Videowiedergabe verwendet wird. Nutzer können sich ein Video in einem kleinen Fenster ansehen, das in einer Ecke des Bildschirms angepinnt ist, während sie zwischen Apps wechseln oder Inhalte auf dem Hauptbildschirm durchsuchen.

BiB nutzt die in Android 7.0 verfügbaren Mehrfenster-APIs, um das angepinnte Video-Overlay-Fenster bereitzustellen. Wenn du BiB in deine App aufnehmen möchtest, musst du alle Aktivitäten registrieren, die BiB unterstützen. Außerdem musst du deine Aktivität nach Bedarf in den BiB-Modus wechseln. Außerdem müssen UI-Elemente ausgeblendet sein und die Videowiedergabe fortgesetzt werden, wenn die Aktivität im BiB-Modus ist.

Das BiB-Fenster wird in der obersten Ebene des Bildschirms in einer vom System ausgewählten Ecke angezeigt.

So können Nutzer mit dem BiB-Fenster interagieren

Nutzer können das BiB-Fenster an eine andere Stelle ziehen. Ab Android 12 können Nutzer außerdem:

Tippen Sie einmal auf das Fenster, um eine Ein/Aus-Schaltfläche für den Vollbildmodus, eine Schließen-Schaltfläche, eine Schaltfläche für Einstellungen und benutzerdefinierte Aktionen Ihrer App (z. B. Wiedergabesteuerung) aufzurufen.
Tippe doppelt auf das Fenster, um zwischen der aktuellen BiB-Größe und der maximalen oder minimalen BiB-Größe zu wechseln. Wenn du beispielsweise doppelt auf ein maximiertes Fenster tippst, wird es minimiert und umgekehrt.
Verstecken Sie das Fenster, indem Sie es zum linken oder rechten Rand ziehen. Wenn Sie das Fenster entriegeln möchten, tippen Sie entweder auf den sichtbaren Teil des verschobenen Fensters oder ziehen Sie es aus dem Fenster.
Sie können die Größe des BiB-Fensters durch Auseinander- und Zusammenziehen der Finger anpassen.

Deine App legt fest, wann die aktuelle Aktivität in den BiB-Modus wechselt. Hier einige Beispiele:

BiB-Modus kann aktiviert werden, wenn der Nutzer auf die Startbildschirmtaste tippt oder nach oben wischt. So werden Wegbeschreibungen in Google Maps weiterhin angezeigt, während der Nutzer eine andere Aktivität ausführt.
Deine App kann ein Video in den BiB-Modus versetzen, wenn der Nutzer vom Video zurückkehrt, um sich andere Inhalte anzusehen.
Deine App kann ein Video in den BiB-Modus versetzen, während sich ein Nutzer das Ende einer Episode ansieht. Auf dem Hauptbildschirm werden Werbe- oder Zusammenfassungsinformationen zur nächsten Folge der Serie angezeigt.
Deine App bietet Nutzern die Möglichkeit, zusätzliche Inhalte in die Wiedergabeliste zu stellen, während sie ein Video ansehen. Das Video wird im BiB-Modus weiter abgespielt, während auf dem Hauptbildschirm eine Aktivität zur Inhaltsauswahl angezeigt wird.

BiB-Unterstützung deklarieren

BiB wird für Apps standardmäßig nicht automatisch unterstützt. Wenn du BiB in deiner App unterstützen möchtest, registriere deine Videoaktivität in deinem Manifest. Setze dazu android:supportsPictureInPicture auf true. Geben Sie außerdem an, dass Ihre Aktivität Änderungen der Layoutkonfiguration verarbeitet, damit Ihre Aktivität nicht neu gestartet wird, wenn Layoutänderungen während des BiB-Moduswechsels auftreten.

<activity android:name="VideoActivity"
    android:supportsPictureInPicture="true"
    android:configChanges=
        "screenSize|smallestScreenSize|screenLayout|orientation"
    ...

Aktivitäten auf BiB umstellen

Ab Android 12 können Sie Ihre Aktivität in den BiB-Modus wechseln, indem Sie das Flag setAutoEnterEnabled auf true setzen. Mit dieser Einstellung wird bei Bedarf automatisch in den BiB-Modus gewechselt, ohne dass enterPictureInPictureMode() in onUserLeaveHint explizit aufgerufen werden muss. Außerdem bietet dies den zusätzlichen Vorteil, dass die Übergänge viel reibungsloser sind. Weitere Informationen

Wenn deine App auf Android 11 oder niedriger ausgerichtet ist, 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 auf eine dedizierte Schaltfläche in der Benutzeroberfläche der App 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 eine Logik einbinden, die eine Aktivität in den BiB-Modus wechselt, anstatt in den Hintergrund zu gehen. So wechselt Google Maps beispielsweise in den BiB-Modus, wenn der Nutzer während der Navigation auf die Schaltfläche „Startseite“ oder „Letzte“ drückt. Sie können diesen Fall umgehen, indem Sie onUserLeaveHint() überschreiben:

Kotlin

override fun onUserLeaveHint() {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode()
    }
}

Java

@Override
public void onUserLeaveHint () {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode();
    }
}

Empfohlen: Nutzern eine optimierte BiB-Umstellung ermöglichen

Unter Android 12 wurden die animierten Übergänge zwischen Vollbild- und BiB-Fenstern erheblich verbessert. Wir empfehlen dringend, alle entsprechenden Änderungen zu implementieren. Danach werden diese Änderungen automatisch auf große Bildschirme wie faltbare Smartphones und Tablets skaliert, ohne dass weitere Maßnahmen erforderlich sind.

Wenn deine App keine entsprechenden Updates enthält, funktionieren BiB-Übergänge weiterhin, die Animationen sind jedoch weniger ausgefeilt. Wenn du beispielsweise vom Vollbildmodus zum BiB-Modus übergehst, kann das BiB-Fenster während des Übergangs ausgeblendet werden, bevor es wieder eingeblendet wird, wenn der Übergang abgeschlossen ist.

Diese Änderungen umfassen Folgendes:

Einfacherer Wechsel in den BiB-Modus durch Bedienung über Gesten
Korrekten sourceRectHint zum Starten und Beenden des BiB-Modus festlegen
Nahtlose Größenanpassung für Inhalte, die keine Videos sind, deaktivieren

Wie Sie eine ausgefeilte Umstellung ermöglichen, können Sie dem Beispiel „PictureInPicture“ für Android entnehmen.

Einfacherer Wechsel in den BiB-Modus durch Bedienung über Gesten

Ab Android 12 bietet das Flag setAutoEnterEnabled viel flüssigere Animationen für den Wechsel zu Videoinhalten im BiB-Modus über die Gestensteuerung, z. B. wenn vom Vollbildmodus nach oben zum Startbildschirm wischt.

Führe die folgenden Schritte aus, um diese Änderung vorzunehmen. Orientiere dich dabei an diesem Beispiel:

Verwenden Sie setAutoEnterEnabled, um PictureInPictureParams.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 der aktuellen PictureInPictureParams frühzeitig an. Die App wartet nicht auf den onUserLeaveHint-Callback, wie es bei Android 11 der Fall gewesen wäre.

Du kannst beispielsweise setPictureInPictureParams bei der allerersten Wiedergabe und bei jeder darauffolgenden Wiedergabe aufrufen, wenn sich das Seitenverhältnis ändert.
Rufen Sie setAutoEnterEnabled(false) nur bei Bedarf auf. Wenn die aktuelle Wiedergabe beispielsweise pausiert ist, möchtest du wahrscheinlich nicht BiB aktivieren.

Korrekten `sourceRectHint` zum Starten und Beenden des BiB-Modus festlegen

Seit der Einführung von BiB in Android 8.0 hat setSourceRectHint den Bereich der Aktivität angegeben, der nach dem Übergang zu Bild im Bild sichtbar ist, z. B. die Videoaufrufgrenzen in einem Videoplayer.

Unter Android 12 verwendet das System sourceRectHint, um eine viel flüssigere Animation beim Aufrufen und Beenden des BiB-Modus zu implementieren.

So legst du sourceRectHint richtig für das Starten und Beenden des BiB-Modus fest:

Erstellen Sie PictureInPictureParams mit den richtigen Grenzen als sourceRectHint. Wir empfehlen außerdem, einen Listener für Layoutänderungen an den Videoplayer 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 den sourceRectHint, bevor das System die Exit-Umstellung startet. Wenn das System kurz davor ist, den BiB-Modus zu beenden, wird die Ansichtshierarchie der Aktivität der Zielkonfiguration (z. B. Vollbild) zugeordnet. Die App kann einen Listener für Layoutänderungen an die Stammansicht oder die Zielansicht (z. B. der Videoplayeransicht) anhängen, um das Ereignis zu erkennen und den sourceRectHint 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());
    }
});

Nahtlose Größenanpassung für Inhalte deaktivieren, die keine Videos sind

In Android 12 wird das Flag setSeamlessResizeEnabled hinzugefügt, das beim Ändern der Größe von Nicht-Video-Inhalten im BiB-Fenster eine viel flüssigere Überblendungsanimation liefert. Bisher konnte das Ändern der Größe von Inhalten, die keine Videos sind, in einem BiB-Fenster zu irritierenden visuellen Artefakten führen.

So deaktivieren Sie die nahtlose Größenanpassung für Inhalte, die keine Videos sind:

Kotlin

setPictureInPictureParams(PictureInPictureParams.Builder()
    .setSeamlessResizeEnabled(false)
    .build())

Java

setPictureInPictureParams(new PictureInPictureParams.Builder()
    .setSeamlessResizeEnabled(false)
    .build());

UI bei BiB verarbeiten

Wenn der BiB-Modus für die Aktivität aktiviert oder beendet wird, ruft das System Activity.onPictureInPictureModeChanged() oder Fragment.onPictureInPictureModeChanged() auf.

Sie sollten diese Callbacks überschreiben, um die UI-Elemente der Aktivität neu zu zeichnen. Beachte, dass deine Aktivität im BiB-Modus in einem kleinen Fenster angezeigt wird. Nutzer können im BiB-Modus nicht mit den UI-Elementen Ihrer App interagieren und die Details kleiner UI-Elemente sind möglicherweise schwer zu erkennen. Videowiedergaben mit minimaler Benutzeroberfläche sorgen für die beste Nutzererfahrung.

Wenn Ihre Anwendung benutzerdefinierte Aktionen für BiB bereitstellen muss, lesen Sie den Abschnitt Steuerelemente hinzufügen auf dieser Seite. Entferne andere UI-Elemente, bevor deine Aktivität BiB erreicht, und stelle sie wieder her, wenn deine Aktivität wieder im Vollbildmodus zu sehen ist:

Kotlin

override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean,
                                           newConfig: Configuration) {
    if (isInPictureInPictureMode) {
        // Hide the full-screen UI (controls, etc.) while in PiP mode.
    } else {
        // Restore the full-screen UI.
    }
}

Java

@Override
public void onPictureInPictureModeChanged (boolean isInPictureInPictureMode, Configuration newConfig) {
    if (isInPictureInPictureMode) {
        // Hide the full-screen UI (controls, etc.) while in PiP mode.
    } else {
        // Restore the full-screen UI.
        ...
    }
}

Steuerelemente hinzufügen

Im BiB-Fenster werden Steuerelemente angezeigt, wenn der Nutzer das Fenstermenü öffnet. Dazu tippt er auf einem Mobilgerät auf das Fenster oder wählt das Menü über die Fernbedienung des Fernsehers aus.

Wenn eine App eine aktive Mediensitzung hat, werden die Steuerelemente für Wiedergabe, Pause, Weiter und Zurück angezeigt.

Sie können auch explizit benutzerdefinierte Aktionen angeben, indem Sie PictureInPictureParams mit PictureInPictureParams.Builder.setActions() erstellen, bevor der BiB-Modus aktiviert wird, und die Parameter übergeben, wenn Sie den BiB-Modus mit enterPictureInPictureMode(android.app.PictureInPictureParams) oder setPictureInPictureParams(android.app.PictureInPictureParams) starten. Sei vorsichtig. Wenn Sie versuchen, mehr als getMaxNumPictureInPictureActions() hinzuzufügen, erhalten Sie nur die maximale Anzahl.

Wiedergabe im BiB wird fortgesetzt

Wenn Ihre Aktivität zu BiB wechselt, wird die Aktivität in den Status „Pausiert“ gesetzt und die Methode onPause() der Aktivität aufgerufen. Die Videowiedergabe sollte nicht angehalten werden und sollte fortgesetzt werden, wenn die Aktivität im BiB-Modus angehalten wird.

Unter Android 7.0 und höher sollten Sie die Videowiedergabe anhalten und fortsetzen, wenn das System onStop() und onStart() Ihrer Aktivität aufruft. So müssen Sie nicht prüfen, ob sich Ihre App im BiB-Modus befindet, und die Wiedergabe explizit fortsetzen.

Wenn du das setAutoEnterEnabled-Flag nicht auf true gesetzt hast und die Wiedergabe in der onPause()-Implementierung pausieren musst, prüfe den BiB-Modus, indem du isInPictureInPictureMode() aufrufst und die Wiedergabe entsprechend verwaltest. Beispiele:

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 deine Aktivität aus dem BiB-Modus wieder in den Vollbildmodus wechselt, setzt das System die Aktivität fort und ruft die Methode onResume() auf.

Einzelne Wiedergabeaktivität für BiB verwenden

In deiner App kann ein Nutzer ein neues Video auswählen, wenn er auf dem Hauptbildschirm nach Inhalten sucht, während eine Videowiedergabe im BiB-Modus ausgeführt wird. Spielen Sie das neue Video in der vorhandenen Wiedergabeaktivität im Vollbildmodus ab, anstatt eine neue Aktivität zu starten, die den Nutzer verwirren könnte.

Damit eine einzelne Aktivität für Anfragen zur Videowiedergabe verwendet und bei Bedarf in den BiB-Modus gewechselt wird, musst du den android:launchMode der Aktivität in deinem Manifest auf singleTask setzen:

<activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...

Überschreiben Sie in Ihren Aktivitäten onNewIntent() und bearbeiten Sie das neue Video. Beenden Sie bei Bedarf die vorhandene Videowiedergabe.

Best Practices

BiB ist auf Geräten mit wenig RAM möglicherweise deaktiviert. Bevor deine Anwendung BiB verwendet, solltest du prüfen, ob sie verfügbar ist. Rufe dazu hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE) auf.

BiB ist für Aktivitäten gedacht, bei denen Videos im Vollbildmodus abgespielt werden. Wenn du für deine Aktivitäten den BiB-Modus aktivierst, solltest du nur Videoinhalte zeigen. Du kannst erfassen, wann deine Aktivität in den BiB-Modus wechselt, und UI-Elemente ausblenden, wie unter Benutzeroberfläche im BiB-Modus verarbeiten beschrieben.

Wenn sich eine Aktivität im BiB-Modus befindet, wird der Eingabefokus standardmäßig nicht angezeigt. Wenn Sie Eingabeereignisse im BiB-Modus empfangen möchten, verwenden Sie MediaSession.setCallback(). Weitere Informationen zur Verwendung von setCallback() findest du unter Now Playing-Karte anzeigen.

Wenn sich deine App im BiB-Modus befindet, kann die Videowiedergabe im BiB-Fenster zu Audiostörungen bei einer anderen App, z. B. einer Musikplayer-App oder einer Sprachsuche-App, führen. Um dies zu vermeiden, fordern Sie zu Beginn der Videowiedergabe den Audiofokus an und verarbeiten Sie Benachrichtigungen über das Ändern des Audiofokus, wie unter Audiofokus verwalten beschrieben. Wenn Sie im BiB-Modus eine Benachrichtigung über einen Verlust des Audiofokus erhalten, pausieren oder stoppen Sie die Videowiedergabe.

Wenn deine App BiB aktiviert, wird nur die wichtigste Aktivität in den Bild-im-Bild-Modus aktiviert. In einigen Situationen, z. B. auf Geräten mit Mehrfenstermodus, kann es sein, dass die folgende Aktivität jetzt zusammen mit der BiB-Aktivität angezeigt und wieder sichtbar wird. Sie sollten diesen Fall entsprechend behandeln, einschließlich der Aktivität unten, bei der ein onResume()- oder onPause()-Callback abgerufen wird. Es ist auch möglich, dass der Nutzer mit der Aktivität interagiert. Wenn beispielsweise eine Videolistenaktivität angezeigt wird und die Videoaktivität im BiB-Modus abgespielt wird, kann der Nutzer ein neues Video aus der Liste auswählen und die BiB-Aktivität sollte entsprechend aktualisiert werden.

Zusätzlicher Beispielcode

Informationen zum Herunterladen einer in Android geschriebenen Beispiel-App finden Sie unter Bild-im-Bild-Beispiel. Eine in Kotlin geschriebene Beispiel-App können Sie unter Android PictureInPicture-Beispiel (Kotlin) herunterladen.

Videos mit Bild im Bild (BiB) hinzufügen

So können Nutzer mit dem BiB-Fenster interagieren

BiB-Unterstützung deklarieren

Aktivitäten auf BiB umstellen

Kotlin

Java

Kotlin

Java

Empfohlen: Nutzern eine optimierte BiB-Umstellung ermöglichen

Einfacherer Wechsel in den BiB-Modus durch Bedienung über Gesten

Kotlin

Java

Korrekten sourceRectHint zum Starten und Beenden des BiB-Modus festlegen

Kotlin

Java

Kotlin

Java

Nahtlose Größenanpassung für Inhalte deaktivieren, die keine Videos sind

Kotlin

Java

UI bei BiB verarbeiten

Kotlin

Java

Steuerelemente hinzufügen

Wiedergabe im BiB wird fortgesetzt

Kotlin

Java

Einzelne Wiedergabeaktivität für BiB verwenden

Best Practices

Zusätzlicher Beispielcode

Korrekten `sourceRectHint` zum Starten und Beenden des BiB-Modus festlegen