uni.getWindowInfo()

同步获取窗口信息

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 alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

扫码体验

示例

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

示例源码如下，请查看 pre > code 标签中的内容

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

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

通用类型

GeneralCallbackResult

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是			错误信息