React中无需wrapper/provider如何通过onClick触发整页全屏

核心结论 #

完全不需要引入第三方包、不需要Provider、不需要额外包裹wrapper div，就能实现在任意组件位置触发整页全屏。

实现原理 #

浏览器原生提供了标准 Fullscreen API，整页全屏的本质是让页面根元素 document.documentElement 进入全屏状态，这个元素是全局可访问的，和React组件层级、按钮所在的DOM位置没有任何关系，不需要通过组件树传递任何状态或引用。

可直接复用的实现代码 #

先写一个跨组件通用的全屏Hook，所有组件都可以直接引入使用：

import { useState, useEffect, useCallback } from 'react';

export function useFullscreen() {
  const [isFullscreen, setIsFullscreen] = useState(false);

  // 同步原生全屏状态，处理用户按ESC、F11等方式退出全屏的场景
  useEffect(() => {
    const updateFullscreenState = () => {
      setIsFullscreen(Boolean(document.fullscreenElement));
    };
    document.addEventListener('fullscreenchange', updateFullscreenState);
    return () => document.removeEventListener('fullscreenchange', updateFullscreenState);
  }, []);

  const toggleFullscreen = useCallback(async () => {
    try {
      if (document.fullscreenElement) {
        await document.exitFullscreen();
      } else {
        // 直接请求根元素全屏，即整页效果
        await document.documentElement.requestFullscreen();
      }
    } catch (error) {
      console.warn('全屏操作失败，请确认是用户主动触发操作：', error);
    }
  }, []);

  return {
    isFullscreen,
    toggleFullscreen,
    enterFullscreen: () => !document.fullscreenElement && document.documentElement.requestFullscreen(),
    exitFullscreen: () => document.fullscreenElement && document.exitFullscreen()
  };
}

使用方式 #

不管按钮在DOM树的哪个层级、属于哪个业务组件，直接引入Hook绑定到onClick事件即可，不需要修改根组件、不需要加任何外层包裹：

// 示例：任意深度嵌套的业务组件里的全屏按钮
function SettingsPageDeepChild() {
  const { isFullscreen, toggleFullscreen } = useFullscreen();
  return (
    <button className="fullscreen-btn" onClick={toggleFullscreen}>
      {isFullscreen ? '退出全屏' : '进入整页全屏'}
    </button>
  );
}

注意事项 #

• 受浏览器安全策略限制，全屏方法必须由用户主动交互事件触发（比如点击、键盘按下事件），不能在页面加载、接口请求回调这类非用户交互场景直接调用
• 现代主流浏览器（Chrome 71+、Firefox 64+、Safari 16.4+、Edge 79+）均已支持标准无前缀的Fullscreen API，如果需要兼容更老旧的版本，只需要在调用时加一层前缀判断即可，不需要引入第三方依赖
• 第三方全屏库（如fscreen、react-full-screen）之所以要求包裹Provider或wrapper div，是因为它们的设计目标是支持任意局部元素全屏，需要获取被包裹元素的引用、跨组件传递全屏状态，对于仅需要整页全屏的场景，这些库的大部分功能都是冗余的。

局部全屏场景的最简实现 #

如果后续需要做某个模块的局部全屏，也不需要全局Provider，只需要给对应元素绑定ref，调用ref上的requestFullscreen方法即可，仅当需要跨多层级组件共享同一个局部元素的全屏状态时，才需要考虑用Context做状态传递，不需要额外套wrapper div。

内容的提问来源于stack exchange，提问作者cikcirikcik