站点 Logo
浏览器全屏 API 实战指南：从原生 JS 到 Vue 3 封装
📗 开发笔记· 2026-10-01 01:00 · 6

浏览器全屏 API 实战指南：从原生 JS 到 Vue 3 封装

想给视频播放器、图片查看器或报表页面加上「一键全屏」？浏览器原生 `Fullscreen API` 就能实现，无需引入任何第三方库。本文从原生 JavaScript 到 Vue 3 组合式封装，带你完整掌握进入全屏、退出全屏、状态检测与监听的全部玩法。

VueJavaScript
目录
浏览器全屏 API 实战指南：从原生 JS 到 Vue 3 封装
一、Fullscreen API 是什么
二、功能一览
三、原生 JavaScript 实现
1. 进入全屏
2. 退出全屏
3. 判断是否处于全屏状态
4. 切换全屏（一键 Toggle）
四、Vue 3 组合式封装
五、监听全屏状态变化（可选）
六、注意事项与兼容性提示
七、总结

浏览器全屏 API 实战指南：从原生 JS 到 Vue 3 封装

想给视频播放器、图片查看器或报表页面加上「一键全屏」？浏览器原生 Fullscreen API 就能实现，无需引入任何第三方库。本文从原生 JavaScript 到 Vue 3 组合式封装，带你完整掌握进入全屏、退出全屏、状态检测与监听的全部玩法。

一、Fullscreen API 是什么

Fullscreen API 是浏览器提供的一组原生接口，可以让任意 HTML 元素进入全屏展示，也能随时退出全屏。它特别适合以下几类场景：

  • 视频播放器的全屏播放；
  • 图片/看图模式的沉浸式浏览；
  • 报表、图表、看板的全屏展示；
  • 任何需要「占满屏幕」交互的页面元素。

它最大的优势是零依赖——不需要引入任何第三方库，浏览器原生支持，非常适合封装成可复用的组件。

二、功能一览

完整的全屏能力通常包含四个核心功能：

功能 说明
进入全屏 让指定元素占满整个屏幕
退出全屏 从全屏状态恢复正常窗口
状态检测 判断当前是否有元素处于全屏状态
变化监听 监听全屏状态的切换（可选，用于同步 UI）

同时，为了兼容老版本浏览器，还需要处理各浏览器前缀（webkit / moz / ms）。

三、原生 JavaScript 实现

1. 进入全屏

默认全屏对象是整个文档根元素，也可以传入任意指定的元素（如某个视频、某张图片）：

js 复制代码 
function enterFullscreen(el = document.documentElement) {
  if (el.requestFullscreen) {
    el.requestFullscreen();
  } else if (el.webkitRequestFullscreen) {
    el.webkitRequestFullscreen();
  } else if (el.mozRequestFullScreen) {
    el.mozRequestFullScreen();
  } else if (el.msRequestFullscreen) {
    el.msRequestFullscreen();
  }
}

2. 退出全屏

退出全屏是文档级别的操作，不依赖具体元素：

js 复制代码 
function exitFullscreen() {
  if (document.exitFullscreen) {
    document.exitFullscreen();
  } else if (document.webkitExitFullscreen) {
    document.webkitExitFullscreen();
  } else if (document.mozCancelFullScreen) {
    document.mozCancelFullScreen();
  } else if (document.msExitFullscreen) {
    document.msExitFullscreen();
  }
}

3. 判断是否处于全屏状态

通过 fullscreenElement 判断当前是否有元素处于全屏：

js 复制代码 
function isFullscreen() {
  return document.fullscreenElement || document.webkitFullscreenElement || document.mozFullScreenElement || document.msFullscreenElement;
}

返回值是当前全屏的元素；如果返回 null，说明当前不在全屏状态。

4. 切换全屏（一键 Toggle）

把「进入」和「退出」组合起来，实现点击一次即可来回切换：

js 复制代码 
function toggleFullscreen() {
  if (isFullscreen()) {
    exitFullscreen();
  } else {
    enterFullscreen();
  }
}

四、Vue 3 组合式封装

在 Vue 3 中，可以把以上逻辑封装成一个组合式函数（Composable），配合响应式状态 isFull，让组件使用起来更顺手：

ts 复制代码 
import { ref } from 'vue';

const isFull = ref(false);

function toggleFullscreen(el: HTMLElement = document.documentElement) {
  if (!isFull.value) {
    el.requestFullscreen?.();
    isFull.value = true;
  } else {
    document.exitFullscreen?.();
    isFull.value = false;
  }
}

export { toggleFullscreen, isFull };

在组件里可以直接这样用：

vue 复制代码 
<script setup>
import { toggleFullscreen, isFull } from './useFullscreen';
</script>

<template>
  <button @click="toggleFullscreen()">
    {{ isFull ? '退出全屏' : '进入全屏' }}
  </button>
</template>

五、监听全屏状态变化（可选）

如果用户通过按 Esc 键等方式主动退出全屏，组件的 isFull 状态可能不同步。这时可以监听 fullscreenchange 事件来保持状态一致：

js 复制代码 
document.addEventListener('fullscreenchange', () => {
  console.log('全屏状态变更：', !!document.fullscreenElement);
});

监听事件后，在 Vue 封装中同步更新 isFull 值即可，避免 UI 与真实状态脱节。

六、注意事项与兼容性提示

  • 必须由用户操作触发：进入全屏的调用需要发生在用户手势（如点击）的回调中，否则浏览器会拦截；
  • 前缀兼容：旧版 Safari / Chrome 需要 webkit 前缀，Firefox 用 moz，老 Edge 用 ms，建议统一做降级处理；
  • 状态同步：用户按 Esc 或切换到全屏元素会触发 fullscreenchange，应据此更新组件状态；
  • Promise 与异常：requestFullscreen 返回一个 Promise，全屏失败（如权限被拒）时可 catch 处理，提升健壮性。

七、总结

Fullscreen API 用极少的代码就能实现专业级的全屏体验，核心就四件事：进入、退出、检测、监听。配合 Vue 3 组合式 API 封装成 composable，即可在视频、看图、报表等多个业务场景中复用，是一套值得收藏的通用前端能力。

如果这篇文章对你有帮助，欢迎点赞、收藏、转发。更多前端实用技巧持续更新中。