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,无安全区时为 0 | ComputedRef<number> |
| bottom | 底部安全区插入距离(px),取自 safeAreaInsets.bottom,无安全区时为 0 | ComputedRef<number> |
注意事项
- 数值来自
useWindowInfo的safeAreaInsets,与窗口信息共用模块级缓存。 - 只表达安全区插入距离,不含状态栏高度;状态栏避让请使用
useWindowInfo().statusBarHeight。 safeAreaInsets为null,或top/bottom不大于 0 时,对应返回值均为 0。