全屏 API 标准

1. 术语

本规范依赖于 Infra 标准。[INFRA]

本规范中使用的大多数术语来自 CSS、DOM、HTML 和 Web IDL。[CSS] [DOM] [HTML] [WEBIDL]

2. 模型

所有元素都有一个相关的全屏标志。除非另有说明，否则该标志为未设置。

所有iframe元素都有一个相关的iframe 全屏标志。除非另有说明，否则该标志为未设置。

所有文档都有一个关联的全屏元素。全屏元素是文档的顶层中最顶层的元素，其全屏标志被设置（如果有），否则为 null。

所有文档都有一个相关的待处理全屏事件列表，它是一个包含 (字符串, 元素)元组的有序集合。初始为空。

要全屏显示 element：

将 hideUntil 设为运行最顶层的弹出元素祖先的结果，给定 element，null 和 false。
如果 hideUntil 为 null，则将 hideUntil 设为 element 的节点文档。
运行隐藏所有弹出元素直到，给定 hideUntil，false 和 true。
设置 element 的全屏标志。
立即从顶层移除给定 element。
添加到顶层给定 element。

要取消 element 的全屏，清除 element 的 fullscreen flag、iframe fullscreen flag（如有）和 keyboard lock flag，并给定 element，立即从顶层移除。

要取消全屏显示 document，取消全屏显示所有在 document 的顶层中的元素，其全屏标志已设置。

要完全退出全屏给定文档 document，运行以下步骤：

如果 document 的全屏元素为 null，则终止这些步骤。
取消全屏显示元素，这些元素的全屏标志已设置，在 document 的顶层中，但不包括 document 的全屏元素。
退出全屏document。

每当运行移除步骤时，给定一个 removedNode，运行以下步骤：

将 document 设为 removedNode 的节点文档。
将 nodes 设为 removedNode 的包括阴影在内的包含后代，其全屏标志已设置，按包括阴影在内的树顺序排列。
遍历nodes中的每个node：
1. 如果 node 是 document 的全屏元素，退出全屏 document。
2. 否则，取消全屏显示node。
3. 如果 document 的顶层包含 node，立即从顶层移除给定 node。
  
  其他规范可以在顶层中添加和移除元素，因此 node 可能不是 document 的全屏元素。例如，node 可能是一个打开的对话框元素。

每当运行卸载文档清理步骤时，给定一个document，完全退出全屏 document。

支持全屏，如果没有先前建立的用户偏好、安全风险或平台限制。

要运行全屏步骤给定文档document，运行这些步骤：

将 pendingEvents 设为 document 的待处理全屏事件列表。
清空 document 的待处理全屏事件列表。
遍历 pendingEvents 中的每个 (type, element)：
1. 将 target 设为 element，如果 element 是已连接并且其节点文档是 document，否则将 target 设为 document。
2. 触发一个事件，名为 type，其bubbles和composed属性设置为 true，在 target 上。

这些步骤与 HTML 中定义的事件循环集成。[HTML]

所有元素都有一个关联的键盘锁定标志。除非另有说明，否则它处于未设置状态。

当一个文档的全屏元素不为 null，且该全屏元素的键盘锁定标志已设置时，该文档的键盘锁定处于活动状态，否则处于非活动状态。

3. API

enum FullscreenNavigationUI {
  "auto",
  "show",
  "hide"
};

enum FullscreenKeyboardLock {
  "browser",
  "none"
};

dictionary FullscreenOptions {
  FullscreenKeyboardLock keyboardLock = "none";
  FullscreenNavigationUI navigationUI = "auto";
};

partial interface Element {
  Promise<undefined> requestFullscreen(optional FullscreenOptions options = {});

  attribute EventHandler onfullscreenchange;
  attribute EventHandler onfullscreenerror;
};

partial interface Document {
  [LegacyLenientSetter] readonly attribute boolean fullscreenEnabled;
  [LegacyLenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical

  Promise<undefined> exitFullscreen();

  attribute EventHandler onfullscreenchange;
  attribute EventHandler onfullscreenerror;
};

partial interface mixin DocumentOrShadowRoot {
  [LegacyLenientSetter] readonly attribute Element? fullscreenElement;
};

promise = element . requestFullscreen([options])

将 element 全屏显示，并在完成时解决 promise。

提供时，options 的 navigationUI 成员指示是否偏好在全屏时显示导航 UI。如果设置为 "show"，则相较于屏幕空间，更偏好导航简便性；如果设置为 "hide"，则更偏好更多屏幕空间。用户代理始终可以优先尊重用户偏好，而不是应用的偏好。默认值 "auto" 表示没有应用偏好。

提供时，options 的 keyboardLock 成员指示所提供的键盘锁定模式是否将会应用。

如果设置为 "browser"，则可以应用键盘锁定。

用户代理始终可以优先尊重用户偏好，而不是应用的偏好。默认值 "none" 表示不应用键盘锁定。

document . fullscreenEnabled

如果 document 能够将元素全屏显示，并且支持全屏，则返回 true，否则返回 false。

promise = document . exitFullscreen()

停止将 document 的全屏元素全屏显示，并在完成时解决 promise。

document . fullscreenElement

返回 document 的全屏元素。

shadowroot . fullscreenElement

返回 shadowroot 的全屏元素。

元素 element 的全屏元素就绪检查在以下所有条件都为 true 时返回 true，否则返回 false：

element 是已连接的。
element 的节点文档被允许使用 "全屏" 功能。
element 的命名空间不是HTML 命名空间，或 element 的弹出框可见性状态为隐藏。

requestFullscreen(options)方法的步骤如下：

将 pendingDoc 设为this的节点文档。
将 promise 设为一个新的 promise。
如果 pendingDoc 不是完全活动的，则使用 TypeError 异常拒绝 promise，并返回 promise。
将 error 设为 false。
如果以下任一条件为 false，则将 error 设置为 true：
- this 的命名空间是HTML 命名空间，或者this 是一个SVG svg 或 MathML math 元素。[SVG] [MATHML]
- this 不是 对话框 元素。
- 全屏元素就绪检查对于this返回 true。
- 支持全屏。
- this的相关全局对象具有瞬时激活，或者该算法是由用户生成的方向更改触发。
如果 error 为 false，则消耗用户激活，给定 pendingDoc 的相关全局对象。
返回 promise，并运行剩余步骤并行。

如果 error 为 false，则调整 pendingDoc 的节点可导航的顶级可遍历对象的活动文档的视口尺寸，可选择考虑 options["navigationUI"]：

值	视口尺寸
"`hide`"	输出设备屏幕的完整尺寸
"`show`"	限制为允许用户代理显示页面导航控件的输出设备屏幕尺寸
"`auto`"	用户代理定义，但匹配上述之一

可选择显示一条消息，说明最终用户如何还原此操作。

如果以下任一条件为 false，则将 error 设置为 true：
- this 的节点文档是 pendingDoc。
- 全屏元素就绪检查对于this返回 true。
如果 error 为 true：
1. 追加 (fullscreenerror, this) 到 pendingDoc 的待处理全屏事件列表中。
2. 使用 TypeError 异常拒绝 promise，并终止这些步骤。
将 fullscreenElements 设为一个有序集合，最初由this组成。
当条件为 true 时：
1. 将 last 设为 fullscreenElements 的最后一个项。
2. 将 container 设为 last 的节点可导航的容器。
3. 如果 container 为 null，则中断。
4. 追加 container 到 fullscreenElements。
对于 fullscreenElements 中的每个 element：
1. 令 doc 为 element 的节点文档。
2. 如果 element 是 doc 的全屏元素，则继续。
  
  当没有任何变化时，无需通知观察者。
3. 如果 element 是 this，且 this 是一个 iframe 元素，则设置 element 的 iframe fullscreen flag。
4. 在 doc 内全屏化 element。
5. 将 (fullscreenchange, element) 追加到 doc 的待处理 fullscreen 事件列表。
元素被全屏化的顺序不可观察，因为运行全屏步骤是在树序中调用的。
根据 options["keyboardLock"] 的值：

"browser"

设置 this 的键盘锁定标志。

"none"

清除 this 的键盘锁定标志。
用 undefined 解决 promise。

具有跨进程可导航对象的实现留给读者练习。欢迎对潜在改进提出意见。

fullscreenEnabled getter 步骤为：如果 this 被允许使用 "fullscreen" 特性并且支持全屏，则返回 true，否则返回 false。

fullscreen getter 步骤为：如果 this 的全屏元素为 null，则返回 false，否则返回 true。

请改用 fullscreenElement 属性。

fullscreenElement getter 步骤为：

如果 this 是影子根，且其宿主未连接，则返回 null。
令 candidate 为将全屏元素重定向到 this 的结果。
如果 candidate 和 this 在同一树中，则返回 candidate。
返回 null。

如果一个文档的顶层中正好有一个元素设置了其fullscreen flag，则称该文档为简单全屏文档。

一个文档即使在其顶层中有两个元素，也可以是一个简单全屏文档。例如，除了全屏元素之外，还可能有一个打开的 dialog 元素。

给定 doc，要收集要取消全屏的文档，运行以下步骤：

令 docs 为一个由 doc 组成的有序集合。
当 true 时：
1. 令 lastDoc 为 docs 的最后一个文档。
2. 断言：lastDoc 的全屏元素不为 null。
3. 如果 lastDoc 不是简单全屏文档，则跳出。
4. 令 container 为 lastDoc 的节点 navigable 的容器。
5. 如果 container 为 null，则跳出。
6. 如果 container 的iframe fullscreen flag已设置，则跳出。
7. 将 container 的节点文档追加到 docs。
返回 docs。

这是其全屏元素将被取消全屏的文档集合，但 docs 中的最后一个文档可能在其顶层中有多个元素设置了fullscreen flag，在这种情况下，该文档仍会保持全屏。

要让文档 doc 退出全屏，运行以下步骤：

令 promise 为一个新 promise。
如果 doc 不是完全活动，或 doc 的全屏元素为 null，则用 TypeError 异常拒绝 promise 并返回 promise。
令 resize 为 false。
令 docs 为给定 doc 收集要取消全屏的文档的结果。
令 topLevelDoc 为 doc 的节点 navigable 的顶层 traversable 的活动文档。
如果 topLevelDoc 在 docs 中，并且它是一个简单全屏文档，则将 doc 设置为 topLevelDoc，并将 resize 设置为 true。
如果 doc 的全屏元素未连接：
1. 将 (fullscreenchange, doc 的全屏元素) 追加到 doc 的待处理 fullscreen 事件列表。
2. 取消 doc 的全屏元素的全屏。
返回 promise，并并行运行剩余步骤。
用 doc 运行完全解锁屏幕方向步骤。
如果 resize 为 true，则将 doc 的视口调整为其“normal”尺寸。
如果 doc 的全屏元素为 null，则用 undefined 解决 promise 并终止这些步骤。
令 exitDocs 为给定 doc 收集要取消全屏的文档的结果。
令 descendantDocs 为一个有序集合，它由 doc 的后代 navigable 的活动文档组成，这些文档的全屏元素为非 null（如有），并按树序排列。
对于 exitDocs 中的每个 exitDoc：
1. 将 (fullscreenchange, exitDoc 的全屏元素) 追加到 exitDoc 的待处理 fullscreen 事件列表。
2. 如果 resize 为 true，则取消 exitDoc 的全屏。
3. 否则，取消 exitDoc 的全屏元素的全屏。
对于 descendantDocs 中的每个 descendantDoc：
1. 将 (fullscreenchange, descendantDoc 的全屏元素) 追加到 descendantDoc 的待处理 fullscreen 事件列表。
2. 取消 descendantDoc 的全屏。
文档被取消全屏的顺序不可观察，因为运行全屏步骤是在树序中调用的。
用 undefined 解决 promise。

exitFullscreen() 方法步骤为：返回在 this 上运行退出全屏的结果。

以下是必须由 Element 和 Document 对象作为事件处理器 IDL 属性支持的事件处理器（及其对应的事件处理器事件类型）：

事件处理器	事件处理器事件类型
`onfullscreenchange`	`fullscreenchange`
`onfullscreenerror`	`fullscreenerror`

这些不受 ShadowRoot 或 Window 对象支持，并且在任何命名空间中的 Element 对象都没有对应的事件处理器内容属性。

4. 用户界面

鼓励用户代理在实现原生媒体全屏控制时使用requestFullscreen()和exitFullscreen()。

如果用户发起关闭请求，这将作为完全退出全屏算法的一部分被触发，属于关闭请求步骤。这优先于任何关闭监听器。

只要用户代理认为有必要，就可以在没有关闭请求或对 exitFullscreen() 的调用的情况下结束任何全屏会话。

当键盘锁定处于活动状态时，应向用户明确通知，可能通过浏览器 UI 指示器。

应有一种简单且直观的方法，让用户能够覆盖键盘锁定，将控制权还给系统或用户代理。

5. 渲染

本节的解释应与HTML的渲染部分等效。[HTML]

5.1. `:fullscreen` 伪类

:fullscreen伪类必须匹配满足以下任一条件的元素element：

element的全屏标志已设置。
element是shadow宿主，并且重新定位其节点文档的全屏元素的结果是element。

这使其不同于fullscreenElement API，该API返回最上层的全屏元素。

5.2. 用户代理级别样式表默认值

@namespace "http://www.w3.org/1999/xhtml";

*|*:not(:root):fullscreen {
  position:fixed !important;
  inset:0 !important;
  margin:0 !important;
  box-sizing:border-box !important;
  min-width:0 !important;
  max-width:none !important;
  min-height:0 !important;
  max-height:none !important;
  width:100% !important;
  height:100% !important;
  transform:none !important;

  /* intentionally not !important */
  object-fit:contain;
}

iframe:fullscreen {
  border:none !important;
  padding:0 !important;
}

*|*:not(:root):fullscreen::backdrop {
  background:black;
}

6. 键盘锁定

键盘锁定通过允许在全屏中运行的 Web 应用拦截某些通常会由系统或用户代理处理的按键输入，从而增强它们的功能。这在游戏或远程桌面应用等场景中很有用，其中 ESC 或功能键等按键是应用功能不可或缺的一部分。

键盘锁定使 Web 应用能够直接捕获并处理按键输入，绕过通常由用户代理或操作系统执行的默认行为。通常会触发用户代理或系统级操作的按键事件，会改为被重定向到处于全屏状态的 Web 应用。这样的按键事件（针对单个按键或键盘快捷键）在键盘锁定处于活动状态时可以没有动作，或者仍然可以有相同的动作，但允许网页调用 preventDefault() 来取消该动作。

每当一个文档的键盘锁定从活动变为非活动时，用户代理必须停用键盘锁定，并将键盘输入的处理恢复为用户代理和操作系统的默认行为。

用户代理应为退出全屏的目的保留一个额外输入。也有一些系统级按键序列或组合出于安全原因不能被拦截，例如 Windows 上的 Ctrl+Alt+Del。

例如，使用 Esc 键退出全屏的用户代理会使用键盘锁定来防止按键时立即退出，而是要求长按才能退出全屏。一些这样的用户代理还会隐式地向全屏会话授予部分键盘锁定，在这种情况下，Esc 键可能是唯一受显式键盘锁定影响的按键。

7. 权限策略集成

本规范定义了一个由字符串"fullscreen"标识的策略控制的功能。其默认允许列表是'self'。

文档的权限策略决定了该文档中的任何内容是否被允许进入全屏模式。如果在任何文档中禁用，则该文档中的任何内容都不会被允许使用全屏。

HTML allowfullscreen 属性会影响嵌套在该 iframe 中的任何文档的容器策略。除非通过 allow 属性覆盖，在 allowfullscreen 上设置 <iframe allow="fullscreen *">，如Permissions Policy § 6.3.1 allowfullscreen中所述。

8. 安全性和隐私考量

用户代理应确保（例如通过覆盖层）最终用户知道某些内容正在全屏显示。用户代理应提供一种始终有效的退出全屏方式，并向用户告知这一点。这是为了防止站点在全屏时通过重新创建用户代理甚至操作系统环境来欺骗最终用户。另请参见 requestFullscreen() 的定义。

要使子 navigable 中的内容能够进入全屏，需要通过权限策略明确允许，可以通过 HTML iframe 元素的 allowfullscreen 属性，或 HTML iframe 元素的 allow 属性中的适当声明，或通过随其所嵌套经过的文档一起传递的 `Permissions-Policy` HTTP 头来实现。

这会防止例如来自第三方的内容在没有明确权限的情况下进入全屏。

应用键盘锁定时，只有有限的一组按键（主要是不涉及系统控制或隐私风险的按键，例如 Alt+Tab、Ctrl+Alt+Del）可以通过 API 锁定。

应用键盘锁定时，用户代理应实现防护措施以防止滥用此特性，例如允许用户覆盖锁定。

用户代理可以提供用户偏好来忽略键盘锁定（以任意粒度，例如针对特定站点，或全局）。类似地，某些平台可能没有键盘，此时用户代理可以忽略键盘锁定状态。然而，这不应影响 requestFullscreen() 方法的 Web 可观察行为，也不应以其他方式暴露，以避免指纹识别。

先前托管的定义

本规范之前托管了::backdrop选择器和文档的顶层概念的定义。

致谢

特别感谢 Robert O’Callahan 设计了最初的模型，并且非常出色。

感谢 Andy Earnshaw, Changwan Hong, Chris Pearce, Darin Fisher, Dave Tapuska, fantasai, Giuseppe Pascale, Glenn Maynard, Ian Clelland, Ian Hickson, Ignacio Solla, João Eiras, Josh Soref, Kagami Sascha Rosylight, Matt Falkenhagen, Mihai Balan, Mounir Lamouri, Øyvind Stenhaug, Pat Ladd, Rafał Chłodnicki, Riff Jiang, Rune Lillesveen, Sigbjørn Vik, Simon Pieters, Tab Atkins-Bittner, Takayoshi Kochi, Theresa O’Connor, triple-underscore, Vincent Scheib, 和 Xidorn Quan 也非常出色。

本标准由 Philip Jägenstedt (Google, philip@foolip.org) 编辑。最初由 Anne van Kesteren (Apple, annevk@annevk.nl) 撰写。Tantek Çelik (Mozilla, tantek@cs.stanford.edu) 解决了法律问题。

知识产权

这是现行标准。对专利审查版本感兴趣的人士应查看现行标准审查草案。

全屏 API

摘要

1. 术语

2. 模型

3. API

4. 用户界面

5. 渲染

5.1. `:fullscreen` 伪类

5.2. 用户代理级别样式表默认值

6. 键盘锁定

7. 权限策略集成

8. 安全性和隐私考量

先前托管的定义

致谢

知识产权

索引

本规范定义的术语

引用定义的术语

参考文献

规范性引用

IDL 索引

全屏 API

摘要

1. 术语

2. 模型

3. API

4. 用户界面

5. 渲染

5.1. :fullscreen 伪类

5.2. 用户代理级别样式表默认值

6. 键盘锁定

7. 权限策略集成

8. 安全性和隐私考量

先前托管的定义

致谢

知识产权

索引

本规范定义的术语

引用定义的术语

参考文献

规范性引用

IDL 索引

5.1. `:fullscreen` 伪类