useWindowSize

窗口尺寸获取和监听 Hook，提供窗口尺寸的响应式获取和实时监听功能。支持防抖优化和服务端渲染，常用于响应式布局、媒体查询判断、组件尺寸适配等场景。

基础用法

最简单的用法是获取当前窗口尺寸并监听变化。

窗口宽度: 1024px

窗口高度: 768px

调整浏览器窗口大小查看实时变化

显示代码

响应式布局判断

基于窗口尺寸进行响应式布局判断，实现不同屏幕尺寸下的适配。

当前设备类型:桌面端

断点信息:

• 移动端 (< 768px): ❌
• 平板 (768px - 1024px): ❌
• 桌面端 (≥ 1024px): ✅

调整窗口大小查看设备类型变化

显示代码

防抖优化

使用防抖功能避免窗口尺寸快速变化时的性能问题。

无防抖

宽度: 1024px

更新次数: 0

300ms 防抖

宽度: 1024px

更新次数: 0

快速调整窗口大小，观察更新次数差异

显示代码

手动控制

支持手动更新尺寸和动态启用/禁用监听功能。

窗口尺寸: 1024 x 768

监听状态:已禁用

显示代码

服务端渲染支持

为服务端渲染环境提供初始尺寸配置。

SSR 初始尺寸: 1920 x 1080

在服务端渲染时使用预设的初始尺寸

显示代码

API

参数

参数	类型	默认值	说明
options	UseWindowSizeOptions	{}	配置选项

UseWindowSizeOptions

属性	类型	默认值	说明
immediate	boolean	true	是否立即获取窗口尺寸
listen	boolean	true	是否监听窗口尺寸变化
debounce	number	0	防抖延迟时间（毫秒），0 表示不防抖
initialWidth	number	1024	初始宽度，在服务端渲染时使用
initialHeight	number	768	初始高度，在服务端渲染时使用

返回值

返回一个数组 [windowSize, updateSize, setEnabled]：

索引	名称	类型	说明
0	windowSize	ComputedRef<WindowSize>	窗口尺寸信息的只读响应式引用
1	updateSize	() => void	手动更新窗口尺寸的函数
2	setEnabled	(enabled: boolean) => void	启用/禁用监听的函数

类型定义

/**
 * 窗口尺寸信息类型
 */
export interface WindowSize {
  /** 窗口宽度 */
  width: number;
  /** 窗口高度 */
  height: number;
}

/**
 * 手动更新窗口尺寸的函数类型
 */
export type UpdateSizeFunction = () => void;

/**
 * 启用/禁用尺寸监听的函数类型
 */
export type SetEnabledFunction = (enabled: boolean) => void;

/**
 * useWindowSize 钩子函数的返回值类型
 */
export type UseWindowSizeReturn = [
  /** 窗口尺寸信息的只读响应式引用 */
  ComputedRef<WindowSize>,
  /** 手动更新窗口尺寸的函数 */
  UpdateSizeFunction,
  /** 启用/禁用尺寸监听的函数 */
  SetEnabledFunction,
];

/**
 * 窗口尺寸监听配置选项
 */
export interface UseWindowSizeOptions {
  /** 是否立即获取窗口尺寸，默认为 true */
  immediate?: boolean;
  /** 是否监听窗口尺寸变化，默认为 true */
  listen?: boolean;
  /** 防抖延迟时间（毫秒），默认为 0（不防抖） */
  debounce?: number;
  /** 初始宽度，在服务端渲染时使用，默认为 1024 */
  initialWidth?: number;
  /** 初始高度，在服务端渲染时使用，默认为 768 */
  initialHeight?: number;
}

注意事项

1. 响应式引用: windowSize 是一个只读的计算属性，在模板中可以直接使用，在 JavaScript 中需要通过 .value 访问
2. 性能优化: 建议在频繁变化的场景下使用防抖功能，避免过度渲染
3. 服务端渲染: 在 SSR 环境中会使用配置的初始尺寸，客户端激活后会自动更新为实际尺寸
4. 内存管理: Hook 会自动处理事件监听器的清理，无需手动移除
5. 多实例使用: 支持在同一个组件中多次使用，每次调用都会创建独立的状态