Skip to content

useSafeArea — Safe Area ​

17:43

Description ​

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 ​

ParameterDescriptionTypeDefaultVersion
-This hook takes no arguments---

Returns ​

FieldDescriptionType
topTop safe-area inset in px, taken from safeAreaInsets.top, 0 when there is no safe areaComputedRef<number>
bottomBottom safe-area inset in px, taken from safeAreaInsets.bottom, 0 when there is no safe areaComputedRef<number>

Notes ​

  • The values come from useWindowInfo's safeAreaInsets and share the module-level window cache.
  • Only safe-area insets are expressed, with no status bar height; use useWindowInfo().statusBarHeight to offset the status bar.
  • When safeAreaInsets is null, or top / bottom is not greater than 0, the corresponding value is 0.