萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

JavaScript 控制瀏覽器全屏模式:Fullscreen API 完整封裝與兼容方案

Fullscreen API 標準流程

現代瀏覽器(Chrome 15+、Firefox 10+、Safari 5.1+、Edge 12+)支援 **Fullscreen API**,核心方法:

  • `element.requestFullscreen()` — 進入全屏
  • `document.exitFullscreen()` — 退出全屏
  • `document.fullscreenElement` — 當前全屏元素
  • `document.fullscreenEnabled` — 是否允許全屏
  • 事件:`fullscreenchange`、`fullscreenerror`

完整跨瀏覽器封裝類

class FullscreenManager {
  constructor() {
    this._prefixes = ['', 'webkit', 'moz', 'ms'];
    this._props = {
      request: 'requestFullscreen',
      exit: 'exitFullscreen',
      element: 'fullscreenElement',
      enabled: 'fullscreenEnabled',
      event: 'fullscreenchange'
    };
    this._initPrefixedProps();
  }
  
  _initPrefixedProps() {
    const doc = document;
    for (const prefix of this._prefixes) {
      const req = prefix ? prefix + 'RequestFullScreen' : 'requestFullscreen';
      if (req in doc.documentElement) {
        this._props.request = req;
        this._props.exit = prefix + 'ExitFullscreen';
        this._props.element = prefix + 'FullscreenElement';
        this._props.enabled = prefix + 'FullscreenEnabled';
        this._props.event = prefix.toLowerCase() + 'fullscreenchange';
        break;
      }
    }
  }
  
  // 進入全屏
  async enter(element = document.documentElement) {
    if (!this.isEnabled) throw new Error('Fullscreen not enabled');
    try {
      await element[this._props.request]();
    } catch (err) {
      // 用戶拒絕、非用戶手勢觸發等
      throw new Error(`Enter fullscreen failed: ${err.message}`);
    }
  }
  
  // 退出全屏
  async exit() {
    if (!this.isFullscreen) return;
    try {
      await document[this._props.exit]();
    } catch (err) {
      throw new Error(`Exit fullscreen failed: ${err.message}`);
    }
  }
  
  // 切換
  async toggle(element = document.documentElement) {
    if (this.isFullscreen) await this.exit();
    else await this.enter(element);
  }
  
  get isFullscreen() {
    return !!document[this._props.element];
  }
  
  get isEnabled() {
    return !!document[this._props.enabled];
  }
  
  get currentElement() {
    return document[this._props.element] || null;
  }
  
  // 監聽變化
  onChange(callback) {
    document.addEventListener(this._props.event, callback);
    return () => document.removeEventListener(this._props.event, callback);
  }
}

// 使用
const fs = new FullscreenManager();

document.getElementById('btnFullscreen').addEventListener('click', async () => {
  try {
    await fs.enter(document.getElementById('player')); // 讓播放器全屏
  } catch (e) {
    console.warn(e.message);
  }
});

fs.onChange(() => {
  console.log('全屏狀態:', fs.isFullscreen ? '開啟' : '關閉', '元素:', fs.currentElement);
});

IE 兼容方案(已淘汰,僅維護舊專案)

// 原文 ActiveXObject 方案(僅 IE)
function legacyIEFullscreen() {
  if (typeof window.ActiveXObject !== 'undefined') {
    try {
      const wscript = new ActiveXObject('WScript.Shell');
      if (wscript) wscript.SendKeys('{F11}'); // 模擬按鍵
    } catch (e) {
      // 安全策略阻擋
    }
  }
}
// ⚠️ 此方案極不推薦:需用戶降低安全設置、易被殺毒攔截、不支援元素級全屏

常見場景與最佳實踐

1. 視頻播放器全屏

<video id="player" controls><source src="video.mp4"></video>
<button id="fsBtn">全屏</button>

const player = document.getElementById('player');
const btn = document.getElementById('fsBtn');
const fs = new FullscreenManager();

btn.onclick = async () => {
  if (fs.isFullscreen) await fs.exit();
  else await fs.enter(player);
};

fs.onChange(() => {
  btn.textContent = fs.isFullscreen ? '退出全屏' : '全屏';
});

2. 絕對定位元素全屏(避免布局塌陷)

.fullscreen-wrapper {
  position: fixed;
  top: 0; left: 0; right: 0; bottom: 0;
  z-index: 9999;
  background: black;
  display: flex;
  align-items: center;
  justify-content: center;
}

3. 用戶手勢要求

瀏覽器**強制要求** `requestFullscreen()` 必須在**用戶交互事件**(click、keydown、touchstart)的回調中調用,否則拋出 `NotAllowedError`。異步操作(setTimeout、Promise.then、fetch 後)會失去用戶手勢上下文。

4. iframe 跨域全屏

<iframe src="..." allow="fullscreen"></iframe>
// 父頁面需在 iframe 上設定 allow="fullscreen"
// 子頁面內部調用 requestFullscreen() 即可

CSS 全屏偽類(樣式微調)

/* 全屏元素本身 */
:fullscreen, :-webkit-full-screen, :-moz-full-screen, :-ms-fullscreen {
  background: black;
}

/* 全屏元素的後代 */
:fullscreen .ui-controls { opacity: 1; }

/* 瀏覽器自動添加的 backdrop(部分瀏覽器) */
::backdrop { background: rgba(0,0,0,0.8); }

結語

Fullscreen API 已成熟標準化,**拋棄 ActiveX 模擬 F11**,使用標準 API 封裝類統一處理前綴、Promise 化、事件監聽。注意「用戶手勢」硬性要求,並在 CSS 中利用 `:fullscreen` 偽類微調全屏狀態下的樣式。

copyright © 萬盛學電腦網 all rights reserved