Skip to content

useWindowInfo — Window Info ​

17:43

Description ​

useWindowInfo collects the common fields of uni.getWindowInfo() and adds computed shortcuts for each field plus the safe-area data. The state is a module-level cache, so every component shares the same window info.

Examples ​

Window size ​

Reads windowWidth, windowHeight, screenWidth, screenHeight and pixelRatio from info, all in px.

View source
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>

Status bar and content area ​

Reads statusBarHeight, windowTop, windowBottom and screenTop; statusBarHeight is the usual offset for a custom navbar.

View source
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>

Safe area data ​

safeArea gives the position rect while safeAreaInsets gives the four inset distances, and both show - when null.

View source
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>

Usage ​

Explains that the module-level cache is shared, a delayed refresh runs after mounting, and safeArea / safeAreaInsets need a null check before use.

View source
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 ​

Parameters ​

ParameterDescriptionTypeDefaultVersion
-This hook takes no arguments---

Returns ​

FieldDescriptionType
infoThe complete window info objectRef<WindowInfo>
pixelRatioDevice pixel ratioComputedRef<number>
screenWidthScreen width in pxComputedRef<number>
screenHeightScreen height in pxComputedRef<number>
windowWidthUsable window width in pxComputedRef<number>
windowHeightUsable window height in pxComputedRef<number>
statusBarHeightStatus bar height in px, commonly used to offset a custom navbarComputedRef<number>
windowTopDistance from the content area to the top in px (same as --window-top)ComputedRef<number>
windowBottomDistance from the content area to the bottom in px (same as --window-bottom)ComputedRef<number>
screenTopy position of the window's top edge in pxComputedRef<number>
safeAreaSafe area position, null when unavailableComputedRef<SafeArea | null>
safeAreaInsetsSafe area insets, null when unavailableComputedRef<SafeAreaInsets | null>

Notes ​

  • Window info is a module-level cache: every caller shares the same info, and any refresh updates all callers at once.
  • The hook collects data immediately when called and refreshes once more via setTimeout(0) in onMounted to keep the App layout stable; no public refresh method is exposed, so after an orientation change the page must be re-entered to get the new size.
  • statusBarHeight and screenTop fall back to 0 when null (the source type comment notes that statusBarHeight is 0 on iOS in landscape).
  • safeArea and safeAreaInsets are null when there is no data, so check for null before reading their fields.