如何在JavaScript中使用全屏API（并通过“唤醒锁API”使屏幕保持处于唤醒状态）

我的经验是：直接尝试使用真正的API，如果请求被拒绝，那就立即启用CSS中的备用方案。

function enterFullscreen(el) {
  if (fs.enabled) {
    return fs.request(el).catch(() => {
      // API可用，但被拒绝了——此时就改用固定的覆盖层来达到全屏效果。
      document.body.classList.add('pseudo-fullscreen');
    });
  }
  document.body.classList.add('pseudo-fullscreen');
  return Promise.resolve();
}

在手机上，我会采取更极端的措施：根本不调用这个API，即使在Android系统上这个API技术上是可行的。由于滚动时地址栏会重新出现，再加上系统的滑动操作机制，在小屏幕触摸设备上，使用固定的覆盖层比真正的全屏效果更加稳定、更容易预测用户的行为。实际上，iPhone的Safari浏览器也是采用这种方式的，所以也就不需要再为这种情况编写额外的测试代码了。

在决定自己是否需要使用这些功能之前，你可以先查看Can I use网站上的当前支持情况表格。

利用Wake Lock API保持屏幕处于唤醒状态

你已经打造出了非常出色的全屏体验。用户放松下来享受这种体验……但90秒钟后，屏幕就会变暗并锁定，因为操作系统没有检测到任何操作，从而认为没有人在使用设备。

对于视频元素来说，浏览器会自动处理这个问题；但对于其他内容（比如倒计时、幻灯片展示、canvas动画、食谱页面或乐谱页等），你就需要使用Screen Wake Lock API了。这个API在2024年就已经被所有主流浏览器支持（Chrome 84及以上版本、Safari 16.4及以上版本、Firefox 126及以上版本），并且在2025年成为了所有浏览器都应支持的基线功能，因此你现在就可以直接使用它了，而无需额外添加任何兼容代码。

这个API只需要调用一次，并且它是基于Promise机制设计的：

let wakeLock = null;

async function requestWakeLock() {
  if (!('wakeLock' in navigator)) return; // 如果不支持该API，就会无声地失败

  try {
    wakeLock = await navigator.wakeLock.request('screen');
    wakeLock.addEventListener('release', () => {
      // 当操作系统或浏览器释放了锁时，就需要将wakeLock设置为null。
      wakeLock = null;
    });
  } catch (err) {
    // 如果请求被拒绝，通常是因为设备处于节能模式。
    console.warn(`Wake lock failed: ${err.name} – ${err.message}`);
  }
}

async function releaseWakeLock() {
  if (wakeLock) {
    await wakeLock.release();
    wakeLock = null;
  }
}

有 three 条规则需要牢记：

1. 这个API必须在安全的环境中使用。它仅通过 HTTPS 或 localhost 提供。

2. 当页面被隐藏时，浏览器会自动释放锁。如果用户切换标签页、最小化窗口或锁定手机，那么当页面再次显示出来时，锁并不会自动重新启用。你需要再次调用这个API来重新申请锁。

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible' && amp; shouldStayAwake()) {
    requestWakeLock();
  }
});

1. 做一个好公民吧。 “唤醒锁”会消耗电池电量。因此，只有在实际需要使用它的时候才去启用它，比如当有内容正在播放、运行或显示的时候。一旦这些操作停止，就立即释放这个锁。

好在，全屏API已经提供了一个完美的信号来指示“是否有内容正在显示”：这个信号就是`fullscreenchange`事件。当用户进入全屏模式时，就请求锁定屏幕；当他们退出全屏模式时，就释放这个锁。

不过，`fullscreenchange`并不是唯一的可用信号。我们可以将“唤醒锁”视为与某个特定的“活动”相关联，而不是与某种显示模式相关联。例如，在一个倒计时定时器中，我会在倒计时开始时请求锁定屏幕，而在倒计时结束或暂停时释放这个锁——因为没有人希望定时器在倒计时进行到90秒的时候突然变暗。在一个播放雨声的应用程序中，锁定屏幕的操作也会随着音频的播放或暂停而相应地启动或停止。

其背后的机制其实是相同的，只是我们需要根据具体的应用场景来决定“现在是否应该保持屏幕处于唤醒状态”这个判断标准而已。

整体归纳

以下是将所有这些做法整合在一起的具体方案：通过键盘快捷键来切换全屏模式；让“唤醒锁”根据当前的全屏状态自动进行相应的操作；确保用户无论以何种方式离开当前界面，UI都能保持同步；同时也为那些不支持相关功能的浏览器提供了备用解决方案。

const toggleBtn = document.getElementById('fs-toggle');
let wakeLock = null;

/* ---------- 全屏兼容层 ---------- */
const fs = {
  get element() {
    return document.fullscreenElement ?? document.webkitFullscreenElement ?? null;
  },
  get enabled() {
    return Boolean(document.fullscreenEnabled ?? document.webkitFullscreenEnabled);
  },
  request(el = document.documentElement) {
    if (el.requestFullscreen) return el.requestFullscreen();
    if (elwebkitRequestFullscreen) return Promise.resolve(el.webkitRequestFullscreen());
    return Promise.reject(new Error('全屏功能不受支持'));
  },
  exit() {
    if (document.exitFullscreen) return document.exitFullscreen();
    if (document.webkitExitFullscreen) return Promise.resolve(document.webkitExitFullscreen());
    return Promisereject(new Error('全屏功能不受支持'));
  },
};

/* ---------- 唤醒锁 ---------- */
async function requestWakeLock() {
  if (!('wakeLock' in navigator) || wakeLock) return;
  try {
    wakeLock = await navigator.wakeLock.request('screen');
    wakeLock.addEventListener('release', () => { wakeLock = null; });
  } catch (err) {
    console.warn(`唤醒锁操作失败：${err.name}`);
  }
}

async function releaseWakeLock() {
  if (!wakeLock) return;
  await wakeLock.release();
  wakeLock = null;
}

/* ---------- 切换全屏模式 ---------- */
async function toggleFullscreen() {
  const pseudo = document.body.classList.contains('pseudo-fullscreen');
  try {
    if (pseudo) {
      document.body.classList.remove('pseudo-fullscreen');
      onFullscreenChange();
    } else if (!fs.element) {
      await fs.request();
    } else {
      await fs.exit();
    }
  } catch (err) {
    // 如果API调用失败，就回退到默认方案。
    document.body.classList.add('pseudo-fullscreen');
    onFullscreenChange();
  }
}

/* ---------- 保持所有状态同步 ---------- */
function onFullscreenChange() {
  const active = Boolean(fs.element) || document.body.classList.contains('pseudo-fullscreen');
  toggleBtn.textContent = active ? '退出全屏模式' : '进入全屏模式';
  toggleBtn.setAttribute('aria-pressed', String(active));
  document.body.classList.toggle('is-fullscreen', active);

  // 只要我们处于全屏模式，屏幕就应该保持唤醒状态。
  if (active) requestWakeLock(); else releaseWakeLock();
}

['fullscreenchange', 'webkit fullscreenchange'].forEach((evt) =>
  document.addEventListener(evt, onFullscreenChange)
);

// 如果标签页在用户进入全屏模式后又被隐藏了，然后再重新显示出来，就需要重新获取屏幕锁定权限。
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible' && fs.element) requestWakeLock();
});

/* ---------- 连接各个组件 ---------- */
toggleBtn.addEventListener('click', toggleFullscreen);
document.addEventListener('keydown', (e) => {
  if (e.target.matches('input, textarea, [contenteditable]')) return;
  if (e.key === 'f' || e.key === 'F') { e.preventDefault(); toggleFullscreen(); }
});
// 对于不支持全屏功能的平台（比如iPhone上的Safari浏览器），在用户第一次点击按钮时，就会直接进入伪全屏模式——因此不需要进行用户代理检测。另外，在移动设备上，当设备方向发生改变时，视口的大小会在事件触发之后才发生变化，所以需要稍后重新计算画布的尺寸或布局。
const resizeStage = () => { /* 重新调整屏幕内容的布局 */ };
window.addEventListener('orientationchange', () => setTimeout(resizeStage, 100));

相应的CSS代码如下：

html { background: #000; }

:fullscreen { overflow: hidden; cursor: none; }
:fullscreen::backdrop { background: #000; }

/* 为不支持全屏功能的浏览器提供的备用方案 */
body.pseudo-fullscreen .app { position: fixed; inset: 0; }
body.pseudo-fullscreen .chrome { display: none; }

这段CSS代码仅有大约六十行，但它正是我在生产环境中实际使用的核心代码。我会将每次全屏模式的切换记录为分析数据，因为对于那些以屏幕展示为核心功能的网站来说，这种切换行为本身就代表着一次转化机会，而正是这段代码触发了这一转换过程。

例如，blankscreen.io上的黑屏页面就是利用了这段代码实现的——这个页面的功能就是将整个屏幕显示为纯黑色背景，用户点击按钮或按下F键时进入全屏模式，指针会隐藏起来；只要页面还在显示，就会保持全屏状态，而按下Esc键后页面会立即恢复正常显示。如果在iPhone上打开这个页面，上面提到的备用方案也会被自动启用。

在实际应用中，这种模式也是通用的：用户只需点击一次按钮或按下F键，整个屏幕就会变成黑色，并且会一直保持全屏状态，直到用户按下Esc键才会恢复正常显示。

一旦掌握了这种模式，那么将其应用于计时器、幻灯片展示或者canvas实验中，就只需要将想要覆盖整个屏幕的元素添加到相应的代码中即可。

快速检查清单

在正式发布产品之前，请先仔细阅读这份清单。其中每一条内容都是我曾经遇到过问题的地方：

• 需要用户进行操作才能进入全屏模式：不要在页面加载时、通过计时器触发，也不应在执行耗时较长的await语句后自动进入全屏模式。

• 不要自行检测屏幕状态：应该直接使用document.fullscreenElement来获取当前的全屏状态，并监听fullscreenchange事件来进行变化检测。

• 不能阻止用户按下Esc键：设计时必须考虑到用户随时可能退出全屏模式这一情况。

• Safari浏览器较旧版本要求方法名和事件名前加上webkit前缀：需要注意这一点。

• iPhone上的Safari浏览器没有专门的全屏元素：需要通过document.fullscreenEnabled来检测这一功能，如果系统拒绝支持全屏模式，就应该将其作为备用方案来处理，而不仅仅是显示控制台警告。

• 检查你设置的快捷键是否与页面本身提供的按键冲突：如果应用程序需要使用某些按键来控制全屏模式的切换，那么应该让这些快捷键专门用于进入全屏模式，而退出全屏模式仍然使用Esc键。

• 要确保在全屏模式下，键盘操作依然可用：需要设置tabindex="0"，并且确保用户可以通过按Enter键或空格键来操作屏幕。

• 使用唤醒锁功能时需要HTTPS连接：在节省电池的模式下，系统可能会拒绝使用唤醒锁；当页面被隐藏时，唤醒锁也会自动失效。因此需要在visibilitychange事件发生时重新请求使用唤醒锁。

• 一旦导致唤醒锁的原因消失，就立即释放它：

  这是非常重要的操作。

• 在全屏模式下，应该为html元素设置背景颜色，而不仅仅是body元素。

结论