屏幕方向

屏幕可以处于，或锁定为下列之一的 屏幕方向：

任意

用户可以将屏幕旋转到设备操作系统或最终用户允许的 任意方向。

默认（未锁定）

屏幕解除锁定时设备的默认行为 （即，活动方向锁定为 null）。此 方向由设备的操作系统或 用户代理确定，或由最终用户控制，也可能由 已安装的 Web 应用程序设置。例如， 当屏幕 方向未锁定且用户旋转设备时，某些 设备会将方向变化限制为 portrait-primary、 landscape-primary 和 landscape-secondary， 而不包括 portrait-secondary。

横向

屏幕宽高比中的宽度大于高度。

自然

设备显示屏的参考方向，方向角度以此为基准 进行测量，该方向由用户代理、 用户、操作系统或屏幕本身确定。例如， 计算机显示器的参考方向通常为 landscape-primary，而移动 电话的参考方向通常为 portrait-primary。

注

用户代理如何确定自然方向由实现定义， 并且因平台而异。某些用户代理 对每种设备类别使用固定方向（例如， 手持设备使用 portrait-primary，而landscape-primary 用于 平板电脑、台式机和电视），而其他用户代理则根据 屏幕的物理尺寸及其默认旋转推导该方向。对于 没有明显直立方向的设备，例如方形或可折叠 屏幕，其自然方向因此可能因 用户代理而异。

纵向

屏幕宽高比中的高度大于宽度。

主方向

设备屏幕的自然方向，适用于纵向 或横向。

次方向

与设备屏幕的主方向相反的方向，适用于 纵向或横向。

输出设备的屏幕关联以下概念：

当前激活的方向锁定

屏幕锁定到的 屏幕方向，用 OrientationLockType 表示；如果未锁定则为 null。

当前方向角度

屏幕相对于其自然方向逆时针旋转的角度（度数），由 屏幕方向取值列表推导得出。

当前方向类型

屏幕的屏幕方向，用 OrientationType 表示。

下面的屏幕方向值列表对具有不同 自然方向的屏幕中与每种屏幕方向类型关联的 角度进行了标准化：

对于自然方向为纵向的屏幕：

• portrait-primary：0°
• landscape-primary：90°
• portrait-secondary：180°
• landscape-secondary：270°

对于自然方向为横向的屏幕：

• landscape-primary：0°
• portrait-primary：90°
• landscape-secondary：180°
• portrait-secondary：270°

Document 接口扩展了以下内部插槽：

预锁定条件 是 用户代理 在允许锁定屏幕方向之前 MAY 施加的可选要求。 常见的预锁定条件包括要求文档处于全屏模式，或属于已安装的 Web 应用。参见 10. 与 Web 应用程序清单的交互 和 9. 与全屏 API 的交互 以获取具体示例。

当以 lock() 方法并传入 OrientationLockType orientation 调用时，用户代理 MUST 执行以下步骤。

1. 令 document 为 this 的 相关全局对象的 关联的 Document。
2. 对 document 运行 通用安全检查。如果 异常被 抛出，则返回 一个以该异常被拒绝的 promise，并中止这些步骤。
3. 如果 用户代理 不支持将屏幕方向锁定为 orientation，则返回 一个被拒绝的 promise，其原因为 "NotSupportedError" DOMException，并中止这些步骤。
4. 如果 用户代理 要求 document 及其关联的 浏览上下文 满足 预锁定条件 才能锁定屏幕方向，且这些条件未被满足， 则返回 一个被拒绝的 promise，其原因为 "NotAllowedError" DOMException，并中止这些步骤。
5. 如果 document 的 [[orientationPendingPromise]] 不为 null，则 拒绝并清空当前锁定的 promise ，其原因为 "AbortError"。
6. 将 document 的 [[orientationPendingPromise]] 设为 一个新的 promise。
7. 应用方向锁 orientation 到 document。
8. 返回 document 的 [[orientationPendingPromise]]。

当调用 unlock() 方法时，用户代理必须执行以下步骤：

1. 令 document 为 this 的 相关全局对象的 关联 Document。
2. 对 document 运行通用安全检查。如果异常被抛出，则重新抛出该异常并中止这些步骤。
3. 如果屏幕的当前激活的方向锁定为 null，则返回 undefined。
4. 如果 document 的 [[orientationPendingPromise]] 不为 null，则对 document 的当前锁定 promise 进行拒绝并置为 null，异常为 "AbortError"。
5. 应用方向锁定 null 到 document。

通用安全检查针对 Document document 的步骤如下：

1. 如果 document 不是 具有用户注意的顶层可遍历项的完全激活后代，抛出 "InvalidStateError" DOMException。
2. 如果 document 设置了 沙箱化的方向锁定浏览上下文标志， 抛出 "SecurityError" DOMException。
3. 如果 document 的 可见性状态 为 "hidden"，抛出 "SecurityError" DOMException。

获取时，type 属性返回 this 的 [[type]]。

获取时，angle 属性返回 this 的 [[angle]]。

当创建 浏览上下文 context 时， 用户代理 必须：

1. 让screenOrientation成为context的关联的ScreenOrientation。
2. 初始化screenOrientation的[[initialType]]内部槽为屏幕的当前方向类型。
3. 初始化screenOrientation的[[type]]内部槽为屏幕的当前方向类型。
4. 初始化screenOrientation的[[angle]]内部槽为屏幕的当前方向角度。

当步骤要求用 DOMString exceptionName 对 Document document 的 当前锁定 promise 进行拒绝并置为 null 时， 用户代理必须：

1. 断言：[[orientationPendingPromise]] 不为 null。
2. 令 promise 为 document 的 [[orientationPendingPromise]]。
3. 在 DOM 操作任务源上， 以 document 的 相关全局对象， 排入一个全局任务，以使用新的 exceptionName DOMException 拒绝 promise。
4. 将 document 的 [[orientationPendingPromise]] 设为 null。

当步骤要求将 OrientationLockType? orientation 的方向锁定应用到 Document document 时， 用户代理必须执行以下步骤：

1. 如果 document 在并行执行过程中停止为 完全激活， 且 [[orientationPendingPromise]] 不为 null，则 拒绝并清空当前锁定的 promise，原因为 "AbortError"。
2. 令 topDocument 为 document 的 顶层可遍历项的 活动文档。
3. 令 descendantDocs 为 有序集合，内容包括 topDocument 的 后代 navigables 的 活动文档，若有，如树型顺序。
4. 对每个 doc 于 descendantDocs 中执行：
   1. 若 doc 即 document，跳过。
   2. 若 doc 的 [[orientationPendingPromise]] 为 null，跳过。
   3. 拒绝并清空当前锁定的 promise，原因为 "AbortError"。
5. 以下子步骤并行执行：
   1. 若 document 已停止为 完全激活， 且 document 的 [[orientationPendingPromise]] 不为 null，则 拒绝并清空当前锁定的 promise， 原因为 "AbortError"，并中止这些步骤。
   2. 若 orientation 为 null， 解锁屏幕方向。
   3. 否则，尝试 锁定屏幕方向为 orientation。 可根据平台约定修改视口绘制方式以匹配 orientation。
   4. 若因用户先前设定偏好、平台限制或其它原因导致尝试失败：
      1. 将屏幕的活动方向锁定 置为 null。
      2. 加入任务队列至 DOM 操作任务源， 使用 document 的 相关全局对象来执行：
         1. 若 document 的 [[orientationPendingPromise]] 不为 null， 拒绝并清空当前锁定的 promise， 原因为 "NotSupportedError"。
         2. 中止这些步骤。
      注

      当用户设置了阻止 Web 应用更改屏幕方向的偏好，或底层平台（而非用户代理）不允许锁定指定的 orientation 时可能发生以上情况。需注意，用户偏好或平台能力的差异可能会被用于指纹识别，因为它们可能导致锁定失败出现可检测模式。

   5. 将屏幕的活动方向锁定 设为 orientation，并根据需要更新当前方向类型 和 当前方向角度， 以反映 屏幕方向的任何变化。
6. 加入全局任务队列到 DOM 操作任务源， 使用 document 的 相关全局对象来执行：
   1. 令 promise 为 document 的 [[orientationPendingPromise]]。
      注
   2. 将 document 的 [[orientationPendingPromise]] 设为 null。
   3. 对 topDocument 执行 屏幕方向变更步骤。
   4. 若 promise 不为 null， 以 undefined 解析 promise。

当用户代理判断某个顶层可遍历项的屏幕方向发生了变化， 或者用户将顶层浏览上下文移动到不同屏幕时， 应对该执行屏幕方向变更步骤， 目标是该顶层可遍历项的 活动文档。

屏幕方向变更步骤针对 Document document，具体如下：

1. 如果 document 不是 具有用户注意的顶层可遍历项的完全激活后代，则中止这些步骤。
2. 令 type 和 angle 为屏幕的 当前方向类型 和 当前方向角度。
3. 令 screenOrientation 为 document 的 相关全局对象的 关联的 ScreenOrientation。
4. 如果 type 等于 screenOrientation 的 [[type]] 且 angle 等于 screenOrientation 的 [[angle]]，则中止这些步骤。
5. 加入全局任务队列至 用户交互任务源， 使用 document 的 相关全局对象，执行以下步骤：
   1. 将 screenOrientation 的 [[angle]] 设为 angle。
   2. 将 screenOrientation 的 [[type]] 设为 type。
   3. 触发名为 "change" 的事件， 目标为 screenOrientation。
6. 令 descendantDocs 为 有序集合， 包含 document 的 后代 navigables 的 活动文档（如有），按树型顺序排列。
7. 依次对 descendantDocs 中的 doc， 执行 屏幕方向变更步骤，目标为 doc。

[HTML] 的“更新可见性状态”算法会运行屏幕方向变更步骤。

每当卸载文档清理步骤针对 document 运行时，用户代理必须执行以下步骤：

1. 如果 document 不是 顶层可遍历项的 活动文档，则中止这些步骤。
2. 对 document 执行 完全解锁屏幕方向步骤。

针对 Document document，完全解锁屏幕方向步骤如下：

1. 如果 document 的 [[orientationPendingPromise]] 不为 null，则 拒绝并清空当前锁定 promise， 原因为 "AbortError"。
2. 令 topDocument 为 document 的 顶层可遍历项的 活动文档。
3. 应用方向锁 null 到 topDocument。

为保护用户隐私，方向变更事件的传递受到多项限制：

• 事件只会在作为 文档 的 具有用户注意的顶层可遍历项的完全激活后代 上触发。
• 额外的 可见性状态 检查为隐藏文档提供更深层次的防护。
• 事件源自 活动文档， 该文档属于 顶层可遍历项， 并向后代文档传播。

对 文档 要求是 具有用户注意的顶层可遍历项的完全激活后代 ，确保方向事件仅发送到既在系统层面可见又获得用户关注（如有焦点或能接受键盘输入）的窗口中的文档。额外的可见性状态检查进一步增强安全性。这些限制可防止后台标签页、隐藏窗口和最小化应用收集方向数据以进行指纹识别。

为了抵御指纹识别，用户代理SHOULD实施以下保护措施，特别是在注重隐私的环境如隐私浏览模式下：

1. 在 顶层可遍历项的整个生命周期内， 始终表现为屏幕的 自然 方向即 [[initialType]]。
2. 将 type getter 的可能返回值限制为 "portrait-primary" 或 "landscape-primary"。 返回值由屏幕宽高比决定。
3. 如果 当前方向类型 与 [[initialType]] 相同，则 angle getter 返回 0，否则返回 90。
4. 屏幕方向改变时，仅当 当前方向类型 从 竖屏 切换到 横屏或反向切换时，才触发 change 事件。