Skip to content

useSafeArea 安全区 ​

17:43

说明 ​

useSafeArea 从窗口信息的 safeAreaInsets 中取出顶部与底部插入距离,无安全区时两者均为 0;它只表达安全区插入距离,不包含状态栏高度。

示例 ​

安全区数值 ​

解构 top 与 bottom 两个 ComputedRef,数值取自 safeAreaInsets,单位 px。

查看源码
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>

可视化占位 ​

把 top / bottom 拼成 px 后绑定到上下色带高度,中间内容区展示安全区之外的范围。

查看源码
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>

使用说明 ​

以提示条说明只含安全区插入距离、无安全区时数值为 0、状态栏避让改用 useWindowInfo().statusBarHeight。

查看源码
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 ​

参数 ​

参数说明类型默认值版本
-该 Hook 不接受参数---

返回值 ​

字段说明类型
top顶部安全区插入距离(px),取自 safeAreaInsets.top,无安全区时为 0ComputedRef<number>
bottom底部安全区插入距离(px),取自 safeAreaInsets.bottom,无安全区时为 0ComputedRef<number>

注意事项 ​

  • 数值来自 useWindowInfo 的 safeAreaInsets,与窗口信息共用模块级缓存。
  • 只表达安全区插入距离,不含状态栏高度;状态栏避让请使用 useWindowInfo().statusBarHeight。
  • safeAreaInsets 为 null,或 top / bottom 不大于 0 时,对应返回值均为 0。