如何在ReactPlayer中启用画中画？react-use-pip报错解惑

1. react-use-pip是否仅适用于原生video组件？ #

是的，react-use-pip 是对浏览器原生Picture-in-Picture API的封装，而该API只能直接作用于原生 <video> 元素。它的内部逻辑依赖调用video元素的 requestPictureInPicture()、exitPictureInPicture() 等方法，必须传入原生video的DOM引用才能正常工作。

2. 能否与ReactPlayer配合使用？ #

可以，但需要先获取ReactPlayer内部渲染的原生<video>元素引用，而非ReactPlayer组件本身的实例引用。

3. 报错的含义及原因 #

报错 Uncaught TypeError: Cannot read properties of undefined (reading 'toLocaleLowerCase') 是因为你传给usePictureInPicture的playerRef是ReactPlayer组件实例，而非原生video元素。react-use-pip尝试调用原生video方法时，发现引用指向的对象不符合要求，导致读取属性时出现undefined。

4. 其他实现画中画的方法或包 #

• 直接调用浏览器原生Picture-in-Picture API，手动封装逻辑，无需第三方包
• 使用react-picture-in-picture包，同样需要获取原生video元素
• 若播放第三方平台视频（如YouTube），需依赖对应平台的API支持（比如YouTube IFrame API的画中画功能）

ReactPlayer + react-use-pip 正确实现示例 #

ReactPlayer提供getInternalPlayer()方法，可获取内部的原生video元素（HTML5模式下），通过该方法拿到正确引用后即可集成：

import { useRef, useEffect, useState } from 'react';
import ReactPlayer from 'react-player';
import usePictureInPicture from 'react-use-pip';

function PlayerWithPiP() {
  const playerRef = useRef(null);
  const videoRef = useRef(null);
  const [isVideoReady, setIsVideoReady] = useState(false);

  const {
    isPictureInPictureActive,
    isPictureInPictureAvailable,
    togglePictureInPicture,
  } = usePictureInPicture(videoRef);

  useEffect(() => {
    if (playerRef.current) {
      const internalPlayer = playerRef.current.getInternalPlayer();
      // 确认是原生video元素（仅HTML5模式有效）
      if (internalPlayer instanceof HTMLVideoElement) {
        videoRef.current = internalPlayer;
        setIsVideoReady(true);
      }
    }
  }, []);

  return (
    <div>
      <ReactPlayer
        url="http://commondatastorage.googleapis.com/gtv-videos-bucket/big_buck_bunny_1080p.mp4"
        width="100%"
        height="auto"
        ref={playerRef}
        controls
      />
      {isVideoReady && isPictureInPictureAvailable && (
        <button onClick={() => togglePictureInPicture(!isPictureInPictureActive)}>
          {isPictureInPictureActive ? '关闭画中画' : '开启画中画'}
        </button>
      )}
    </div>
  );
}

export default PlayerWithPiP;

注意事项 #

• 确保ReactPlayer处于HTML5模式（播放普通视频链接默认是该模式），若播放第三方平台视频（如YouTube），getInternalPlayer()返回iframe，无法直接使用原生PiP API
• 浏览器需支持Picture-in-Picture API（Chrome、Edge、Firefox等现代浏览器均支持，Safari需手动开启相关设置）
• 画中画功能需用户交互触发，不能自动开启；视频需包含音轨（或设置muted后由用户手动触发）

内容的提问来源于stack exchange，提问作者Ramya Ramaradjou