本文介绍在 Vue 3 中正确监听文档全屏状态的方法，解决直接 watch(document.fullscreenElement) 报错的问题，推荐使用原生 fullscreenchange 事件或 VueUse 的 useFullscreen 组合式函数实现可靠、响应式的全屏检测。
本文介绍在 vue 3 中正确监听文档全屏状态的方法，解决直接 `watch(document.fullscreenelement)` 报错的问题，推荐使用原生 `fullscreenchange` 事件或 vueuse 的 `usefullscreen` 组合式函数实现可靠、响应式的全屏检测。
在 Vue 3 中，watch() API 仅支持可响应式源（如 ref、reactive 对象、getter 函数或其数组），而 document.fullscreenElement 是一个只读属性，且本身不具备响应性——因此直接传入 watch() 会触发 Vue 警告：Invalid watch source: null 或 Invalid watch source: document.fullscreenElement。
✅ 正确做法是借助浏览器原生的全屏事件机制。document 对象提供了标准的 fullscreenchange 事件，每当全屏状态切换（进入或退出）时自动触发。你可以在 onMounted 中添加事件监听，并在 onUnmounted 中清理，确保无内存泄漏：
import { ref, onMounted, onUnmounted } from 'vue'
const fullScreenActivated = ref<boolean>(false)
onMounted(() => {
const handleFullscreenChange = () => {
fullScreenActivated.value = !!document.fullscreenElement
}
document.addEventListener('fullscreenchange', handleFullscreenChange)
// 清理：移除事件监听器
onUnmounted(() => {
document.removeEventListener('fullscreenchange', handleFullscreenChange)
})
})</boolean>
⚠️ 注意：document.fullscreenElement 在非全屏时为 null，因此使用 !! 进行布尔转换是最简洁可靠的判断方式；避免误用已废弃的 document.webkitIsFullScreen 等私有属性。
? 更进一步，推荐使用社区成熟方案 —— VueUse 提供的 useFullscreen 组合式函数。它已封装事件监听、跨浏览器兼容性（自动处理 webkit, moz, ms 前缀）及响应式状态管理，一行代码即可获得完整能力：
import { useFullscreen } from '@vueuse/core'
const { isFullscreen, enter, exit, toggle } = useFullscreen()
// isFullscreen 是 ref<boolean>，可直接在模板中使用
// <button>切换全屏</button>
// <span>{{ isFullscreen ? '当前全屏' : '未全屏' }}</span></boolean>
✅ 优势总结：
- 自动绑定/解绑 fullscreenchange 和 fullscreenerror 事件；
- 兼容 Chrome/Firefox/Safari/Edge 等主流浏览器；
- 提供 enter()、exit()、toggle() 方法，开箱即用；
- 返回的 isFullscreen 是响应式 ref，天然支持 watch 和模板响应式更新。
综上，切勿尝试对原生 DOM 属性做直接 watch；应始终通过事件驱动 + 响应式状态桥接的方式实现 UI 与浏览器状态的同步。这是 Vue 3 与底层 Web API 协作的标准实践。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
