useWindowInfo — Window Info
17:43Description
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
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| - | This hook takes no arguments | - | - | - |
Returns
| Field | Description | Type |
|---|---|---|
| info | The complete window info object | Ref<WindowInfo> |
| pixelRatio | Device pixel ratio | ComputedRef<number> |
| screenWidth | Screen width in px | ComputedRef<number> |
| screenHeight | Screen height in px | ComputedRef<number> |
| windowWidth | Usable window width in px | ComputedRef<number> |
| windowHeight | Usable window height in px | ComputedRef<number> |
| statusBarHeight | Status bar height in px, commonly used to offset a custom navbar | ComputedRef<number> |
| windowTop | Distance from the content area to the top in px (same as --window-top) | ComputedRef<number> |
| windowBottom | Distance from the content area to the bottom in px (same as --window-bottom) | ComputedRef<number> |
| screenTop | y position of the window's top edge in px | ComputedRef<number> |
| safeArea | Safe area position, null when unavailable | ComputedRef<SafeArea | null> |
| safeAreaInsets | Safe area insets, null when unavailable | ComputedRef<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)inonMountedto 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. statusBarHeightandscreenTopfall back to0whennull(the source type comment notes thatstatusBarHeightis 0 on iOS in landscape).safeAreaandsafeAreaInsetsarenullwhen there is no data, so check for null before reading their fields.