实现视频画中画切换：videojs-player API应用

原创 于 2025-09-21 08:13:32 发布 · 695 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

实现视频画中画切换：videojs-player API应用

【免费下载链接】videojs-player @videojs player component for @vuejs(3) and React. 【免费下载链接】videojs-player 项目地址: https://gitcode.com/gh_mirrors/vi/videojs-player

痛点与解决方案

你是否遇到过视频播放时需要同时处理其他任务的场景？传统视频播放器强制全屏或固定窗口的模式，严重影响多任务处理效率。本文将详解如何通过videojs-player的画中画（Picture-in-Picture，PiP）API，实现视频悬浮播放功能，让用户在浏览网页的同时持续观看视频内容。

读完本文你将掌握：

  • 画中画模式的核心实现原理
  • videojs-player PiP API的完整使用方法
  • Vue/React框架下的组件集成方案
  • 跨浏览器兼容性处理策略
  • 高级定制技巧与性能优化

画中画技术基础

什么是画中画模式

画中画（Picture-in-Picture，PiP）是一种视频播放模式，允许视频在一个悬浮的小窗口中继续播放，同时用户可以与页面其他内容交互。该功能通过浏览器原生API或播放器扩展实现，目前已成为现代视频应用的标准配置。

浏览器支持情况

浏览器最低支持版本原生APIvideojs-player支持
Chrome70+✅✅
Firefox69+✅✅
Safari14+✅✅
Edge79+✅✅

数据来源：caniuse.com 2023年统计

videojs-player API概览

核心API结构

// 播放器核心接口定义
interface VideoJsPlayer {
  // 画中画控制
  pip(): boolean;               // 切换画中画状态
  isPIPActive(): boolean;       // 检查是否处于画中画模式
  supportsPIP(): boolean;       // 检查浏览器是否支持画中画
  togglePIP(): Promise<boolean>;// 异步切换画中画状态
  
  // 事件监听
  on(event: 'pip', listener: () => void): void;
  on(event: 'pip:exit', listener: () => void): void;
}

关键方法对比

方法功能描述返回值适用场景
pip()切换画中画状态boolean简单切换场景
togglePIP()异步切换画中画Promise 需要状态反馈的场景
isPIPActive()检查当前状态boolean条件渲染控制
supportsPIP()检测浏览器支持boolean功能降级处理

Vue3组件实现

基础集成示例

<template>
  <div class="video-container">
    <video-player
      ref="videoPlayer"
      :options="playerOptions"
      @ready="onPlayerReady"
    />
    <button 
      @click="togglePictureInPicture"
      :disabled="!isPiPSupported"
    >
      {{ isPIPActive ? '退出画中画' : '开启画中画' }}
    </button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted, Ref } from 'vue';
import { VideoPlayer } from '@videojs-player/vue';

const videoPlayer = ref<InstanceType<typeof VideoPlayer>>();
const isPiPSupported = ref(false);
const isPIPActive = ref(false);

const playerOptions = {
  autoplay: false,
  controls: true,
  responsive: true,
  fluid: true,
  sources: [{
    src: 'https://example.com/video.mp4',
    type: 'video/mp4'
  }]
};

const onPlayerReady = (player: any) => {
  // 检测画中画支持性
  isPiPSupported.value = player.supportsPIP();
  
  // 监听画中画事件
  player.on('pip', () => {
    isPIPActive.value = true;
    console.log('画中画模式已开启');
  });
  
  player.on('pip:exit', () => {
    isPIPActive.value = false;
    console.log('画中画模式已关闭');
  });
};

const togglePictureInPicture = async () => {
  if (!videoPlayer.value) return;
  
  try {
    const player = videoPlayer.value.player;
    const success = await player.togglePIP();
    if (!success) {
      console.error('画中画切换失败');
    }
  } catch (error) {
    console.error('画中画操作出错:', error);
  }
};
</script>

<style scoped>
.video-container {
  max-width: 800px;
  margin: 0 auto;
}
button {
  margin-top: 10px;
  padding: 8px 16px;
  background: #007bff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
button:disabled {
  background: #ccc;
  cursor: not-allowed;
}
</style>

组件封装最佳实践

// components/VideoPlayerWithPiP.vue
import { defineComponent, ref, onUnmounted } from 'vue';
import { VideoPlayer } from '@videojs-player/vue';

export default defineComponent({
  name: 'VideoPlayerWithPiP',
  components: { VideoPlayer },
  props: {
    src: { type: String, required: true },
    type: { type: String, default: 'video/mp4' },
    autoplay: { type: Boolean, default: false }
  },
  emits: ['pip-change'],
  setup(props, { emit }) {
    const playerRef = ref<any>(null);
    const isPIPActive = ref(false);
    
    const handlePipChange = (active: boolean) => {
      isPIPActive.value = active;
      emit('pip-change', active);
    };
    
    const togglePiP = async () => {
      if (!playerRef.value) return;
      const player = playerRef.value.player;
      if (!player.supportsPIP()) return false;
      
      return player.togglePIP();
    };
    
    const onReady = (player: any) => {
      player.on('pip', () => handlePipChange(true));
      player.on('pip:exit', () => handlePipChange(false));
    };
    
    onUnmounted(() => {
      if (playerRef.value) {
        const player = playerRef.value.player;
        player.off('pip');
        player.off('pip:exit');
      }
    });
    
    return {
      playerRef,
      isPIPActive,
      togglePiP,
      onReady
    };
  }
});

React组件实现

函数式组件示例

import React, { useRef, useState, useEffect } from 'react';
import { VideoPlayer } from '@videojs-player/react';

interface VideoPlayerWithPiPProps {
  src: string;
  type?: string;
  width?: number;
  height?: number;
}

const VideoPlayerWithPiP: React.FC<VideoPlayerWithPiPProps> = ({
  src,
  type = 'video/mp4',
  width = 800,
  height = 450
}) => {
  const playerRef = useRef<any>(null);
  const [isPiPSupported, setIsPiPSupported] = useState(false);
  const [isPIPActive, setIsPIPActive] = useState(false);
  
  const handlePlayerReady = (player: any) => {
    // 存储player实例
    playerRef.current = player;
    
    // 检测支持性
    setIsPiPSupported(player.supportsPIP());
    
    // 绑定事件监听
    player.on('pip', () => {
      setIsPIPActive(true);
    });
    
    player.on('pip:exit', () => {
      setIsPIPActive(false);
    });
  };
  
  const togglePictureInPicture = async () => {
    if (!playerRef.current) return;
    
    try {
      const result = await playerRef.current.togglePIP();
      if (!result) {
        alert('画中画切换失败，请检查浏览器设置');
      }
    } catch (error) {
      console.error('画中画操作错误:', error);
    }
  };
  
  // 组件卸载时清理事件监听
  useEffect(() => {
    return () => {
      if (playerRef.current) {
        const player = playerRef.current;
        player.off('pip');
        player.off('pip:exit');
      }
    };
  }, []);
  
  return (
    <div className="video-player-container">
      <VideoPlayer
        options={{
          autoplay: false,
          controls: true,
          width,
          height,
          sources: [{ src, type }]
        }}
        onReady={handlePlayerReady}
      />
      
      <button
        onClick={togglePictureInPicture}
        disabled={!isPiPSupported}
        className="pip-button"
      >
        {isPIPActive ? '退出画中画' : '开启画中画'}
      </button>
    </div>
  );
};

export default VideoPlayerWithPiP;

自定义Hook封装

// hooks/usePictureInPicture.ts
import { useRef, useState, useEffect, MutableRefObject } from 'react';

export function usePictureInPicture() {
  const playerRef = useRef<any>(null);
  const [isSupported, setIsSupported] = useState(false);
  const [isActive, setIsActive] = useState(false);
  
  // 初始化画中画支持检测
  useEffect(() => {
    if (typeof document !== 'undefined' && 'pictureInPictureEnabled' in document) {
      setIsSupported(true);
    }
  }, []);
  
  // 绑定播放器事件
  const setupPlayerEvents = (player: any) => {
    playerRef.current = player;
    
    player.on('pip', () => setIsActive(true));
    player.on('pip:exit', () => setIsActive(false));
    
    // 检测当前是否已在画中画模式
    if (player.isPIPActive()) {
      setIsActive(true);
    }
  };
  
  // 切换画中画状态
  const togglePiP = async () => {
    if (!playerRef.current || !isSupported) return false;
    
    try {
      return await playerRef.current.togglePIP();
    } catch (error) {
      console.error('画中画切换失败:', error);
      return false;
    }
  };
  
  // 清理事件监听
  const cleanup = () => {
    if (playerRef.current) {
      playerRef.current.off('pip');
      playerRef.current.off('pip:exit');
    }
  };
  
  return {
    playerRef,
    isSupported,
    isActive,
    setupPlayerEvents,
    togglePiP,
    cleanup
  };
}

高级应用场景

自动画中画切换

实现页面滚动时自动激活画中画模式：

// 监听页面滚动事件
window.addEventListener('scroll', () => {
  const player = playerRef.current;
  if (!player || !player.supportsPIP()) return;
  
  // 获取视频元素位置
  const rect = player.el().getBoundingClientRect();
  
  // 当视频元素离开视口时自动开启画中画
  if (rect.bottom < 0 || rect.top > window.innerHeight) {
    if (!player.isPIPActive()) {
      player.togglePIP();
    }
  } else {
    // 当视频元素回到视口时退出画中画
    if (player.isPIPActive()) {
      player.togglePIP();
    }
  }
});

画中画状态同步

在多标签页之间同步画中画状态：

// 存储画中画状态到localStorage
function syncPiPState(active) {
  localStorage.setItem('video-pip-state', JSON.stringify({
    active,
    timestamp: Date.now()
  }));
}

// 监听存储事件同步状态
window.addEventListener('storage', (e) => {
  if (e.key === 'video-pip-state') {
    const state = JSON.parse(e.newValue);
    const player = playerRef.current;
    
    if (player && player.isPIPActive() !== state.active) {
      player.togglePIP();
    }
  }
});

// 在画中画事件中更新状态
player.on('pip', () => syncPiPState(true));
player.on('pip:exit', () => syncPiPState(false));

兼容性处理

浏览器特性检测

// 全面的画中画支持性检测
function checkPiPSupport() {
  // 检测浏览器原生支持
  const hasNativeSupport = 'pictureInPictureEnabled' in document;
  
  // 检测videojs-player支持
  const hasPlayerSupport = player && typeof player.supportsPIP === 'function';
  
  // 检测当前环境是否允许
  const isAllowed = !document.pictureInPictureElement;
  
  return hasNativeSupport && hasPlayerSupport && isAllowed;
}

功能降级方案

当浏览器不支持画中画时，提供替代方案：

<template>
  <div v-if="!isPiPSupported" class="pip-fallback">
    <h4>您的浏览器不支持画中画功能</h4>
    <p>推荐使用以下浏览器以获得最佳体验：</p>
    <ul>
      <li>Chrome 70+</li>
      <li>Firefox 69+</li>
      <li>Safari 14+</li>
      <li>Edge 79+</li>
    </ul>
    
    <!-- 替代方案：小窗口悬浮播放 -->
    <button @click="enableFloatingMode">启用悬浮窗口模式</button>
  </div>
</template>

性能优化策略

资源占用对比

播放模式CPU占用内存占用电池消耗
正常模式中中中
画中画模式低低低
全屏模式高中高

优化建议

  1. 限制画中画窗口大小：通过API设置最小尺寸，避免过大窗口影响性能

    player.pip({ width: 320, height: 180 }); // 设置画中画窗口大小

  2. 暂停非活跃视频：当多个视频同时播放时，仅保持画中画视频活跃

    // 暂停其他所有视频
document.querySelectorAll('video').forEach(video => {
  if (video !== player.el() && !video.paused) {
    video.pause();
  }
});

  3. 减少画中画模式下的视频质量：降低分辨率减少带宽和资源消耗

    // 切换到低分辨率源流
if (player.isPIPActive()) {
  player.src({ src: 'low-quality-video.mp4', type: 'video/mp4' });
}

总结与展望

画中画功能已成为现代视频应用的必备特性，通过videojs-player的API可以轻松实现这一功能，极大提升用户体验。本文详细介绍了从基础集成到高级应用的完整方案，包括Vue和React框架下的实现代码、兼容性处理和性能优化策略。

随着Web技术的发展，未来画中画功能将支持更多高级特性，如多视频画中画、自定义窗口样式、画中画内容交互等。开发者应持续关注浏览器API和videojs-player的更新，为用户提供更加丰富的视频体验。

收藏本文，随时查阅videojs-player画中画实现方案，关注作者获取更多视频播放技术实践指南！

【免费下载链接】videojs-player @videojs player component for @vuejs(3) and React. 【免费下载链接】videojs-player 项目地址: https://gitcode.com/gh_mirrors/vi/videojs-player

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值