useWindowInfo 窗口信息
17:43说明
useWindowInfo 采集 uni.getWindowInfo() 的常用字段,并额外提供各字段的 computed 快捷值与安全区数据;状态为模块级缓存,多个组件共享同一份窗口信息。
示例
窗口尺寸
读取 info 中的 windowWidth、windowHeight、screenWidth、screenHeight 与 pixelRatio,单位均为 px。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in sizeRows"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useWindowInfo } from '@/uni_modules/uview-pro-x';
// 解构方式使用:const { windowWidth } = useWindowInfo()
const { info } = useWindowInfo();
type Row = {
desc: string;
result: string;
last: boolean;
};
const sizeRows = computed((): Row[] => {
const current = info.value;
return [
{ desc: 'windowWidth', result: current.windowWidth.toString(), last: false },
{ desc: 'windowHeight', result: current.windowHeight.toString(), last: false },
{ desc: 'screenWidth', result: current.screenWidth.toString(), last: false },
{ desc: 'screenHeight', result: current.screenHeight.toString(), last: false },
{ desc: 'pixelRatio', result: current.pixelRatio.toString(), last: true }
];
});
</script>状态栏与内容区
读取 statusBarHeight、windowTop、windowBottom 与 screenTop,其中 statusBarHeight 常用于自定义导航栏顶部避让。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in statusRows"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useWindowInfo } from '@/uni_modules/uview-pro-x';
const { info } = useWindowInfo();
type Row = {
desc: string;
result: string;
last: boolean;
};
const statusRows = computed((): Row[] => {
const current = info.value;
return [
{ desc: 'statusBarHeight', result: current.statusBarHeight.toString(), last: false },
{ desc: 'windowTop', result: current.windowTop.toString(), last: false },
{ desc: 'windowBottom', result: current.windowBottom.toString(), last: false },
{ desc: 'screenTop', result: current.screenTop.toString(), last: true }
];
});
</script>安全区数据
safeArea 提供位置矩形,safeAreaInsets 提供四边插入距离,两者为 null 时显示 -。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in safeRows"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useWindowInfo } from '@/uni_modules/uview-pro-x';
const { info } = useWindowInfo();
type Row = {
desc: string;
result: string;
last: boolean;
};
// safeArea / safeAreaInsets 可能为 null,取值前先判空
const safeRows = computed((): Row[] => {
const area = info.value.safeArea;
const insets = info.value.safeAreaInsets;
return [
{ desc: 'safeArea.left', result: area != null ? area.left.toString() : '-', last: false },
{ desc: 'safeArea.top', result: area != null ? area.top.toString() : '-', last: false },
{ desc: 'safeArea.right', result: area != null ? area.right.toString() : '-', last: false },
{ desc: 'safeArea.bottom', result: area != null ? area.bottom.toString() : '-', last: false },
{ desc: 'safeArea.width', result: area != null ? area.width.toString() : '-', last: false },
{ desc: 'safeArea.height', result: area != null ? area.height.toString() : '-', last: false },
{ desc: 'insets.left', result: insets != null ? insets.left.toString() : '-', last: false },
{ desc: 'insets.top', result: insets != null ? insets.top.toString() : '-', last: false },
{ desc: 'insets.right', result: insets != null ? insets.right.toString() : '-', last: false },
{ desc: 'insets.bottom', result: insets != null ? insets.bottom.toString() : '-', last: true }
];
});
</script>使用说明
以提示条说明模块级缓存共享、挂载后延迟刷新一次、safeArea / safeAreaInsets 取值前需判空。
查看源码
vue
<template>
<ux-alert-tips type="primary" :show-icon="true" title="const { info, windowWidth, safeArea } = useWindowInfo()" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="模块级缓存,多个组件共享同一份数据" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="挂载后会延迟刷新一次,保证 App 端布局稳定" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="safeArea / safeAreaInsets 可能为 null,取值前需判空" />
</template>
<script setup lang="ts">
import { useWindowInfo } from '@/uni_modules/uview-pro-x';
const { info, windowWidth, windowHeight, safeArea, safeAreaInsets } = useWindowInfo();
</script>API
参数
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| - | 该 Hook 不接受参数 | - | - | - |
返回值
| 字段 | 说明 | 类型 |
|---|---|---|
| info | 完整窗口信息对象 | Ref<WindowInfo> |
| pixelRatio | 设备像素比 | ComputedRef<number> |
| screenWidth | 屏幕宽度(px) | ComputedRef<number> |
| screenHeight | 屏幕高度(px) | ComputedRef<number> |
| windowWidth | 可使用窗口宽度(px) | ComputedRef<number> |
| windowHeight | 可使用窗口高度(px) | ComputedRef<number> |
| statusBarHeight | 状态栏高度(px),自定义导航栏顶部避让常用 | ComputedRef<number> |
| windowTop | 内容区域距离顶部的距离(px,同 --window-top) | ComputedRef<number> |
| windowBottom | 内容区域距离底部的距离(px,同 --window-bottom) | ComputedRef<number> |
| screenTop | 窗口上边缘的 y 值(px) | ComputedRef<number> |
| safeArea | 安全区域位置,无数据时为 null | ComputedRef<SafeArea | null> |
| safeAreaInsets | 安全区域插入距离,无数据时为 null | ComputedRef<SafeAreaInsets | null> |
注意事项
- 窗口信息是模块级缓存:所有调用共享同一份
info,任一次刷新都会同步更新全部调用方。 - 调用 Hook 时立即采集一次,并在
onMounted后用setTimeout(0)再刷新一次,用于保证 App 端布局稳定;没有暴露主动刷新方法,横竖屏切换后需重新进入页面才能拿到新尺寸。 statusBarHeight与screenTop为null时回落为0(源码类型注释:iOS 横屏statusBarHeight为 0)。safeArea与safeAreaInsets无数据时为null,读取字段前需判空。