Vant 组合式 API 详解usePageVisibility 页面可见状态监听【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantusePageVisibility是 Vant 底层依赖包vant/use提供的一个组合式 API用于在 Vue 3 项目中获取页面的可见状态visible/hidden。在移动端 Web 开发中它常用于处理「页面切换到后台自动暂停播放、回到前台自动恢复」这类场景例如 Vant 的 Swipe 轮播组件就是基于它实现自动播放的暂停与恢复。读完本文你将掌握该 API 的完整用法、返回值语义、底层实现原理以及在真实组件中的应用方式。一、什么是 usePageVisibilityusePageVisibility是一个封装了浏览器 Page Visibility API 的组合式函数返回一个类型为RefVisibilityState的响应式引用实时反映页面当前的可见状态visible页面当前可见用户正在浏览当前标签页hidden页面当前不可见例如切换到其他标签页、最小化浏览器、或 App 切入后台该 API 属于 Vant 对外提供的组合式 API 家族之一与useWindowSize、useEventListener、useCountDown等一同维护在 packages/vant-use 包中并通过 packages/vant-use/src/index.ts 统一对外导出。Vant 组件库自身也重度依赖这些 API因此「Vant 用户复用它们」是官方文档明确推荐的用法见 vant-use-intro.zh-CN.md。二、安装与引入虽然vant/use已经作为 Vant 的依赖随包安装官方仍然推荐显式安装它以获得独立的类型提示和版本管理# with npm npm i vant/use # with yarn yarn add vant/use # with pnpm pnpm add vant/use # with Bun bun add vant/use该包以 Vue 3 为 peer 依赖vue: ^3.0.0见 packages/vant-use/package.json模块格式同时提供 ESMdist/index.js与 CJSdist/index.cjs并带有完整的 TypeScript 类型声明dist/index.d.ts因此可以直接获得VisibilityState等类型的自动补全。三、基本用法在 Vue 3 组件的setup中调用usePageVisibility()即可获取页面可见状态配合watch监听状态变化import { watch } from vue; import { usePageVisibility } from vant/use; export default { setup() { const pageVisibility usePageVisibility(); watch(pageVisibility, (value) { console.log(visibility: , value); }); }, };当用户切换标签页或最小化窗口时控制台会打印出visibility: hidden重新回到页面时打印visibility: visible。由于返回值本身就是一个Ref你也可以使用script setup语法并直接以pageVisibility.value读取当前状态或在模板中通过pageVisibility响应式渲染。典型应用自动暂停耗时任务实际业务中页面不可见时应当主动释放资源或暂停高频操作如轮询请求、倒计时、动画避免后台运行时造成不必要的性能开销与流量消耗import { watch, onBeforeUnmount } from vue; import { usePageVisibility } from vant/use; const pageVisibility usePageVisibility(); let timer null; watch(pageVisibility, (value) { if (value visible) { startPolling(); } else { stopPolling(); } }); onBeforeUnmount(stopPolling);四、API 详解类型定义type VisibilityState visible | hidden; function usePageVisibility(): RefVisibilityState;返回值参数说明类型visibilityState页面当前的可见状态visible为可见hidden为隐藏RefVisibilityState几个值得注意的使用细节返回值是模块级单例usePageVisibility内部将响应式状态缓存为模块级变量源码见 packages/vant-use/src/usePageVisibility/index.ts这意味着在同一个页面中多次调用该函数返回的是同一个Ref对象状态全局共享且不会重复绑定事件监听避免内存泄漏与多余开销。可在 setup 之外调用由于不依赖组件实例上下文它同样可以像useWindowSize一样在普通模块或工具函数中调用。初始值语义首次调用时状态初始化为visible随后在浏览器环境下立即依据document.hidden同步一次真实状态。也就是说如果页面一开始就处于隐藏状态例如页面在后台被打开第一次读取即可拿到正确的hidden而非固定为visible。SSR 安全在非浏览器环境下typeof window undefined函数只返回初始的visible状态不会尝试访问document因此可以安全地用于服务端渲染场景。五、底层实现原理usePageVisibility的完整实现只有短短 20 余行packages/vant-use/src/usePageVisibility/index.ts却清晰地展示了三个关键设计import { ref, Ref } from vue; import { inBrowser } from ../utils; type VisibilityState hidden | visible; let visibility: RefVisibilityState; export function usePageVisibility() { if (!visibility) { visibility refVisibilityState(visible); if (inBrowser) { const update () { visibility.value document.hidden ? hidden : visible; }; update(); window.addEventListener(visibilitychange, update); } } return visibility; }1. 懒初始化单例模式利用模块级变量visibility做缓存if (!visibility)保证事件监听只注册一次。这与 changelog 中「Improve usePageVisibility event bindings performance」packages/vant-use/changelog.md的记录相吻合说明该实现正是为了优化重复调用时的绑定性能。2. 数据来源与事件驱动状态的唯一数据源是document.hidden状态更新由浏览器的visibilitychange事件驱动。每次事件触发时执行update函数将document.hidden映射为hidden | visible并写入ref从而驱动 Vue 的响应式更新。值得说明的是浏览器原生 Page Visibility API 还提供document.visibilityState其取值为visible、hidden、prerender等而 Vant 选择只关心二值状态简化了上层使用的心智负担。3. 环境守卫inBrowser来自 packages/vant-use/src/utils.ts 中的typeof window ! undefined判断配合首次调用即执行update()的逻辑既保证了 SSR 下的安全执行又确保了首帧状态正确。六、源码级应用案例Swipe 自动播放的暂停与恢复usePageVisibility并非一个「只存在于文档中的 API」Vant 核心组件 Swipe轮播就把它作为自动播放的核心控制逻辑。在 packages/vant/src/swipe/Swipe.tsx 中watch(usePageVisibility(), (visible) { if (visible visible) { autoplay(); } else { stopAutoplay(); } });这段代码体现了非常典型的实战模式页面可见时调用autoplay()启动轮播定时器页面隐藏切后台、锁屏时调用stopAutoplay()停止定时器回到页面后再次自动恢复播放无需用户手动干预。这验证了usePageVisibility的核心价值用几行代码将「页面生命周期」与「业务行为」解耦让任何需要感知页面可见性的业务视频播放、倒计时、动画、轮询都能以统一的方式实现。七、注意事项兼容性前提该 API 依赖浏览器的 Page Visibility API 与visibilitychange事件主流现代浏览器均支持在使用前可确认目标运行环境WebView、浏览器版本对document.hidden的支持情况。不要在 watch 回调中做重型同步操作visibilitychange在移动端可能伴随系统级事件频繁触发回调中应只做轻量状态切换重型逻辑建议异步执行。单例共享语义由于返回的是模块级共享的Ref不同组件监听的是同一状态源适合「全局只需要一份可见性状态」的场景无需自行做状态提升。综上usePageVisibility以极小的 API 面一个函数、一个返回对象解决了移动端开发中高频出现的「感知页面前后台切换」问题配合 packages/vant/docs/markdown/use-page-visibility.en-US.md 中的英文说明与 packages/vant/docs/markdown/vant-use-intro.zh-CN.md 的 API 总览你可以快速在业务中落地使用。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考