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 Bild-im-Bild-Modus (BiB). BiB ist eine spezielle Art des Mehrfenstermodus, für die Videowiedergabe verwendet wird. Der Nutzer kann sich ein Video in einem kleinen, angepinnten Fenster in einer Ecke des Bildschirms, während Sie zwischen Apps wechseln oder Inhalte auf Hauptbildschirms.

BiB nutzt die in Android 7.0 verfügbaren Mehrfenster-APIs, um angepinnten Video-Overlay-Fenster. Um BiB zu deiner App hinzuzufügen, musst du deine Aktivitäten, die BiB unterstützen, kannst du bei Bedarf in den BiB-Modus wechseln und Achten Sie darauf, dass UI-Elemente ausgeblendet sind und die Videowiedergabe fortgesetzt wird, wenn die Aktivität im BiB-Modus ist.

Das BiB-Fenster wird im obersten Layer des Bildschirms in einer von den System.

BiB wird auch auf kompatiblen Android TV-Geräten mit Android 14 (API-Level 34) oder höher Es gibt viele Gemeinsamkeiten, zusätzliche Überlegungen bei der Verwendung BiB auf Fernsehern:

Wie Nutzer mit dem BiB-Fenster interagieren können

Nutzer können das BiB-Fenster an eine andere Stelle ziehen. Ab Android 12 kann auch:

Tippen Sie einmal auf das Fenster, um eine Ein/Aus-Schaltfläche für den Vollbildmodus, eine Schließen-Schaltfläche, eine die Einstellungsschaltfläche und benutzerdefinierte Aktionen deiner App (z. B. Steuerelementen).
Tippe doppelt auf das Fenster, um zwischen der aktuellen und der maximalen BiB-Größe zu wechseln. oder minimale BiB-Größe, z. B. durch Doppeltippen auf ein maximiertes Fenster und umgekehrt.
Verschieben Sie das Fenster, indem Sie es an den linken oder rechten Rand ziehen. Um den tippen Sie entweder auf den sichtbaren Teil des verschachtelten Fensters oder ziehen Sie ihn heraus.
Ändern Sie die Größe des BiB-Fensters, indem Sie zum Zoomen die Finger auseinander- und zusammenziehen.

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

Eine Aktivität kann in den BiB-Modus wechseln, wenn der Nutzer auf die Startbildschirmtaste tippt oder wischt bis nach Hause. So werden in Google Maps weiterhin Wegbeschreibungen der Nutzer gleichzeitig eine andere Aktivität ausführt.
Deine App kann ein Video in den BiB-Modus versetzen, wenn der Nutzer von nach anderen Inhalten suchen.
Deine App kann ein Video in den BiB-Modus versetzen, während sich ein Nutzer das Ende eines Videos ansieht eine Folge von Inhalten. Auf dem Hauptbildschirm wird Werbung oder eine Zusammenfassung angezeigt. zur nächsten Folge der Serie.
Ihre App bietet Nutzern die Möglichkeit, zusätzliche Inhalte in die Warteschlange zu stellen, während sehen sie sich ein Video an. Das Video wird im BiB-Modus weiter abgespielt, während der Hauptbildschirm Bildschirm eine Aktivität zur Inhaltsauswahl angezeigt.

BiB-Unterstützung deklarieren

BiB wird für Apps standardmäßig nicht automatisch unterstützt. Bei Bedarf BiB in deiner App unterstützen, deine Videoaktivität in deinem Manifest registrieren, indem du android:supportsPictureInPicture wird auf true festgelegt. Geben Sie außerdem an, und "Aktivität" verarbeitet Änderungen der Layoutkonfiguration, sodass Ihre Aktivität neu starten, wenn Layoutänderungen während Wechsel im BiB-Modus erfolgen.

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

Aktivitäten auf BiB umstellen

Ab Android 12 kannst du deine Aktivitäten in den BiB-Modus versetzen, indem du das Flag setAutoEnterEnabled in true. Bei dieser Einstellung wird eine Aktivität wechselt bei Bedarf automatisch in den BiB-Modus, ohne enterPictureInPictureMode() in onUserLeaveHint Und das hat die hat den Vorteil, dass die Übergänge viel reibungsloser sind. Weitere Informationen finden Sie unter Wechsel bei der Bedienung über Gesten reibungsloser in den BiB-Modus.

Wenn Ihre App auf Android 11 oder niedriger ausgerichtet ist, muss eine Aktivität den Aufruf enterPictureInPictureMode() um in den BiB-Modus zu wechseln. Mit dem folgenden Code wird beispielsweise eine Aktivität in BiB-Modus, wenn der Nutzer auf eine bestimmte 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;
    }
    ...
}

Stattdessen können Sie eine Logik einbinden, die eine Aktivität in den BiB-Modus verwandelt. in den Hintergrund zu gehen. Google Maps wechselt z. B. in den BiB-Modus, während die App navigiert, während der Nutzer die Startbildschirmtaste oder die Schaltfläche „Letzte Apps“ drückt. Sie können um diesen Fall abzufangen, indem Sie onUserLeaveHint():

Kotlin

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

Java

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

Empfohlen: Nutzern eine ausgefeilte BiB-Umstellung anbieten

Unter Android 12 wurden die animierten Übergänge erheblich verbessert. zwischen Vollbild- und BiB-Fenster. Wir empfehlen dringend, alle anwendbare Änderungen; Sobald Sie dies getan haben, werden diese Änderungen automatisch große Displays wie faltbare Geräte und Tablets ohne weitere Arbeitsschritte.

Auch wenn deine App keine entsprechenden Updates enthält, sind BiB-Umstellungen immer noch aktiv. aber die Animationen sind weniger ausgefeilt. Zum Beispiel kann die Umstellung vom Vollbildmodus in den BiB-Modus wechselt, kann das dazu führen, dass das BiB-Fenster während bevor er wieder angezeigt wird, wenn er abgeschlossen ist.

Diese Änderungen umfassen Folgendes.

Reibungsloserer Wechsel in den BiB-Modus von der Bedienung über Gesten
Richtige sourceRectHint zum Aufrufen und Beenden des BiB-Modus festlegen
Nahtlose Größenanpassung für Nicht-Video-Inhalte deaktivieren

Weitere Informationen finden Sie in der Android-App Kotlin-Beispiel für PictureInPicture als Referenz für eine ausgefeilte Umstellung.

Einfacher Wechsel zum BiB-Modus von der Bedienung über Gesten

Ab Android 12 bietet das Flag setAutoEnterEnabled viele flüssigere Animation für den Wechsel zu Videoinhalten im BiB-Modus mit Touch-Gesten wenn du im Vollbildmodus nach oben wischst, um zum Startbildschirm zurückzukehren.

Führen Sie die folgenden Schritte aus, um diese Änderung vorzunehmen. In diesem Beispiel Referenz:

Mit setAutoEnterEnabled erstellen PictureInPictureParams.Builder:

Kotlin

setPictureInPictureParams(PictureInPictureParams.Builder()
    .setAspectRatio(aspectRatio)
    .setSourceRectHint(sourceRectHint)
    .setAutoEnterEnabled(true)
    .build())

Java

setPictureInPictureParams(new PictureInPictureParams.Builder()
    .setAspectRatio(aspectRatio)
    .setSourceRectHint(sourceRectHint)
    .setAutoEnterEnabled(true)
    .build());

Rufen Sie setPictureInPictureParams mit den aktuellen PictureInPictureParams früher. Die App wartet nicht auf die onUserLeaveHint-Callback. So wie es bei Android 11 der Fall gewesen wäre.

Beispielsweise können Sie setPictureInPictureParams direkt auf der erste und jede nachfolgende Wiedergabe, wenn sich das Seitenverhältnis ändert.
Rufen Sie setAutoEnterEnabled(false) auf, aber nur bei Bedarf. Beispiel: BiB ist nicht sinnvoll, wenn die aktuelle Wiedergabe pausiert ist. Bundesstaat.

Richtige `sourceRectHint` zum Aufrufen und Beenden des BiB-Modus festlegen

Beginnend mit der Einführung von BiB in Android 8.0, setSourceRectHint den Bereich der Aktivität angegeben, der nach dem Übergang zu Bild im Bild, zum Beispiel die Begrenzungen des Videoaufrufs in einem Videoplayer

Unter Android 12 nutzt das System sourceRectHint, um eine viel flüssigere sowohl beim Aufrufen als auch beim Beenden des BiB-Modus.

So richtest du sourceRectHint richtig ein, um den BiB-Modus zu starten und zu beenden:

PictureInPictureParams erstellen unter Verwendung der richtigen Grenzen als sourceRectHint. Wir empfehlen außerdem, Listener für Layoutänderungen an den Videoplayer:

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 zum Beenden des Übergangs. Wenn das System den BiB-Modus verlässt, wird der Aufruf ist die Ansichtshierarchie entsprechend ihrer Zielkonfiguration angeordnet (z. B. Vollbildmodus). Die App kann einen Listener für Layoutänderungen an ihre Stammansicht anhängen Video-Player-Ansicht verwenden, um das Ereignis zu erkennen und sourceRectHint aktualisieren, bevor die Animation beginnt.

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, die keine Videos sind, deaktivieren

In Android 12 wird das Flag setSeamlessResizeEnabled hinzugefügt, das viele flüssigere Überblendungsanimation beim Ändern der Größe von Inhalten ohne Videos im BiB-Fenster . Bisher konnte durch das Ändern der Größe von Inhalten, die keine Videos sind, in einem BiB-Fenster und verwirrende visuelle Artefakte.

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 während BiB verarbeiten

Wenn die Aktivität in den BiB-Modus wechselt oder diesen beendet, ruft das System Activity.onPictureInPictureModeChanged() oder Fragment.onPictureInPictureModeChanged()

Sie sollten diese Callbacks überschreiben, um die UI-Elemente der Aktivität neu zu zeichnen. Notizen dass deine Aktivitäten im BiB-Modus in einem kleinen Fenster angezeigt werden. Nutzer dürfen mit den UI-Elementen Ihrer App interagieren, wenn diese sich im BiB-Modus befindet, und die Details kleine UI-Elemente sind möglicherweise schwer zu sehen. Videowiedergaben mit mit minimaler Benutzeroberfläche die beste User Experience bieten.

Wenn deine App benutzerdefinierte Aktionen für BiB bereitstellen muss, siehe Add Steuerelemente auf dieser Seite. Entfernen Sie andere UI-Elemente vor der im BiB-Fenster angezeigt und wiederhergestellt werden, wenn die Aktivität im Vollbildmodus angezeigt wird noch einmal:

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 können Steuerelemente angezeigt werden, wenn der Nutzer das Fenstermenü öffnet (durch auf einem Mobilgerät auf das Fenster tippen oder das Menü auf dem Fernseher auswählen Fernbedienung.)

Wenn eine App über ein aktives Medium verfügt, Sitzung, dann abspielen werden die Steuerelemente zum Pausieren, Weiter und Zurück angezeigt.

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

Videowiedergabe im BiB-Modus fortsetzen

Sobald deine Aktivität zu BiB wechselt, platziert das System die Aktivität in den pausierten und ruft die Funktion onPause()-Methode. Videokampagne sollte die Wiedergabe nicht pausiert werden. Stattdessen sollte sie fortgesetzt werden, wenn die Aktivität pausiert, während in den BiB-Modus gewechselt wird.

Unter Android 7.0 und höher solltest du die Wiedergabe pausieren und fortsetzen, wenn die ruft das System die onStop() und onStart() Dadurch kannst du vermeiden, dass du prüfen musst, ob sich deine App in onPause() im BiB-Modus befindet und Wiedergabe explizit fortsetzen.

Wenn Sie das Flag setAutoEnterEnabled nicht auf true gesetzt haben und pausiere die Wiedergabe in deiner onPause()-Implementierung und prüfe den BiB-Modus, indem du isInPictureInPictureMode() und die Wiedergabe entsprechend handhaben. 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äten vom BiB-Modus zurück in den Vollbildmodus wechseln, setzt Ihre Aktivität fort und ruft onResume()-Methode.

Einzelne Wiedergabeaktivität für BiB verwenden

In Ihrer App kann ein Nutzer, der nach Inhalten auf der Website sucht, ein neues Video auswählen. während die Videowiedergabe im BiB-Modus stattfindet. Neues Video abspielen in der bestehenden Wiedergabeaktivität im Vollbildmodus angezeigt, anstatt ein neue Aktivitäten, die die Nutzenden verwirren könnten.

Um sicherzustellen, dass eine einzelne Aktivität für Videowiedergabeanfragen verwendet wird und in den BiB-Modus wechseln oder den BiB-Modus deaktivieren, setze den android:launchMode der Aktivität auf singleTask im Manifest:

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

Überschreiben Sie in Ihren Aktivitäten onNewIntent() und verarbeiten das neue Video, wobei die vorhandene Videowiedergabe bei Bedarf beendet wird.

Best Practices

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

BiB ist für Aktivitäten gedacht, bei denen ein Video im Vollbildmodus abgespielt wird. Wenn Sie die in den BiB-Modus wechseln und nur Videoinhalte zeigen. Erfassen, wenn Ihre Aktivität wechselt in den BiB-Modus und blendet UI-Elemente aus, wie unter Umgang mit der Benutzeroberfläche beschrieben: bei BiB.

Wenn eine Aktivität im BiB-Modus ist, wird standardmäßig kein Eingabefokus angezeigt. Bis im BiB-Modus Eingabeereignisse empfangen, verwenden Sie MediaSession.setCallback() Weitere Informationen zur Verwendung von setCallback() finden Sie unter „Now Playing“ anzeigen .

Wenn sich deine App im BiB-Modus befindet, kann die Videowiedergabe im BiB-Fenster zu Audio führen Beeinträchtigung anderer Apps, z. B. einer Musikplayer-App oder einer Sprachsuche-App. Um dies zu vermeiden, fordern Sie beim Start der Videowiedergabe den Audiofokus an und bearbeiten Sie Benachrichtigungen zu Änderungen des Audiofokus, wie unter Audio verwalten Fokus: Wenn Sie eine Benachrichtigung erhalten des Verlusts des Audiofokus, wenn im BiB-Modus die Videowiedergabe angehalten oder beendet wird.

Wenn in deiner App BiB gestartet wird, beachte, dass nur die Top-Aktivität angezeigt wird. Bild im Bild. In einigen Situationen, z. B. auf Geräten mit Mehrfenstermodus, möglich, dass die Aktivität unten jetzt angezeigt wird und zusammen mit die BiB-Aktivität. Sie sollten diesen Fall entsprechend behandeln, einschließlich des Fehlers Aktivität unten, die einen onResume()- oder onPause()-Callback erhält. Es ist auch dass Nutzende mit der Aktivität interagieren können. Wenn Sie beispielsweise angezeigt wird, in der Videoliste angezeigt wird und das wiedergegebene Video im BiB-Modus ist, Der Nutzer kann ein neues Video aus der Liste auswählen und die BiB-Aktivität wird aktualisiert. entsprechend anpassen.

Zusätzlicher Beispielcode

Informationen zum Herunterladen einer in Kotlin geschriebenen Beispiel-App finden Sie unter Android PictureInPicture-Beispiel (Kotlin)

Videos mit Bild im Bild (BiB) hinzufügen

Wie Nutzer mit dem BiB-Fenster interagieren können

BiB-Unterstützung deklarieren

Aktivitäten auf BiB umstellen

Kotlin

Java

Kotlin

Java

Empfohlen: Nutzern eine ausgefeilte BiB-Umstellung anbieten

Einfacher Wechsel zum BiB-Modus von der Bedienung über Gesten

Kotlin

Java

Richtige sourceRectHint zum Aufrufen und Beenden des BiB-Modus festlegen

Kotlin

Java

Kotlin

Java

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

Kotlin

Java

UI während BiB verarbeiten

Kotlin

Java

Steuerelemente hinzufügen

Videowiedergabe im BiB-Modus fortsetzen

Kotlin

Java

Einzelne Wiedergabeaktivität für BiB verwenden

Best Practices

Zusätzlicher Beispielcode

Richtige `sourceRectHint` zum Aufrufen und Beenden des BiB-Modus festlegen