Vue 2 兼容性

软件包版本

支持 Vue 2.4.0 及以上的 Vue 2 版本，使用 vue-fullscreen@legacy。本文接口参考版本为 4.0.0。

Fullscreen API 浏览器支持

原生全屏由浏览器提供。完整版本列表见 Can I use：Fullscreen API，设备限制见 MDN 的 requestFullscreen 兼容性表。以下为常见环境概览。

浏览器 / 设备	原生全屏支持
桌面 Chrome / Edge	Chrome 71+、Edge 79+ 支持标准 API
桌面 Firefox	64+ 支持标准 API
macOS Safari	16.4+ 支持标准 API；更早版本有带前缀的部分支持
iPad Safari	iPadOS 16.4+ 支持标准 API，但有设备限制；较早版本有带前缀的部分支持
iPhone Safari	不支持任意元素的 Fullscreen API；使用网页全屏
Android Chrome / Firefox	当前版本支持，具体版本见支持表
Internet Explorer	IE 11 通过带 ms 前缀的 API 支持；不可用时使用网页全屏

表中的版本号描述浏览器 API，不是本组件包的最低浏览器版本或实机测试承诺。本包的 UMD/CJS 构建使用 ES5 语法，ESM 构建保留模块声明，供应用打包器处理。底层 screenfull 处理部分浏览器前缀差异，但不能补齐浏览器缺失的全屏能力。

Safari 与移动设备

iPad 原生全屏会显示浏览器提供的退出控件，下滑等系统手势也可能退出。iPhone 的视频播放器全屏是独立能力，不代表图表、普通 div 或整个页面可以原生全屏。Safari 16.4 的改动可参阅 WebKit 发布说明。

Internet Explorer

Vue 2 发布文件使用 ES5 语法，主入口不会自动加载全局 polyfill。需要 IE 11 时，可以选择以下任意一种方式。

引入本包提供的 polyfill

在应用入口中，先引入 polyfill，再引入组件包：

import 'vue-fullscreen/polyfills'
import Vue from 'vue'
import VueFullscreen from 'vue-fullscreen'

Vue.use(VueFullscreen)

CommonJS 项目可先执行 require('vue-fullscreen/polyfills')，再执行 require('vue-fullscreen')。

普通网页按下面顺序加载，路径表示从安装的软件包中复制出的文件：

<script src="/vendor/vue-fullscreen/polyfills.js"></script>
<script src="/vendor/vue/dist/vue.js"></script>
<script src="/vendor/vue-fullscreen/index.umd.js"></script>

保持脚本执行顺序，不要添加 async。IE 无法直接加载 ESM。可选入口会在全局环境中补齐缺失能力，已标记为具有副作用，打包器会保留显式引入。

使用应用已有的 polyfill

如果应用已经提供以下能力，就无需重复引入本包的 polyfill：

• Promise，包括 Promise.prototype.finally；
• WeakMap；
• Symbol 和 Symbol.iterator；
• 数组迭代能力，包括 Array.prototype.entries；
• Object.assign。

例如，可以在应用入口先全局引入 core-js/stable，再加载组件包。仅在模块内生效的 ponyfill 或只补 Promise 的方案不能覆盖全部要求。如果使用动态加载，应先等 polyfill 加载完成，再动态导入组件。

具备这些能力的现代浏览器无需引入可选入口。应用代码、Vue 2 和其他依赖仍需兼容 IE 11；这些 polyfill 不能让 Vue 3 支持 IE。

自动检查覆盖产物 ES5 语法，以及模拟缺失能力、ms 前缀全屏 API、网页降级、DOM 恢复和指令错误事件。这不是 IE 浏览器实机测试，部署前仍需在 IE 11 中验证实际应用。不支持 IE 10 及更早版本。VitePress 文档站和 Vite 示例页面本身需要现代浏览器。

用户操作与 iframe 权限

原生全屏只能由点击、触摸或按键等用户操作触发。不要先等待网络请求再调用全屏 API，以免用户激活状态过期。

嵌入页面需要允许全屏，例如：

<iframe src="/example/" allow="fullscreen" allowfullscreen></iframe>

父页面的 Permissions-Policy 仍可能限制全屏；仅添加 iframe 属性不能覆盖更严格的响应头策略。

能力检测与网页全屏降级

在浏览器中读取 fullscreen.isEnabled 可判断当前文档是否允许使用原生全屏。它不表示是否已经进入全屏，也不保证下一次请求一定成功。

import { fullscreen } from 'vue-fullscreen'

// 在组件挂载后或用户点击时读取
const nativeAvailable = fullscreen.isEnabled

• 原生全屏不可用时，组件、指令和 API 自动使用网页全屏。
• 显式设置 pageOnly: true（组件属性为 page-only）时，始终使用网页全屏。
• 原生能力可用但请求被拒绝时，会报告错误并恢复 DOM，不会静默降级。API 调用应捕获 Promise 拒绝，组件使用 error 事件，指令使用 fullscreen-error 事件。

网页全屏保留浏览器工具栏，只覆盖当前文档的视口。在 iframe 内，它只能覆盖 iframe 区域；teleport 也只会移动到该文档的 body，不能突破 iframe 边界。