Skip to content

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安全区域位置,无数据时为 nullComputedRef<SafeArea | null>
safeAreaInsets安全区域插入距离,无数据时为 nullComputedRef<SafeAreaInsets | null>

注意事项 ​

  • 窗口信息是模块级缓存:所有调用共享同一份 info,任一次刷新都会同步更新全部调用方。
  • 调用 Hook 时立即采集一次,并在 onMounted 后用 setTimeout(0) 再刷新一次,用于保证 App 端布局稳定;没有暴露主动刷新方法,横竖屏切换后需重新进入页面才能拿到新尺寸。
  • statusBarHeight 与 screenTop 为 null 时回落为 0(源码类型注释:iOS 横屏 statusBarHeight 为 0)。
  • safeArea 与 safeAreaInsets 无数据时为 null,读取字段前需判空。