画中画（Picture-in-Picture, PiP）是一种多窗口模式，允许用户在屏幕一角的小窗口中观看视频，同时在主屏幕上继续与其他应用或内容进行交互。播放器 SDK 支持以下两种画中画实现模式，以适应不同的业务场景：

• 手动模式：由用户主动触发。通常是在播放器界面提供一个“画中画”或“小窗播放”按钮，用户点击后，视频窗口会缩小并悬浮。开发者需要在用户点击按钮时，调用 SDK 提供的 API 来开启画中画。
• 自动模式：由系统事件触发。此模式指应用切换到后台时，可实现自动进入画中画的效果。这并非 SDK 的内置自动行为，而是需要开发者监听应用的生命周期事件（如应用进入后台），并主动调用接口来开启画中画。

兼容性与前置条件 #

在集成画中画功能前，请确保您的项目满足对应平台的前提条件。

Android #

• 悬浮窗画中画（type: 'floating'）：
  • 最低版本要求：Android 6.0（API 23）及以上。
  • 权限要求：​需要获取“显示在其他应用上层”（即悬浮窗）权限。

    说明

    • 如果您在应用未获授权时调用 startPictureInPicture 接口，SDK 会自动跳转至系统授权页面。
    • 您也可以调用 requestOverlayPermission 接口主动引导用户授权，参看权限申请（仅 Android）。
• 系统画中画（type: 'system'）：

  • 最低版本要求：Android 8.0（API 26）及以上。

  • 权限要求：​在应用 AndroidManifest.xml 中声明画中画权限：

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

    说明

    推荐配置 configChanges 属性， 以防止 PiP 模式切换时 Activity 重建。

• 系统自动进入（通过 enableAutoStartPictureInPicture()）：如需在系统支持的场景下自动进入 PiP，要求 Android 12（API 31）及以上。

iOS #

• 系统版本：iOS 15 及以上版本。
• 项目配置：在 Xcode 项目中，您必须开启 Audio, AirPlay, and Picture in Picture 后台模式。参考步骤如下：
  1. 在 Xcode 项目中选择 App 的 Target。
  2. 单击 Signing & Capabilities 页签。
  3. 单击 + Capability 按钮添加 Background Modes 功能，勾选 Audio, AirPlay, and Picture in Picture。
     
• 系统画中画设置：请确保用户已在设备的设置 > 通用 > 画中画页面中，开启自动开启画中画开关。
  

权限申请（仅 Android） #

为了提供更好的用户体验，建议您在用户点击画中画按钮前，通过引导流程主动申请悬浮窗权限，而不是在用户点击后被动触发。

import { requestOverlayPermission } from '@volcengine/react-native-vod-player';

// 调用后会跳转到系统设置页面引导用户进行手动授权
requestOverlayPermission();

配置画中画 #

建议在播放器初始化后尽早完成画中画配置。

import { configurePictureInPicture } from '@volcengine/react-native-vod-player';

configurePictureInPicture({
  type: 'floating',            // Android: 'floating' | 'system'，默认值为 'floating'
  syncPlayerViewConfig: false, // 是否同步播放器视图配置
});

参数说明：

• type：Android 平台的画中画类型，可选值为 'floating'（悬浮窗画中画） 或 'system'（系统画中画）。默认值为 'floating'。二者区别请参看 Android 平台画中画类型。iOS 会忽略该参数。
• syncPlayerViewConfig：是否同步播放器视图配置。设置为 true 后，画中画窗口会尽量保持与播放器视图一致的画面比例和填充模式。

手动开启画中画 #

步骤 1：设置全局监听回调 #

建议在 App 初始化或播放页面挂载时设置监听，以便同步 App 内部的 UI 状态。

import { setPictureInPictureListener } from '@volcengine/react-native-vod-player';

setPictureInPictureListener({
  onStartPictureInPicture() {
    console.log('画中画已开启');
  },
  onStopPictureInPicture() {
    console.log('画中画已关闭');
  },
  onError(code, extraData) {
    // 错误码 0:成功, 1:不支持, 2:参数错误, 3:已开启
    console.log(`画中画开启失败: ${code}, ${extraData}`);
  },
  onClickPictureInPictureRestoreBtn() {
    // 用户点击画中画窗口右上角的恢复按钮
    console.log('正在从画中画恢复到应用');
  },
});

步骤 2：调用开启接口 #

在视频播放过程中，调用播放器实例的方法。

// 1. 判断当前环境是否支持画中画
import { isPictureInPictureSupported } from '@volcengine/react-native-vod-player';
const isSupport = isPictureInPictureSupported();

if (isSupport) {
  // 2. 开启画中画（仅播放时有效）
  player.startPictureInPicture();
}

// 3. 停止画中画（或返回原页面）
player.stopPictureInPicture();
// 或者调用 stopPictureInPictureGlobal 停止画中画，该方法不依赖播放器实例
// stopPictureInPictureGlobal();

自动开启画中画 #

本节介绍如何实现应用从前台切换到后台时，自动开启画中画的功能。该功能需要您结合 App 的生命周期事件进行开发。

步骤 1：开启 SDK 的自动画中画配置 #

在播放器创建后，调用以下接口允许应用在后台触发画中画逻辑。

// 允许应用进入后台后自动开启画中画
player.enableAutoStartPictureInPicture();

步骤 2：监听 App 生命周期并手动触发 #

如果没有调用configurePictureInPicture切换 Android 画中画类型，默认是悬浮窗画中画。由于系统环境限制，SDK 无法直接感知应用切换至后台的动作。因此，实现自动开启画中画的关键在于，你需要通过 React Native 的 AppState 监听应用状态，在应用进入后台时主动调用开启画中画接口。

import { AppState } from 'react-native';

useEffect(() => {
  const subscription = AppState.addEventListener('change', nextAppState => {
    if (nextAppState === 'background') {
      // 应用进入后台，主动触发画中画
      player.startPictureInPicture();
    } else if (nextAppState === 'active') {
      // 应用返回前台，通常需关闭画中画以恢复全屏播放
      player.stopPictureInPicture();
    }
  });

  return () => {
    subscription.remove();
  };
}, []);

Feed 流场景实现画中画 #

在 Feed 流（上下滑动切换视频）场景下，若想在画中画小窗内实现视频的无缝切集，参考以下步骤：

1. 销毁旧播放器实例：调用 close 方法时，传入 {stopPip: false} 参数，销毁播放器实例但保持当前的画中画窗口不被关闭。
2. 创建新播放器实例：在切换到下一个视频实例后，立即对其调用 startPictureInPicture 以接管现有窗口。

// 1. 停止并销毁当前播放器实例，但保持画中画窗口开启
lastPlayer.close({ stopPip: false });

// 2. 立即让新播放器实例接管画中画窗口并播放
nextPlayer.startPictureInPicture();
nextPlayer.play();

附录 #

Android 平台画中画类型 #

在 Android 平台上，SDK 提供两种画中画实现方式：

• 悬浮窗画中画：基于悬浮窗能力实现，默认采用该模式，需要用户授权悬浮窗权限。

  

• 系统画中画：基于 Android Activity 的系统 PiP 模式实现。该模式具有更自然的系统转场动画，开启后应用会切换到后台。