useFullscreen

一个全屏控制 Hook，提供简洁的 API 来进入和退出全屏模式。支持元素全屏和整个页面全屏，自动处理浏览器兼容性和状态管理。

基础用法

🖥️ 基础全屏控制

页面全屏

状态: 普通模式

支持: ❌ 否

元素全屏

📱 点击全屏

或使用按钮控制

元素状态: 普通模式

支持: ❌ 否

显示代码

高级用法示例

⚡ 高级全屏功能

视频播放器

▶️

模拟视频播放器

点击进入全屏

图片查看器

🌅

🌊

🏔️

🌸

显示代码

API 参考

参数

参数	类型	默认值	说明
target	Ref<HTMLElement | null>	-	目标元素，不传则为整个页面
options	UseFullscreenOptions	{}	配置选项

UseFullscreenOptions

属性	类型	默认值	说明
onEnter	() => void	-	进入全屏回调
onExit	() => void	-	退出全屏回调
onError	(error: Error) => void	-	错误回调

返回值

useFullscreen 返回一个数组，包含以下元素：

const [isFullscreen, toggle, enter, exit, isSupported] = useFullscreen(target, options);

索引	名称	类型	说明
0	isFullscreen	Ref<boolean>	是否处于全屏状态
1	toggle	() => Promise<void>	切换全屏状态
2	enter	() => Promise<void>	进入全屏
3	exit	() => Promise<void>	退出全屏
4	isSupported	Ref<boolean>	是否支持全屏 API

类型定义

export interface UseFullscreenOptions {
  onEnter?: () => void;
  onExit?: () => void;
  onError?: (error: Error) => void;
}

export type UseFullscreenReturn = [Ref<boolean>, () => Promise<void>, () => Promise<void>, () => Promise<void>, Ref<boolean>];

export function useFullscreen(target?: Ref<HTMLElement | null>, options?: UseFullscreenOptions): UseFullscreenReturn;

使用场景

1. 视频播放器 - 视频全屏播放功能
2. 图片查看器 - 图片全屏查看
3. 游戏应用 - 游戏全屏模式
4. 演示文稿 - 幻灯片全屏展示
5. 数据可视化 - 图表全屏查看

高级用法

带回调的全屏控制

const [isFullscreen, toggle] = useFullscreen(elementRef, {
  onEnter: () => {
    console.log("进入全屏模式");
    // 隐藏其他 UI 元素
  },
  onExit: () => {
    console.log("退出全屏模式");
    // 恢复 UI 元素
  },
  onError: (error) => {
    console.error("全屏操作失败:", error);
  },
});

条件全屏

const handleFullscreen = async () => {
  if (isSupported.value) {
    try {
      await toggle();
    } catch (error) {
      console.error("全屏失败:", error);
    }
  } else {
    alert("浏览器不支持全屏 API");
  }
};

键盘快捷键

import { useEventListener } from "@vakao-ui/hooks";

const [isFullscreen, toggle] = useFullscreen();

useEventListener(window, "keydown", (event: KeyboardEvent) => {
  if (event.key === "F11") {
    event.preventDefault();
    toggle();
  }
});

浏览器兼容性

浏览器	支持版本
Chrome	15+
Firefox	10+
Safari	5.1+
Edge	12+
IE	11+

注意事项

1. 全屏 API 需要用户手势触发（如点击事件）
2. 某些浏览器可能有安全限制
3. 移动设备上的全屏行为可能有所不同
4. 组件卸载时会自动退出全屏状态
5. 使用 ESC 键可以退出全屏模式
6. 全屏状态会自动同步到响应式状态