如何在 JavaScript 中使用 Fullscreen API（并使用 Wake Lock API 保持屏幕唤醒）

你有两种可行的方案：

1. 一种“伪全屏”回退方案：将你的元素定位为 position: fixed; inset: 0 并隐藏你自己的浏览器界面。你无法摆脱 Safari 的地址栏，但它会在滚动时折叠，对大多数工具来说这已经足够好。

2. 建议“添加到主屏幕”：在主屏幕上启动且其 manifest 中包含 "display": "standalone" 的网页应用将在没有任何浏览器 UI 的情况下运行。这是在 iPhone 上实现真正全屏内容的唯一方法。

无论你选择哪种方案，不要仅依赖特性检测。document.fullscreenEnabled 告诉你 API 是否 存在，但请求仍可能在运行时被拒绝（例如在没有 allowfullscreen 属性的 iframe 内部，或在浏览器策略已锁定的页面上，或者仅仅是因为你未测试过的浏览器有其自己的看法）。

对我来说，行之有效的做法是尝试使用真实的 API，并将拒绝视为触发 CSS 回退的条件：

function enterFullscreen(el) {
  if (fs.enabled) {
    return fs.request(el).catch(() => {
      // The API exists but refused – degrade to a fixed overlay.
      document.body.classList.add('pseudo-fullscreen');
    });
  }
  document.body.classList.add('pseudo-fullscreen');
  return Promise.resolve();
}

在手机上，我会再进一步，根本不调用该 API，即便在 Android 上它技术上可用。地址栏在滚动时重新出现以及系统的滑动手势之间，固定覆盖层在小触摸屏上的表现比真正的全屏更可预测。这实际上也是 iPhone Safari 强制你走的同一条代码路径。如此一来，测试分支就少了一条。

您可以在决定需要多少此功能之前，先查看 可以使用吗 上的最新支持表。

使用 Wake Lock API 保持屏幕唤醒

您已经构建了一个美妙的全屏体验。用户靠后观看……九十秒后，屏幕变暗并锁定，因为操作系统未检测到任何输入，认为没有人在场。

对于 video 元素，浏览器会为您处理此问题。对于其他情况（如倒计时、幻灯片、Canvas 动画、食谱或乐谱页面），您需要使用 屏幕唤醒 API。它在 2024 年已进入所有主要浏览器（Chrome 84+、Safari 16.4+、Firefox 126+），并于 2025 年成为 基线 的一部分，因此您可以今天直接使用，无需 polyfill。

该 API 只需一次调用，并且基于 Promise：

let wakeLock = null;

async function requestWakeLock() {
  if (!('wakeLock' in navigator)) return; // unsupported – fail silently

  try {
    wakeLock = await navigator.wakeLock.request('screen');
    wakeLock.addEventListener('release', () => {
      // The OS or browser released it (tab hidden, battery saver, etc.)
      wakeLock = null;
    });
  } catch (err) {
    // Rejected – most often because the device is in a power-saving mode.
    console.warn(`Wake lock failed: ${err.name} – ${err.message}`);
  }
}

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

以下是三条需要了解的规则：

1. 它需要安全上下文。 该 API 仅在 HTTPS（以及 localhost）下暴露。

2. 当页面被隐藏时，浏览器会自动释放锁。 如果用户切换标签页、最小化窗口或锁定手机，当页面再次可见时，锁不会自行恢复。您需要重新请求它：

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

1. 做个好公民。 唤醒锁会耗尽电池。只有在它真正有用的时候才保持它，比如某东西在播放、运行或被显示的时候。一旦停止，立即释放它。

好消息是，Fullscreen API 已经为 “something is being displayed” 提供了完美的信号：fullscreenchange。当用户进入全屏时，请求唤醒锁；当他们退出全屏时，释放它。

不过，全屏并不是唯一的好信号，将唤醒锁视为附加在 活动 上而非显示模式上会更有帮助。在倒计时计时器中，我会在倒计时开始时请求锁，在倒计时归零或暂停时释放它（不管页面是否全屏），因为没有人希望计时器在 90 秒时变黑。在雨声播放器中，唤醒锁会跟随音频：播放时获取锁，暂停时或睡眠定时器淡出声音时释放锁。

机制是相同的：只有 “屏幕现在应该保持唤醒吗？” 这个问题会变化。

把所有内容放在一起

这里有一个完整的模式：带键盘快捷键的全屏切换、随全屏状态变化的唤醒锁、无论用户如何离开都能保持同步的 UI，以及针对不支持此功能的浏览器的后备方案。

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

/* ---------- Fullscreen compatibility layer ---------- */
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 (el.webkitRequestFullscreen) return Promise.resolve(el.webkitRequestFullscreen());
    return Promise.reject(new Error('Fullscreen not supported'));
  },
  exit() {
    if (document.exitFullscreen) return document.exitFullscreen();
    if (document.webkitExitFullscreen) return Promise.resolve(document.webkitExitFullscreen());
    return Promise.reject(new Error('Fullscreen not supported'));
  },
};

/* ---------- Wake lock ---------- */
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(`Wake lock failed: ${err.name}`);
  }
}

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

/* ---------- Toggle ---------- */
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) {
    // The API refused (iframe policy, unsupported platform, etc.) – degrade gracefully.
    document.body.classList.add('pseudo-fullscreen');
    onFullscreenChange();
  }
}

/* ---------- Keep everything in sync ---------- */
function onFullscreenChange() {
  const active = Boolean(fs.element) || document.body.classList.contains('pseudo-fullscreen');
  toggleBtn.textContent = active ? 'Exit fullscreen' : 'Fullscreen';
  toggleBtn.setAttribute('aria-pressed', String(active));
  document.body.classList.toggle('is-fullscreen', active);

  // The screen should stay awake exactly as long as we're fullscreen.
  if (active) requestWakeLock(); else releaseWakeLock();
}

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

// Re-acquire the lock if the tab was hidden and came back while fullscreen.
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible' && fs.element) requestWakeLock();
});

/* ---------- Wiring ---------- */
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(); }
});
// Unsupported platforms (iPhone Safari) simply take the catch branch above
// on the first click and land in pseudo-fullscreen – no user-agent sniffing needed.
// One more mobile quirk: rotating the device changes the viewport *after*
// the event fires, so re-measure your canvas or layout a beat later.
const resizeStage = () => { /* re-measure whatever fills the screen */ };
window.addEventListener('orientationchange', () => setTimeout(resizeStage, 100));

对应的 CSS 如下：

html { background: #000; }

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

/* Fallback for browsers without element fullscreen */
body.pseudo-fullscreen .app { position: fixed; inset: 0; }
body.pseudo-fullscreen .chrome { display: none; }

大约六十行代码，这就是我在生产中运行的同一核心：我将每次全屏进入记录为一个分析事件，因为在一个屏幕工具站点上，这种转变 就是 转化，而正是这段代码触发了它。

例如，它驱动着 blankscreen.io 的黑屏页面 —— 该页面的全部任务是将显示器变成纯黑，点击或按下 F 键进入全屏，隐藏光标，保持唤醒状态只要它在屏幕上显示，并在按下 Esc 时干净利落地退出。如果你在 iPhone 上打开它，你会看到上面的伪全屏回退在发挥作用。

同样的模式在实际中也存在：一次点击或按下 F 键，整个显示器变黑，屏幕保持唤醒状态只要它在显示。按 Esc 键浏览器恢复。

只要掌握了这个模式，将其添加到计时器、幻灯片或 Canvas 实验中，只需放入你想让其填满屏幕的元素即可。

快速陷阱清单

在发布之前，请检查此清单。每一项都是我至少曾经踩过的坑：

• 需要用户手势： 在加载时、计时器中或在耗时的 await 之后不得进入全屏。

• 不要自行跟踪状态： 读取 document.fullscreenElement 并监听 fullscreenchange 事件。

• 无法阻止Esc： 设计时应考虑用户可能随时离开。

• 旧版 Safari 需要 webkit 前缀 来处理方法 以及 事件名称。

• iPhone Safari 不支持元素全屏： 使用 document.fullscreenEnabled 进行特性检测，并将运行时的拒绝视为回退触发器，而不仅仅是控制台警告。

• 将你的快捷键与页面自身的按键进行对比： 如果应用占用了字母键，则让快捷键仅 进入 全屏，退出交给 Esc。

• 使全屏区域可通过键盘访问（tabindex="0"、Enter/Space）。

• 唤醒锁需要 HTTPS： 在省电模式下可能被拒绝，页面隐藏时会被撤销。在 visibilitychange 时重新申请。

• 释放唤醒锁，在不再需要时立即释放。

• 将背景放置在 html 上，而不仅仅是 body，在页面全屏时。

结论

全屏 API 就是这样一个浏览器功能：乍看之下只是一行代码，但实际上它有自己的个性。

核心（requestFullscreen()、exitFullscreen()、fullscreenElement 以及 fullscreenchange 事件）其实很简单。关键在于遵守用户手势规则，让 UI 诚实地反映真实状态，处理 Safari 的历史记录，并记住：如果屏幕两分钟后变暗，“全屏”仅仅是工作的一半。Wake Lock API 能弥补这一差距，通过 fullscreenchange 将两者配合使用，可使两者保持整洁。

取上面的六十行模式，将你自己的元素放进去，你就能得到一个适用于从演示到游戏的各种场景的生产就绪全屏体验。

编码愉快！