窗口焦点
====

#### 场景介绍

**窗口焦点（Window Focus）** 是指在某一屏幕组内，当前能够接收键盘事件的窗口所具有的状态。系统通过焦点机制确保用户输入被正确路由到目标界面组件。

在一个屏幕组中，有且仅有一个窗口处于焦点状态，该窗口被称为**焦点窗口（Focused Window）** 。焦点窗口不仅能够响应键盘输入，还可在资源调度中享有更高优先级，例如在渲染、任务执行等方面获得系统倾斜。只有当窗口成功获取焦点后，系统方可拉起输入法进行输入。

#### 基本概念和机制介绍

#### \[h2\]屏幕组

屏幕组是系统中一组逻辑上关联的显示区域，每个屏幕组独立维护其窗口栈和焦点状态。**每个屏幕组内有且仅有一个焦点窗口**，不同屏幕组之间的焦点互不影响。

#### \[h2\]窗口焦点状态

**窗口焦点状态（Focus State）** 表示当前窗口是否能接收用户输入事件（如点击、按键等）。

*   主要状态如下所示：
    
    *   WINDOW\_ACTIVE：窗口已获焦，可响应用户操作。
        
    *   WINDOW\_INACTIVE：窗口失焦，无法接收输入。
        
*   典型场景：应用启动后自动获焦；切换到其他应用时原窗口失焦。
    
*   可通过[on('windowEvent')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onwindowevent10)接口监听窗口焦点状态的变化。
    

#### \[h2\]窗口激活态管理

**窗口激活态（Highlight State）** 表示当前窗口是否处于“视觉高亮”状态，“视觉高亮”是一种UI反馈机制，通过改变窗口的外观（如标题栏颜色、边框样式、透明度、阴影等）来向用户传达：这个窗口当前是活跃的、可交互的，或者正在被系统强调。

*   窗口激活态支持应用窗口（包括主窗口和子窗口），不支持系统窗口。
    
*   窗口处于激活态不等于窗口获焦；但获焦窗口一定处于激活态。
    
*   具有独占激活和非独占激活两种模式。
    
    *   独占激活模式：仅一个窗口处于高亮，该应用的其他窗口自动失去高亮。
        
    *   非独占激活模式：应用内多个窗口（如父窗口和子窗口）同时高亮。
        
*   独占激活典型场景：多子窗应用中，仅当前操作的子窗标题栏处于高亮。
    
*   非独占激活典型场景：在专业设计工具中，用户同时操作主视图和参数设置面板，系统允许这两个窗口同时高亮，以表明它们都处于活跃交互状态。
    
*   可通过[on('windowHighlightChange')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onwindowhighlightchange15)接口监听窗口激活态的变化。
    

#### 焦点相关开发场景

| 功能 | 典型场景 | 对应接口 |
| :-- | :-- | :-- |
| 监听窗口焦点变化 | 监听窗口焦点变化，以在窗口失焦时控制后台行为，如暂停动画、释放资源等。 | [on('windowEvent')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onwindowevent10) |
| 监听窗口激活态变化 | 监听窗口激活态变化，用于动态调整UI样式，如标题栏颜色、边框等。 | [on('windowHighlightChange')](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#onwindowhighlightchange15) |
| 设置窗口是否可获焦 | 控制某个窗口是否参与焦点竞争。例如横幅消息通知，设置不可获焦，不打断用户输入法输入 | [setWindowFocusable()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#setwindowfocusable9) |
| 在同应用内转移窗口焦点 | 进行应用内部多个窗口之间的焦点切换，确保流畅的焦点导航体验。例如，多窗口界面切换编辑窗口等。 | [shiftAppWindowFocus()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-f#windowshiftappwindowfocus11) |
| 判断窗口是否获焦 | 进行窗口获焦状态的判断，可用于防止非活跃窗口执行敏感操作。 | [isFocused()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#isfocused12) |
| 设置窗口是否独占激活 | 
设置窗口为独占激活时，可用于聚焦窗口操作，提升用户注意力。

设置窗口为非独占激活时，可用于多标签页设计，支持多个窗口同时保持高亮。

 | [setExclusivelyHighlighted()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#setexclusivelyhighlighted15) |
| 查询窗口是否为激活态 | 判断当前窗口是否处于视觉高亮，可用于UI状态同步等场景。 | [isWindowHighlighted()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#iswindowhighlighted18) |
| 显示当前窗口 | 

可用于显示主窗口、子窗口、全局悬浮窗及系统窗口。

如果传入focusOnShow: false，窗口显示时不可获焦。

 | [showWindow(options: ShowWindowOptions)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#showwindow20) |

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ec/v3/c3VCnUERQ4Gu2ulXZikrrw/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132328Z&HW-CC-Expire=86400&HW-CC-Sign=8C57E75C0460967DED102831A92EDBB2C237F8D8739FC8F7C29BDEB488DF0301)

*   针对监听类接口：请使用对应的off()接口在页面销毁时移除相关监听，以避免内存泄露。
    
*   页面加载优于显示：在调用showWindow()显示窗口等接口时，请确保已使用loadContent()或setUIContent等接口完成页面的加载。
    
*   合理使用窗口独占激活模式：避免滥用[setExclusivelyHighlighted()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#setexclusivelyhighlighted15)导致用户体验割裂。
    
*   状态查询和监听接口的结合使用：首次进入页面可使用isWindowHighlighted()/isFocused()获取初始状态，再通过对应的on('windowHighlightChange')/on('windowEvent')接口监听后续变化以实现相关适配和操作。