前端【免费下载链接】screenfullSimple wrapper for cross-browser usage of the JavaScript Fullscreen API项目地址https://gitcode.com/gh_mirrors/sc/screenfull点击查看免费下载本文围绕开源仓库 screenfull 的官方文档展开系统讲解这一「简单包装器Simple wrapper」如何封装浏览器原生 Fullscreen API、抹平各厂商前缀差异并给出完整的安装、API 参考、实战示例与源码级原理剖析。读完本文你将能够用统一、极简的 API 在任意支持的浏览器中实现页面或指定元素的全屏切换并正确处理移动端、iframe、jQuery 与 Angular 等场景。screenfull 是一个「功能已完整、不再接受新特性」的成熟库readme.md其核心价值在于用 0.7 kBgzipped的体积把标准、WebKit、旧 WebKit、Mozilla、Microsoft 五套 Fullscreen API 前缀差异全部封装掉让你无需关心webkitRequestFullscreen还是mozRequestFullScreen统一调用screenfull.request()即可。一、安装与版本选择screenfull 仅依赖浏览器原生 Fullscreen API没有任何运行时依赖安装极其简单npm install screenfull安装后体积约0.7 kBgzippedreadme.md。关于 ESM 的重要说明当前版本的 screenfull 是纯 ESMECMAScript Module包package.json 中type: module且exports: ./index.js这意味着你可以直接使用import screenfull from screenfull引入如果项目处于 CommonJS 环境或需要在不经过转译transpilation的情况下支持旧浏览器官方明确建议改用 5.2.0 版本readme.md从 package.json 的engines字段可以看到Node.js 环境要求^14.13.1 || 16.0.0。基本引入方式import screenfull from screenfull; if (screenfull.isEnabled) { screenfull.request(); }二、为什么需要 screenfull与原生 API 的对比这是理解 screenfull 价值的最好入口。官方文档readme.md给出了同一需求的两版代码对比。使用 screenfullimport screenfull from screenfull; if (screenfull.isEnabled) { screenfull.request(); }使用原生 JavaScriptdocument.fullscreenEnabled document.fullscreenEnabled || document.mozFullScreenEnabled || document.documentElement.webkitRequestFullScreen; function requestFullscreen(element) { if (element.requestFullscreen) { element.requestFullscreen(); } else if (element.mozRequestFullScreen) { element.mozRequestFullScreen(); } else if (element.webkitRequestFullScreen) { element.webkitRequestFullScreen(Element.ALLOW_KEYBOARD_INPUT); } } if (document.fullscreenEnabled) { requestFullscreen(document.documentElement); } // This is not even entirely comprehensive. Theres more.正如文档所注原生方案「甚至还不全面还有更多细节」。浏览器厂商各自实现过带前缀的 API属性名、方法名、事件名、甚至exit在不同浏览器中叫exitFullscreen、mozCancelFullScreen、webkitCancelFullScreen……而 screenfull 在底层将这些差异集中收纳进一张「方法映射表」对外暴露一套统一 API。三、浏览器支持情况所有支持 Fullscreen API 的现代浏览器均可使用文档引用了 caniuse 的 fullscreen 兼容性数据特别说明Safari 在桌面端和 iPad 上受支持但在 iPhone 上不受支持。这是浏览器本身的限制不是 screenfull 的缺陷readme.md。iframe 中的使用前提如果你的页面位于iframe内要进入全屏必须给 iframe 标签加上allowfullscreen属性以及兼容旧浏览器的webkitallowfullscreen和mozallowfullscreen。这一点同时影响.request()与.isEnabled两个 API 的表现下文会再次提到。四、完整 API 参考screenfull 对外暴露的全部 API 均可在 index.d.ts 的类型声明中看到其方法签名与 index.js 的实现一一对应。.request(element, options?)让指定元素进入全屏。element默认是html文档根元素如果传入的是当前全屏元素的子元素会切换到该元素非子元素则不会切换options标准FullscreenOptions对象即原生 Fullscreen API 的选项返回一个 Promise在元素进入全屏后 resolve。import screenfull from screenfull; document.getElementById(button).addEventListener(click, () { if (screenfull.isEnabled) { screenfull.request(); } else { // 忽略或做其他处理 } });重要约束浏览器只允许在用户手势click、touch、key 等发起的回调中进入全屏request()必须由用户事件触发。.exit()退出全屏。返回一个 Promise在元素退出全屏后 resolve。await screenfull.exit();从源码index.js可以看到exit()会先判断screenfull.isFullscreen若当前不在全屏状态则立即 resolve避免无意义的调用。.toggle(element, options?)如果当前不在全屏则请求进入否则退出全屏。参数与.request()一致DOM 元素 FullscreenOptions返回一个 Promise在元素进入/退出全屏后 resolve。源码index.js的实现非常简洁本质上是对上面两个方法的三元选择toggle(element, options) { return screenfull.isFullscreen ? screenfull.exit() : screenfull.request(element, options); },.on(event, function) 与 .off(event, function)事件类型仅有两个change | errorindex.d.ts 中EventName类型change浏览器在全屏状态之间切换时触发error全屏操作发生错误时触发.on()注册监听器.off()移除之前注册的监听器。import screenfull from screenfull; // 监听全屏状态变化 if (screenfull.isEnabled) { screenfull.on(change, () { console.log(Am I fullscreen?, screenfull.isFullscreen ? Yes : No); }); } // 监听全屏错误 if (screenfull.isEnabled) { screenfull.on(error, event { console.error(Failed to enable fullscreen, event); }); } // 移除监听器 screenfull.off(change, callback);从 index.js 可以看到.on/.off内部会根据eventNameMap把逻辑事件名映射到浏览器实际的前缀事件名再调用document.addEventListener/removeEventListener的第三个参数为false冒泡阶段。.onchange(function) 与 .onerror(function)分别是.on(change, function)和.on(error, function)的简写别名由 index.js 直接转发实现onchange(callback) { screenfull.on(change, callback); }, onerror(callback) { screenfull.on(error, callback); },.isFullscreen布尔值表示当前是否处于全屏状态。注意它是一个getter 属性见 index.js内部通过Boolean(document[nativeAPI.fullscreenElement])实时读取。.element返回当前处于全屏状态的元素若不在全屏状态则返回undefined。同样由 getter 实现document[nativeAPI.fullscreenElement] ?? undefinedindex.js。.isEnabled布尔值表示当前是否被允许进入全屏。iframe 中需要allowfullscreen等属性才会为true。其 getter 为Boolean(document[nativeAPI.fullscreenEnabled])注释特别说明「Coerce to boolean in case of old WebKit」即对旧 WebKit 的非布尔返回值做强制布尔化处理index.js。.raw暴露内部实际使用的「带前缀的原始属性名」共六项requestFullscreen、exitFullscreen、fullscreenElement、fullscreenEnabled、fullscreenchange、fullscreenerrorindex.js。在 index.d.ts 中对应RawEventNames类型全部为readonly string。当你需要直接访问浏览器原生 API 时比如做更底层的控制可通过screenfull.raw拿到真正的属性名。五、实战示例从页面到元素的六种全屏场景以下示例均来自官方文档readme.md可直接复制运行。1. 全屏整个页面默认即全屏html根元素import screenfull from screenfull; document.getElementById(button).addEventListener(click, () { if (screenfull.isEnabled) { screenfull.request(); } else { // Ignore or do something else } });2. 全屏指定元素传入任意 DOM 元素import screenfull from screenfull; const element document.getElementById(target); document.getElementById(button).addEventListener(click, () { if (screenfull.isEnabled) { screenfull.request(element); } });3. 移动端隐藏导航 UI通过FullscreenOptions的navigationUI选项控制移动端导航界面import screenfull from screenfull; const element document.getElementById(target); document.getElementById(button).addEventListener(click, () { if (screenfull.isEnabled) { screenfull.request(element, {navigationUI: hide}); } });4. 用 jQuery 全屏一个元素jQuery 集合需先取出原始 DOM 节点import screenfull from screenfull; const element $(#target)[0]; // Get DOM element from jQuery collection $(#button).on(click, () { if (screenfull.isEnabled) { screenfull.request(element); } });5. 点击图片切换全屏jQueryimport screenfull from screenfull; $(img).on(click, event { if (screenfull.isEnabled) { screenfull.toggle(event.target); } });6. 监听全屏状态变化与错误见上文.on(change)与.on(error)示例。官方演示页 index.html 给出了一个完整的联动示例监听change事件后根据screenfull.element实时刷新页面上「当前全屏元素」的显示文本function fullscreenchange() { const {element} screenfull; // 更新状态文本... if (element) { $(#element).text(Element: ${element.localName}${element.id ? #${element.id} : }); } } screenfull.on(change, fullscreenchange);六、框架集成Angular.js 与 Angular 2 指令封装Angular.jsAngularJS 1.x官方文档推荐使用社区封装的 angular-screenfull 绑定可以在模板中直接声明式使用div ngsf-fullscreen pThis is a fullscreen element/p button ngsf-toggle-fullscreenToggle fullscreen/button /divAngular 2现代 Angular可以直接用Directive封装成自定义指令把全屏逻辑收敛到指令内部import {Directive, HostListener} from angular/core; import screenfull from screenfull; Directive({ selector: [toggleFullscreen] }) export class ToggleFullscreenDirective { HostListener(click) onClick() { if (screenfull.isEnabled) { screenfull.toggle(); } } }button toggleFullscreenToggle fullscreenbutton七、源码原理剖析screenfull 如何抹平浏览器差异1. 前缀探测methodMap 与 nativeAPI核心机制是 index.js 顶部的methodMap数组——按「标准 → 新 WebKit → 旧 WebKit → Mozilla → Microsoft」五个梯队组织六类 API 名称梯队进入全屏退出全屏全屏元素是否可用change 事件error 事件标准requestFullscreenexitFullscreenfullscreenElementfullscreenEnabledfullscreenchangefullscreenerror新 WebKitwebkitRequestFullscreenwebkitExitFullscreenwebkitFullscreenElementwebkitFullscreenEnabledwebkitfullscreenchangewebkitfullscreenerror旧 WebKitwebkitRequestFullScreenwebkitCancelFullScreenwebkitCurrentFullScreenElementwebkitCancelFullScreenwebkitfullscreenchangewebkitfullscreenerrorMozillamozRequestFullScreenmozCancelFullScreenmozFullScreenElementmozFullScreenEnabledmozfullscreenchangemozfullscreenerrorMicrosoftmsRequestFullscreenmsExitFullscreenmsFullscreenElementmsFullscreenEnabledMSFullscreenChangeMSFullscreenError然后通过nativeAPI立即执行检测index.js遍历methodMap只要发现某个梯队的退出全屏方法存在于document上就认定该浏览器使用这一套前缀并把整套真实属性名映射到「标准名」上返回。因此无论底层叫什么screenfull 对外永远统一。2. Promise 化的事件驱动实现.request()index.js没有直接依赖原生返回值而是采用事件驱动 Promise 包装策略先注册一次性的change监听器onFullScreenEntered调用elementnativeAPI.requestFullscreen如果原生方法返回的是 Promise新标准浏览器则通过.then(onFullScreenEntered)收尾.catch(reject)兜底错误。.exit()index.js采用同样模式。这种双轨设计保证了即便在不返回 Promise 的旧前缀实现上也能通过change事件获得一致的 Promise 语义。3. 优雅降级与 SSR 安全如果typeof document undefinedNode/SSR 环境nativeAPI直接返回falseindex.js如果当前浏览器根本不支持 Fullscreen API最终导出的screenfull会被整体替换为{isEnabled: false}index.js任何调用都不会抛错便于你按isEnabled做无全屏时的降级 UI。4. 状态属性为何用 getter 实现isFullscreen、element、isEnabled三个状态全部通过Object.defineProperties定义为getter 而非静态值index.js每次访问都实时读取document上的状态从而保证change事件回调里拿到的永远是最新状态。八、TypeScript 类型支持screenfull 自带完整类型声明 index.d.ts开箱即用EventName change | error约束事件名RawEventNamesraw属性对应的六项字符串类型所有方法均标注返回类型如request(element?: Element, options?: FullscreenOptions): Promisevoid。类型测试位于 index.test-d.ts通过tsd断言了全部 API 的签名request/toggle/exit返回Promisevoidon/off/onchange/onerror的 handler 参数为Eventraw各字段均为string。项目质量检查脚本package.json 的test: xo tsd同时运行xolint与tsd类型测试从测试写法即可放心地把screenfull用在严格类型检查的项目中。九、FAQ全屏状态下如何跳转到新页面问题全屏时如何导航到新页面答案出于安全原因浏览器不支持在全屏状态下直接跳转页面。官方文档readme.md给出的变通方案是——创建一个铺满屏幕的无缝 iframe在 iframe 内部加载新页面import screenfull from screenfull; document.querySelector(#new-page-button).addEventListener(() { const iframe document.createElement(iframe) iframe.setAttribute(id, external-iframe); iframe.setAttribute(src, https://new-page-website.com); iframe.setAttribute(frameborder, no); iframe.style.position absolute; iframe.style.top 0; iframe.style.right 0; iframe.style.bottom 0; iframe.style.left 0; iframe.style.width 100%; iframe.style.height 100%; document.body.prepend(iframe); document.body.style.overflow hidden; });演示页 index.html 中还在fullscreenchange回调里做了配套清理当退出全屏!screenfull.isFullscreen时移除#external-iframe并恢复document.body.style.overflow auto避免残留元素遮挡页面。十、使用注意事项与最佳实践先判断再调用所有全屏操作前都应检查screenfull.isEnabled这在 iframe、iPhone Safari 等受限场景下尤为重要必须由用户手势触发request()需要在 click、touch、key 事件回调中调用否则会被浏览器拒绝并触发error事件及时清理监听器使用.on()注册后记得在合适时机用.off()移除避免内存泄漏和重复回调iframe 场景给 iframe 添加allowfullscreen以及旧浏览器的webkitallowfullscreen、mozallowfullscreen属性版本选择ESM 环境使用当前版本CommonJS 或需兼容未转译旧浏览器时使用 5.2.0降级体验isEnabled false时不要隐藏按钮应改为提示「当前环境不支持全屏」或直接忽略操作。延伸阅读项目类型声明与实现index.d.ts、index.js类型测试index.test-d.ts官方演示页面包含 Request / Exit / Toggle 按钮与图片全屏示例index.html许可证MITlicensescreenfull 的定位非常克制——它只做一件事统一跨浏览器全屏 API并且做到极致。理解了methodMap探测机制与 Promise 包装策略后你不仅能熟练使用它也能在遇到类似「前缀差异 API 统一封装」需求时复用同样的设计思路。赞分享前端【免费下载链接】screenfullSimple wrapper for cross-browser usage of the JavaScript Fullscreen API项目地址https://gitcode.com/gh_mirrors/sc/screenfull点击查看免费下载相关推荐大屏展示系统开发screenfull多显示器全屏控制方案大屏展示系统开发screenfull多显示器全屏控制方案 在数据可视化和监控系统开发中多显示器环境下的全屏控制一直是前端工程师面临的棘手问题。不同浏览器对全前端Screenfull全屏API跨浏览器兼容解决方案Screenfull全屏API跨浏览器兼容解决方案 在现代Web开发中全屏体验已成为提升用户体验的重要一环。Screenfull作为JavaScript全屏A前端vum框架性能优化终极指南提升移动端应用加载速度的5个简单方法vum框架性能优化终极指南提升移动端应用加载速度的5个简单方法 在移动端开发中性能优化是决定用户体验的关键因素。vum框架作为基于Vue.js的移动端UI框创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考