useFullscreen

1"use client"
2 
3import * as React from "react"
4 
5export interface UseFullscreenResult<T extends HTMLElement> {
6  /** Callback ref — attach it to the element you want to be able to fullscreen. */
7  ref: (node: T | null) => void
8  /** Whether the tracked element is currently the document's fullscreen element. */
9  fullscreen: boolean
10  /** Requests fullscreen on the tracked element. Never throws — resolves `false` on
11   *  any failure (no node attached, unsupported browser, or the browser rejected the
12   *  request because it wasn't called synchronously inside a user gesture). */
13  enter: () => Promise<boolean>
14  /** Exits fullscreen. Never throws — resolves `false` if nothing is fullscreen, the
15   *  browser is unsupported, or the exit request was rejected. */
16  exit: () => Promise<boolean>
17  /** `exit()` if the tracked element is fullscreen, otherwise `enter()`. */
18  toggle: () => Promise<boolean>
19  /** `document.fullscreenEnabled` — `false` during SSR and on unsupported browsers. */
20  supported: boolean
21}
22 
23/**
24 * 单个元素的全屏进出 + 状态订阅。用**callback ref**(不是 `useRef` + `useEffect`)
25 * 记录当前要全屏的节点 —— 节点被条件渲染替换(换 key、换分支)时天然拿到"现在
26 * 到底在管哪个节点"的真相,不需要额外的挂载 effect。
27 *
28 * `fullscreen` 用 `useSyncExternalStore` 订阅 `document` 的全局 `fullscreenchange`
29 * 事件(不是每节点各建一个 observer —— 全屏状态本来就是 document 级别的单例):
30 * `getSnapshot` 每次都从 ref 里读最新节点,和 `document.fullscreenElement` 比较,
31 * 得到"是不是**这个**元素在全屏"。这样零 `useEffect` + `setState`,`fullscreenchange`
32 * 无论因为调用方点了 `exit()`、点了别的元素的 `enter()`,还是用户按 Esc 系统级退出
33 * 而触发,都会被同一条订阅捕获并同步——Esc 退出不需要任何特殊分支。
34 *
35 * `enter`/`exit` 把 `requestFullscreen`/`exitFullscreen` 的 Promise 包一层,永不
36 * 抛出、失败一律 resolve `false`。失败常见原因:没有已挂载的节点、浏览器不支持、
37 * 或者(最常踩)**没有在用户手势(click/keydown 的同步调用栈里)直接调用** ——
38 * 浏览器的 Fullscreen API 要求 `requestFullscreen()` 必须同步发生在一次真实用户
39 * 交互内,`await` 过别的 Promise、`setTimeout` 之后再调,请求会被浏览器直接拒绝。
40 *
41// … truncated