uni.getWindowInfo() @getwindowinfo

# uni.getWindowInfo()

同步获取窗口信息 GitCode GitHub

# getWindowInfo 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	3.9	4.11	4.61

# 返回值

类型描述

GetWindowInfoResult result

名称类型必备默认值兼容性描述

pixelRatio

number

是

设备像素比

screenWidth

number

是

屏幕宽度，单位为px

screenHeight

number

是

屏幕高度，单位为px

windowWidth

number

是

可使用窗口宽度，单位为px

windowHeight

number

是

可使用窗口高度，单位为px

statusBarHeight

number

是

状态栏的高度，单位为px

windowTop

number

是

内容区域距离顶部的距离（同CSS变量 --window-top），单位为px

windowBottom

number

是

内容区域距离底部的距离（同CSS变量 --window-bottom），单位为px

safeArea

SafeArea

是

安全区域在屏幕中的位置信息

名称

类型

必备

默认值

兼容性

描述

left

number

是

安全区域左上角横坐标，单位为px

right

number

是

安全区域右下角横坐标，单位为px

top

number

是

安全区域左上角纵坐标，单位为px

bottom

number

是

安全区域右下角纵坐标，单位为px

width

number

是

安全区域的宽度，单位为px

height

number

是

安全区域的高度，单位为px

safeAreaInsets

SafeAreaInsets

是

安全区域插入位置（与屏幕边界的距离）信息

名称

类型

必备

默认值

兼容性

描述

left

number

是

安全区域左侧插入位置（距离左边边界距离），单位为px

right

number

是

安全区域右侧插入位置（距离右边边界距离），单位为px

top

number

是

安全区顶部插入位置（距离顶部边界距离），单位为px

bottom

number

是

安全区域底部插入位置（距离底部边界距离），单位为px

screenTop

number

是

窗口上边缘的 y 值，单位为px

cutoutArea

Array<CutoutRect>

否

挖孔、刘海区域在屏幕中的位置信息

名称

类型

必备

默认值

兼容性

描述

left

number

是

挖孔、刘海区域左上角横坐标，单位为px

right

number

是

挖孔、刘海区域右下角横坐标，单位为px

top

number

是

挖孔、刘海区域左上角纵坐标，单位为px

bottom

number

是

挖孔、刘海区域右下角纵坐标，单位为px

uni.getWindowInfo是全局API，沿袭自小程序。但小程序并未考虑丰富的场景，其实手机屏幕尺寸、应用所占区域尺寸、页面所占区域尺寸是3个概念。

在小屏模式、分屏模式、特殊页面（tabbar和dialogPage）等特殊场景下，这3个概念的数值不相同。但uni的全局API无法表达差异，需要在页面对象上补充区域尺寸信息。

其实大多数情况下开发者需要获取的是当前页面的尺寸，此时在UniPage对象上获取高宽、四边位置更精准。详见

下图标注了各区域信息

# 安全区域说明

由于全面屏手机屏幕有顶部的摄像头挖空区和底部导航的存在，为了确保内容区域不被遮挡，提出了安全区域概念，以便于在安全区域内布局。

app-android平台全屏模式下分安全区域字段说明：

safeArea.top : statusBarHeight
safeArea.bottom: statusBarHeight + 应用导航栏高度 + windowHeight + tabbar高度
safeArea.height: safeArea.bottom - safeArea.top
safeAreaInsets: 安全区域与可渲染内容区域边界的距离

HBuilderX4.31版本页面内容可渲染区域在设备系统导航栏设置为全面屏手势时，调整为可渲染到手势指示条区域，如不想将页面内容渲染到此区域，可在页面底部设置占位view，其高度为safeAreaInsets.bottom值。

app-ios平台safeArea与iOS原生的安全区域概念相同，top与bottom分别对应window.safeAreaInsets.top window.safeAreaInsets.bottom，具体请参照Apple文档

注意事项

screenWidth/screenHeight获取的是设备屏幕宽高信息
- app平台应用在非全屏模式（如“浮窗”或“分屏”）时，仍然返回的设备屏幕的宽高
windowWidth/windowHeight获取的是当前栈顶页面的可使用窗口宽高信息，调用此API前如果打开了新页面，可能获取到的是新开页面的信息
- app平台需要在页面渲染后才能获取到准确信息，稳妥起见，建议在页面生命周期onReady后获取
statusBarHeight获取的是系统状态栏高度
- app-Android平台横屏时获取的状态栏高度与竖屏一致
- app-iOS平台横屏时获取的状态栏高度为0，与竖屏时获取的高度不一致
windowTop/windowBottom 在app平台页面内容无法渲染顶部默认导航栏或底部tabBar区域，返回的值一定为0
HBuilderX4.25版本开始，app-android平台返回的安全区域的 top 属性值调整为手机状态栏高度

# 示例

hello uni-app x

Template

Script

<template>
  <page-head :title="title"></page-head>
  <view class="uni-common-mt">
    <view class="uni-list">
      <view class="uni-list-cell" v-for="(item, _) in items" style="align-items: center">
        <view class="uni-pd">
          <view class="uni-label" style="width: 180px">{{ item.label }}</view>
        </view>
        <view class="uni-list-cell-db">
          <text class="uni-list-cell-db-text">{{ item.value == '' ? '未获取' : item.value }}</text>
        </view>
      </view>
    </view>
    <view class="uni-padding-wrap">
      <view class="uni-btn-v">
        <button type="primary" @tap="getWindowInfo">获取窗口信息</button>
      </view>
      <!-- #ifdef APP-ANDROID -->
      <view class="uni-btn-v">
        <navigator url="/pages/API/get-window-info/window-area">
          <button type="primary">窗口各区域示例</button>
        </navigator>
      </view>
      <!-- #endif -->
    </view>
  </view>
</template>


<style>
  .uni-pd {
    padding-left: 15px;
  }
</style>