Back to Uni App

Get Window Info

docs/api/get-window-info.md

2.3.313.3 KB
Original Source
<!-- ## uni.getWindowInfo() @getwindowinfo -->

::: sourceCode

uni.getWindowInfo() @getwindowinfo

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-getSystemInfo

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-getSystemInfo

:::

同步获取窗口信息

getWindowInfo 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(Vapor)
4.04.413.94.114.615.0

返回值

类型描述
GetWindowInfoResultresult

GetWindowInfoResult 的属性描述

名称类型必备默认值兼容性描述
pixelRationumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0设备像素比
screenWidthnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0屏幕宽度,单位为px
screenHeightnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0屏幕高度,单位为px
windowWidthnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0可使用窗口宽度,单位为px
windowHeightnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0可使用窗口高度,单位为px
statusBarHeightnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0状态栏的高度,单位为px
windowTopnumber-Web: 4.0; 微信小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0内容区域距离顶部的距离(同CSS变量 --window-top),单位为px
windowBottomnumber-Web: 4.0; 微信小程序: x; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0内容区域距离底部的距离(同CSS变量 --window-bottom),单位为px
safeAreaSafeArea-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域在屏幕中的位置信息
safeAreaInsetsSafeAreaInsets-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域插入位置(与屏幕边界的距离)信息
screenTopnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0窗口上边缘的 y 值,单位为px
cutoutAreaArray<CutoutRect>-Web: x; 微信小程序: x; Android 系统版本: 9.0; Android: 4.31; iOS: x; HarmonyOS: x挖孔、刘海区域在屏幕中的位置信息
safeArea 的属性描述
名称类型必备默认值兼容性描述
leftnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域左上角横坐标,单位为px
rightnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域右下角横坐标,单位为px
topnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域左上角纵坐标,单位为px
bottomnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域右下角纵坐标,单位为px
widthnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域的宽度,单位为px
heightnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域的高度,单位为px
safeAreaInsets 的属性描述
名称类型必备默认值兼容性描述
leftnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域左侧插入位置(距离左边边界距离),单位为px
rightnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域右侧插入位置(距离右边边界距离),单位为px
topnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区顶部插入位置(距离顶部边界距离),单位为px
bottomnumber-Web: 4.0; 微信小程序: 4.41; Android: 3.9; iOS: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0安全区域底部插入位置(距离底部边界距离),单位为px
cutoutArea 的属性描述
名称类型必备默认值兼容性描述
leftnumber-Web: x; 微信小程序: x; Android 系统版本: 9.0; Android: 4.31; iOS: x; HarmonyOS: x挖孔、刘海区域左上角横坐标,单位为px
rightnumber-Web: x; 微信小程序: x; Android 系统版本: 9.0; Android: 4.31; iOS: x; HarmonyOS: x挖孔、刘海区域右下角横坐标,单位为px
topnumber-Web: x; 微信小程序: x; Android 系统版本: 9.0; Android: 4.31; iOS: x; HarmonyOS: x挖孔、刘海区域左上角纵坐标,单位为px
bottomnumber-Web: x; 微信小程序: x; Android 系统版本: 9.0; Android: 4.31; iOS: x; HarmonyOS: x挖孔、刘海区域右下角纵坐标,单位为px

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

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

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

下图标注了各区域信息

安全区域说明 @safearea

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

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文档

::: warning 注意事项

  • 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 alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见 ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/get-window-info/get-window-info

appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/get-window-info/get-window-info

示例

vue
<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 data.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>
      <view class="uni-btn-v">
        <navigator url="/pages/API/get-window-info/window-area">
          <button type="primary">窗口各区域示例</button>
        </navigator>
      </view>
    </view>
  </view>
</template>
<script setup lang="uts">
  import { setStatusBarHeight, setSafeArea } from '@/store/index.uts'
  // #ifdef APP-ANDROID
  import type { SafeArea } from '@/store/index.uts'
  // #endif

  type Item = {
    label : string,
    value : string,
  }

  type DataType = {
    items: Item[];
  }

  const title = ref('getWindowInfo')
  const data = reactive({
    items: [] as Item[],
  } as DataType)

  const getWindowInfo = () => {
    const res = uni.getWindowInfo();
    // 获取状态栏高度, 供截图对比使用
    setStatusBarHeight(res.statusBarHeight);
    // 获取安全区信息,供截图使用
    // #ifdef APP-ANDROID
    setSafeArea({
      top: res.safeArea.top,
      left: res.safeArea.left,
      right: res.safeArea.right,
      bottom: res.safeArea.bottom,
      width: res.safeArea.width,
      height: res.safeArea.height,
    } as SafeArea);
    // #endif
    // #ifdef APP-IOS
    setSafeArea({
      top: res.safeArea.top,
      left: res.safeArea.left,
      right: res.safeArea.right,
      bottom: res.safeArea.bottom,
      width: res.safeArea.width,
      height: res.safeArea.height,
    });
    // #endif
    data.items = [] as Item[];

    const res_str = JSON.stringify(res);
    const res_obj = JSON.parseObject(res_str);
    const res_map = res_obj!.toMap();
    let keys = [] as string[]
    res_map.forEach((_, key) => {
      keys.push(key);
    });
    keys.sort().forEach(key => {
      const value = res[key];
      if (value != null) {
        const item = {
          label: key,
          value: "" + ((typeof value == "object") ? JSON.stringify(value) : value)
        } as Item;
        data.items.push(item);
      }
    });
  }

  onReady(() => {
    getWindowInfo()
  })

</script>

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

:::

参见

通用类型

GeneralCallbackResult

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息