useFullscreen

元素的全屏展示

useFullscreen 封装了 Fullscreen API，用于管理给定 DOM 元素的全屏模式进入和退出。它返回一个包含当前全屏状态（布尔值）和操作对象的元组，操作对象包含 enterFullscreen、exitFullscreen、toggleFullscreen 和表示浏览器支持的 isEnabled 标志。可通过选项提供进入/退出事件的回调。

使用场景

• 构建视频播放器、图片画廊或演示模式，这些场景受益于全屏显示
• 创建使用整个屏幕的沉浸式阅读或游戏体验
• 为数据仪表板或可视化工具添加全屏切换

注意事项

• SSR 安全：在服务端渲染期间全屏状态和 isEnabled 均返回 false。服务端不会访问 document。
• 浏览器支持：所有现代浏览器均支持 Fullscreen API。在显示全屏控件前请先检查 isEnabled 确认支持。
• 用户手势：浏览器需要用户发起的事件（例如点击）才能进入全屏。没有用户交互的程序化调用将被拒绝。

Usage

function Demo() {
  const ref = useRef(null);
  const [isFullscreen, { enterFullscreen, exitFullscreen, toggleFullscreen }]
    = useFullscreen(ref);
  return (
    <div ref={ref}>
      <div style={{ marginBottom: 16 }}>
        {isFullscreen ? "全屏模式" : "非全屏模式"}
      </div>
      <div>
        <button type="button" onClick={enterFullscreen}>
          进入全屏
        </button>
        <button
          type="button"
          onClick={exitFullscreen}
          style={{ margin: "0 8px" }}
        >
          退出全屏
        </button>
        <button type="button" onClick={toggleFullscreen}>
          切换全屏
        </button>
      </div>
    </div>
  );
};

API

useFullScreen

Returns

readonly [boolean, { readonly enterFullscreen: () => void; readonly exitFullscreen: () => void; readonly toggleFullscreen: () => void; readonly isEnabled: boolean; }]: 包含以下元素的元组：

• 当前是否处于全屏。
• 一个操作对象:
• enterFullscreen： 进入全屏。
• exitFullscreen： 退出全屏。
• toggleFullscreen： 切换全屏。
• isEnabled： 当前浏览器是否支持全屏。

Arguments

UseFullScreenOptions

BasicTarget

export type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;

TargetValue

type TargetValue<T> = T | undefined | null;

TargetType

type TargetType = HTMLElement | Element | Window | Document | EventTarget;