在鸿蒙跨设备应用开发中,窗口形态适配是提升多设备体验的关键。supportWindowMode 作为 module.json5 配置文件中的核心属性,专门用于声明 UIAbility 支持的窗口运行模式,直接决定应用在手机、平板、PC、折叠屏等设备上的展示形态,是实现智慧多窗、悬浮窗、分屏功能的基础配置。

一、属性核心定义
  supportWindowMode 是字符串数组类型的可缺省配置项,用于声明当前 UIAbility 支持的窗口运行模式,缺省默认值为 ["fullscreen", "split", "floating"],即同时支持全屏、分屏、悬浮窗三种模式。


二、可配置取值与含义
  该属性支持三种固定取值,对应不同的窗口展示形态:
fullscreen
基础配置,窗口支持全屏显示,是应用最常见的运行模式。
split
窗口支持分屏显示,可与其他应用并排运行,充分利用大屏空间。
floating
多设备差异化形态:手机 / 折叠屏为悬浮窗;平板为悬浮窗 + 自由多窗;PC 为自由多窗,支持窗口自由拖拽、缩放。


三、标准配置位置与示例
  supportWindowMode 需配置在 module.json5 文件的 abilities 节点下,与 UIAbility 基础配置同级。
配置示例

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1",
      "pc"
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "label": "$string:EntryAbility_label",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "exported": true,
       
        "supportWindowMode": ["fullscreen", "split", "floating"],
        // 可选:横向悬浮窗配置(游戏/视频类应用)
        "preferMultiWindowOrientation": "landscape"
      }
    ]
  }
}



四、supportWindowMode是静态配置,不支持根据设备类型动态调整。若希望在平板或2in1设备上动态设置窗口模式(例如在PC启动时默认为悬浮窗),需在UIAbility的onWindowStageCreate生命周期中,通过windowStage.setSupportedWindowModes()方法进行设置,并配合windowClass.recover()将窗口切换为悬浮窗。


五、关键注意事项
 启动模式优先级规则
同时配置 fullscreen 和 split 时,应用启动模式受 targetAPIVersion 影响:
API 版本 < 15:默认以悬浮窗启动
API 版本 ≥ 15:默认以全屏启动
强制布局适配
开启多窗模式后,必须实现自适应 / 响应式布局,监听 windowSizeChange 事件动态调整 UI,避免窗口缩放后内容挤压、截断。
PC 设备必配项
适配 PC / 二合一设备时,需在 deviceTypes 中追加 "2in1",否则窗口模式不生效。

Logo

社区规范:仅讨论OpenHarmony相关问题。

更多推荐