useSafeArea — Safe Area
17:43Description
useSafeArea extracts the top and bottom inset distances from the window's safeAreaInsets, returning 0 for each when there is no safe area. It only expresses safe-area insets and excludes the status bar height.
Examples
Safe area values
Destructures the top and bottom computed refs, whose values come from safeAreaInsets in px.
View source
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in valueRows"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useSafeArea } from '@/uni_modules/uview-pro-x';
// 解构方式使用:const { top, bottom } = useSafeArea()
const { top, bottom } = useSafeArea();
type Row = {
desc: string;
result: string;
last: boolean;
};
const valueRows = computed((): Row[] => [
{ desc: '顶部插入 top', result: top.value.toString(), last: false },
{ desc: '底部插入 bottom', result: bottom.value.toString(), last: true }
]);
</script>Visual preview
Binds top and bottom as px heights to the two colored bars around a center area that represents the space outside the safe area.
View source
vue
<template>
<view class="demo-safe-frame">
<view class="demo-safe-bar" :style="{ height: topPx, backgroundColor: $u.strOr($u.color.primaryLight) }"></view>
<view class="demo-safe-center">
<text class="demo-safe-center-text">内容区(安全区之外)</text>
</view>
<view class="demo-safe-bar" :style="{ height: bottomPx, backgroundColor: $u.strOr($u.color.successLight) }"></view>
</view>
</template>
<script setup lang="ts">
import { $u, useSafeArea } from '@/uni_modules/uview-pro-x';
const { top, bottom } = useSafeArea();
// 色带高度绑定安全区数值,按 px 拼字符串走内联样式
const topPx = computed((): string => top.value.toString() + 'px');
const bottomPx = computed((): string => bottom.value.toString() + 'px');
</script>
<style lang="scss">
.demo-safe-frame {
display: flex;
flex-direction: column;
height: 160px;
border-radius: 8px;
overflow: hidden;
background-color: $u-bg-gray-light;
}
.demo-safe-bar {
width: 100%;
}
.demo-safe-center {
flex: 1;
display: flex;
flex-direction: row;
align-items: center;
justify-content: center;
background-color: $u-bg-color;
}
.demo-safe-center-text {
font-size: 12px;
color: $u-tips-color;
}
</style>Usage
Explains that only safe-area insets are included, both values are 0 without a safe area, and status bar offsetting should use useWindowInfo().statusBarHeight.
View source
vue
<template>
<ux-alert-tips type="primary" :show-icon="true" title="const { top, bottom } = useSafeArea()" />
<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="无安全区时 top / bottom 均为 0" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="状态栏避让请用 useWindowInfo().statusBarHeight" />
</template>
<script setup lang="ts">
import { useSafeArea } from '@/uni_modules/uview-pro-x';
const { top, bottom } = useSafeArea();
</script>API
Parameters
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| - | This hook takes no arguments | - | - | - |
Returns
| Field | Description | Type |
|---|---|---|
| top | Top safe-area inset in px, taken from safeAreaInsets.top, 0 when there is no safe area | ComputedRef<number> |
| bottom | Bottom safe-area inset in px, taken from safeAreaInsets.bottom, 0 when there is no safe area | ComputedRef<number> |
Notes
- The values come from
useWindowInfo'ssafeAreaInsetsand share the module-level window cache. - Only safe-area insets are expressed, with no status bar height; use
useWindowInfo().statusBarHeightto offset the status bar. - When
safeAreaInsetsisnull, ortop/bottomis not greater than 0, the corresponding value is 0.