Fullscreen 全屏控制

dlsjs 提供了一组全屏控制函数：toggleFullscreen 切换全屏状态；requestFullscreen 请求进入全屏；exitFullscreen 退出全屏；isFullscreenActive 检查当前是否处于全屏；getFullscreenElement 获取当前全屏元素；addFullscreenChangeListener 添加全屏状态变化监听器（返回移除监听的函数）。所有函数均兼容不同浏览器前缀（webkit、moz、ms）。

语法

javascript

toggleFullscreen(element)
requestFullscreen(element)
exitFullscreen()
isFullscreenActive()
getFullscreenElement()
addFullscreenChangeListener(callback)

参数

element HTMLElement
- toggleFullscreen 和 requestFullscreen 要设置为全屏的 HTML 元素。toggleFullscreen 非必填，默认为 document.documentElement（整个文档）。
callback Function
- addFullscreenChangeListener 的全屏状态变化回调函数。回调被调用时会传入一个布尔参数 isActive，表示当前是否处于全屏状态。

返回值

toggleFullscreen boolean

操作是否成功发起。进入或退出全屏的请求成功发起时返回 true，参数无效或浏览器不支持时返回 false。

requestFullscreen boolean

进入全屏请求是否成功发起。成功发起返回 true，参数无效或浏览器不支持时返回 false。

exitFullscreen boolean

退出全屏请求是否成功发起。成功发起返回 true，浏览器不支持时返回 false。

isFullscreenActive boolean

当前是否处于全屏模式。true 表示处于全屏，false 表示非全屏。

getFullscreenElement HTMLElement|null

返回当前处于全屏状态的元素；若未处于全屏，返回 null。

addFullscreenChangeListener Function

返回一个移除监听器的函数，调用后即可取消对应的事件监听。若参数无效或浏览器不支持，返回一个空函数。

描述

全屏 API 允许将指定元素（或整个文档）以全屏模式显示，隐藏浏览器 UI。由于历史原因，不同浏览器实现了带前缀的私有 API，dlsjs 的全屏函数内部已统一处理 requestFullscreen、webkitRequestFullscreen、mozRequestFullScreen、msRequestFullscreen 等变体，调用方无需关心浏览器差异。

toggleFullscreen(element)：若当前已全屏则调用 exitFullscreen()，否则调用 requestFullscreen(element)。默认操作整个文档。
requestFullscreen(element)：调用元素对应前缀的 requestFullscreen 方法请求进入全屏。
exitFullscreen()：调用 document 对应前缀的退出全屏方法。
isFullscreenActive()：检查 document.fullscreenElement 及其带前缀的变体是否存在。
getFullscreenElement()：返回 document.fullscreenElement 或带前缀的变体，无则返回 null。
addFullscreenChangeListener(callback)：根据浏览器支持情况选择 fullscreenchange / webkitfullscreenchange / mozfullscreenchange / MSFullscreenChange 事件，回调被调用时传入当前 isFullscreenActive() 的结果。返回的函数用于移除该监听。

注意事项

用户手势要求：进入全屏必须由用户手势（如点击、按键）触发，在脚本中自动调用 requestFullscreen 通常会被浏览器拒绝。
返回值含义：requestFullscreen / exitFullscreen / toggleFullscreen 返回的 true 仅表示"请求已成功发起"，不代表全屏状态已实际切换完成。如需在切换后执行逻辑，请使用 addFullscreenChangeListener。
浏览器前缀：函数内部已处理 webkit、moz、ms 前缀，无需调用方关心。
参数校验：toggleFullscreen 和 requestFullscreen 接收非 HTMLElement 时会输出 dlsjs 警告并返回 false。
退出全屏只能通过 document：exitFullscreen 操作的是 document，不接受元素参数。
监听器移除：addFullscreenChangeListener 返回的移除函数应妥善保存，在组件销毁或不再需要时调用，避免内存泄漏。
iOS Safari 限制：iOS Safari 对全屏 API 的支持有限，requestFullscreen 在 iPhone 上通常不生效，iPad 部分版本支持视频元素全屏。
全屏中切换标签页：切换到其他标签页或窗口失焦时，浏览器可能自动退出全屏。

示例

切换全屏

操作指定元素

监听全屏变化

浏览器兼容性

API	Chrome	Firefox	Safari	Edge	IE
`requestFullscreen`（标准）	15+（前缀）/ 69+（无前缀）	10+（前缀）/ 64+（无前缀）	5.1+（前缀）/ 16.4+（无前缀）	12+（前缀）/ 79+（无前缀）	11+（`ms` 前缀）
`exitFullscreen`	同上	同上	同上	同上	同上
`fullscreenElement`	同上	同上	同上	同上	同上
`fullscreenchange` 事件	同上	同上	同上	同上	同上

iOS 限制

iOS Safari 对 Fullscreen API 支持有限，iPhone 上 requestFullscreen 通常不生效；iPad 部分版本仅支持视频元素全屏。如需在 iOS 上全屏播放视频，建议使用 <video> 元素的 webkitEnterFullscreen。

性能考虑

时间复杂度: O(1) - 所有函数均为直接调用浏览器 API 或访问属性，无循环操作。
异步特性：进入/退出全屏是异步过程，requestFullscreen 返回 true 后全屏状态并不会立即生效，需通过 addFullscreenChangeListener 监听实际变化。
事件监听开销：addFullscreenChangeListener 仅注册一次事件，开销极低；但应在不需要时调用返回的移除函数，避免内存泄漏。

Fullscreen 全屏控制 ​

语法 ​

参数 ​

返回值 ​

描述 ​

注意事项 ​

示例 ​

切换全屏 ​

操作指定元素 ​

监听全屏变化 ​

浏览器兼容性 ​

性能考虑 ​

相关函数 ​