窗口模式设置
在鸿蒙跨设备应用开发中,窗口形态适配是提升多设备体验的关键。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",否则窗口模式不生效。
更多推荐

所有评论(0)