• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 窗口子系统变更说明
2
3## cl.window.1 在2in1设备上getWindowStatus和on('windowStatusChange')接口在窗口最大化状态返回值变更
4
5**访问级别**
6
7公开接口
8
9**变更原因**
10
11getWindowStatus和on('windowStatusChange') 接口在最大化状态返回值为 WindowStatusType::FULL_SCREEN，与实际情况不符合。
12
13应用无法直接通过这两个接口在2in1设备上区分当前最大化和全屏状态，与接口功能设计不符合。
14
15**变更影响**
16
17该变更为不兼容变更。
18
19变更前：2in1设备上调用getWindowStatus和on('windowStatusChange') 接口，在最大化状态返回值为WindowStatusType::FULL_SCREEN。
20
21变更后：2in1设备上调用getWindowStatus和on('windowStatusChange') 接口，在最大化状态返回值为WindowStatusType::MAXIMIZE。
22
23**起始 API Level**
24
25on('windowStatusChange')接口从API version 11开始支持
26
27在2in1设备上getWindowStatus接口从API version 12开始支持
28
29**变更发生版本**
30
31从OpenHarmony SDK 5.0.1.45开始。
32
33**变更的接口/组件**
34
35@ohos.window.d.ts
36
37系统能力：SystemCapability.Window.SessionManager
38
39接口：getWindowStatus、on('windowStatusChange')
40
41**适配指导**
42
43针对2in1设备上想要区分当前窗口最大化状态和全屏状态的场景，在变更前后的实现方案分别如下：
44
45- API version 13及之前的版本，可以在窗口状态为WindowStatusType::FULL_SCREEN的情况下，再调用[getImmersiveModeEnabledState()](../../../application-dev/reference/apis-arkui/js-apis-window.md#getimmersivemodeenabledstate12) 接口进行进一步判断，到底是最大化状态还是全屏状态。若接口返回true则表示当前窗口为全屏状态，若接口返回false则表示当前窗口为最大化状态。
46
47- API version 14及之后的版本，可以直接调用getWindowStatus、on('windowStatusChange')接口区分窗口最大化和全屏状态。
48
49  不过需要注意返回值的变更和代码适配：若应用针对WindowStatusType::FULL_SCREEN 和 WindowStatusType::MAXIMIZE状态的代码处理逻辑相同，则在对应的逻辑处理时，直接追加WindowStatusType::MAXIMIZE判断条件（条件或）即可；若应用针对WindowStatusType::FULL_SCREEN和 WindowStatusType::MAXIMIZE状态有不同的处理逻辑，则需要增加新的WindowStatusType::MAXIMIZE条件判断分支中进行窗口最大化状态相关逻辑的处理。
50
51以下示例以on('windowStatusChange') 接口为例，提供变更前后2in1设备上区分当前窗口最大化状态和全屏状态的指导和适配示例：
52
53API version 13及之前版本区分最大化状态示例：
54```ts
55// EntryAbility.ets
56import { BusinessError } from '@kit.BasicServicesKit';
57
58export default class EntryAbility extends UIAbility {
59  // ...
60  onWindowStageCreate(windowStage: window.WindowStage) {
61    console.info('onWindowStageCreate');
62    try {
63      let windowClass = windowStage.getMainWindowSync();
64      windowClass?.on("windowStatusChange", (windowStatusType: window.WindowStatusType) => {
65        if (windowStatusType == window.WindowStatusType.FULL_SCREEN) {
66          // isFullScreen 为true 表示全屏，为false 表示最大化
67          let isFullScreen: boolean = windowClass.getImmersiveModeEnabledState();
68        } else {
69          // ...
70        }
71      })
72    } catch (exception) {
73      console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
74    }
75  }
76}
77```
78
79API version 14版本区分最大化状态示例：
80```ts
81// EntryAbility.ets
82import { BusinessError } from '@kit.BasicServicesKit';
83
84export default class EntryAbility extends UIAbility {
85  // ...
86  onWindowStageCreate(windowStage: window.WindowStage) {
87    console.info('onWindowStageCreate');
88    try {
89      let windowClass = windowStage.getMainWindowSync();
90      windowClass?.on("windowStatusChange", (windowStatusType: window.WindowStatusType) => {
91        // 应用对于窗口全屏和最大化状态的处理逻辑不同，新增window.WindowStatusType.MAXIMIZE的判断分支
92        if (windowStatusType == window.WindowStatusType.FULL_SCREEN) {
93          // ....
94        } else if (windowStatusType == window.WindowStatusType.MAXIMIZE) {
95          // ...
96        } else {
97          // ...
98        }
99      })
100    } catch (exception) {
101      console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
102    }
103  }
104}
105```
106
107API version 14版本不区分最大化状态示例：
108```ts
109// EntryAbility.ets
110import { BusinessError } from '@kit.BasicServicesKit';
111
112export default class EntryAbility extends UIAbility {
113  // ...
114  onWindowStageCreate(windowStage: window.WindowStage) {
115    console.info('onWindowStageCreate');
116    try {
117      let windowClass = windowStage.getMainWindowSync();
118      windowClass?.on("windowStatusChange", (windowStatusType: window.WindowStatusType) => {
119        // 应用对于窗口全屏和最大化状态的处理逻辑相同，直接在判断时新增针对window.WindowStatusType.MAXIMIZE的或条件
120        if (windowStatusType == window.WindowStatusType.FULL_SCREEN ||
121            windowStatusType == window.WindowStatusType.MAXIMIZE) {
122          // ....
123        } else {
124          // ...
125        }
126      })
127    } catch (exception) {
128      console.error(`Failed to obtain the main window. Cause code: ${exception.code}, message: ${exception.message}`);
129    }
130  }
131}
132```
133
134## cl.window.2 在2in1设备上hasImmersiveWindow接口在窗口最大化状态返回值变更
135
136**访问级别**
137
138系统接口
139
140**变更原因**
141
142在2in1设备上调用hasImmersiveWindow接口在窗口处于最大化状态时返回true，与实际情况不符合。
143
144无法通过这个接口在2in1设备上区分是否有窗口处于最大化状态，还是全屏状态，与接口功能设计不符合。
145
146**变更影响**
147
148该变更为不兼容变更。
149
150变更前：2in1设备上调用hasImmersiveWindow接口时，如果窗口处于最大化状态时下，则返回true。
151
152变更后：2in1设备上调用hasImmersiveWindow接口时，如果窗口处于最大化状态时下，则返回false。
153
154**起始 API Level**
155
156hasImmersiveWindow接口从API version 11开始支持
157
158**变更发生版本**
159
160从OpenHarmony SDK 5.0.1.45开始。
161
162**变更的接口/组件**
163
164@ohos.display.d.ts
165
166系统能力：SystemCapability.Window.SessionManager
167
168接口：hasImmersiveWindow
169
170**适配指导**
171
172排查应用实现中是否存在调用hasImmersiveWindow判断当前屏幕是否包含全屏窗口的场景。若涉及，需要根据返回值变更进行调整适配。
173