1# ArkUI子系统Changelog 2 3## cl.arkui.1 半模态底部样式最大高度默认避让状态栏安全区 4 5**访问级别** 6 7公开接口 8 9**变更原因** 10 11UX规格变更。 12 13半模态底部样式最大高度默认避让状态栏安全区。 14 15**变更影响** 16 17此变更不涉及应用适配。 18 19场景1：竖屏下，状态栏隐藏时，半模态底部样式最大高度也需要避让状态栏安全区。 20 21- 变更前：状态栏隐藏时，半模态底部样式最大高度距离屏幕上边界8vp，未避让状态栏安全区。 22- 变更后：API version 18及以后，状态栏隐藏时，半模态底部样式最大高度距离状态栏下边界8vp，避让状态栏安全区。该样式的最大高度为屏幕高度 - (窗口状态栏安全区高度 + 安全间距8vp)。 23 24| 变更前 | 变更后 | 25|------ |--------| 26||| 27 28场景2：横屏下，状态栏不隐藏时，半模态底部样式最大高度也需要避让状态栏安全区。 29 30- 变更前：状态栏不隐藏时，半模态底部样式最大高度距离屏幕上边界8vp，未避让状态栏安全区，且与状态栏区域重合。 31- 变更后：API version 18及以后，状态栏不隐藏时，半模态底部样式最大高度距离状态栏下边界8vp，避让状态栏安全区。该样式的最大高度为屏幕高度 - (窗口状态栏安全区高度 + 安全间距8vp)。 32 33| 变更前 | 变更后 | 34|------ |--------| 35||| 36 37**起始API Level** 38 3911 40 41**变更发生版本** 42 43从OpenHarmony SDK 5.1.0.54 版本开始。 44 45**变更的接口/组件** 46 47bindSheet的LARGE属性 48 49**适配指导** 50 51若开发者自定义的builder面板内容是固定高度，建议使用100%布局，变更后自定义的内容也可以自动撑满半模态面板。 52 53若按变更前的最大高度规格限制的builder内容，需要变更为新规格计算。 54 55## cl.arkui.2 sharedTransition在id入参为undefined或空字符串时的行为变更 56 57**访问级别** 58 59公开接口 60 61**变更原因** 62 63sharedTransition的id从非空字符串变为空字符串或undefined时，无法实现清空共享元素转场id的效果。 64 65**变更影响** 66 67此变更涉及应用适配，API18之前不变，API18及以后，发生变更。 68 69变更前：sharedTransition的id从非空字符串变为空字符串或undefined时，会维持之前的有效id值。 70 71变更后：sharedTransition的id从非空字符串变为空字符串或undefined时，会将共享元素转场id置为空字符串，达到取消sharedTransition匹配的效果。 72 73**起始API Level** 74 75API 7 76 77**变更发生版本** 78 79从OpenHarmony SDK 5.1.0.54版本开始。 80 81**变更的接口/组件** 82 83common.d.ts文件的sharedTransition接口 84 85**适配指导** 86 87开发者如果希望同一组件的sharedTransition的id维持有效值不变，且开发者已经主动设置id为空字符串或undefined时，需要适配。适配方式为不更改sharedTransition的id，维持之前的有效值不变。其余情况无需适配。 88 89 90## cl.arkui.3 bindSheet在2in1设备中默认避让窗口安全区 91 92**访问级别** 93 94公开接口 95 96**变更原因** 97 98UX规格变更。 99 100半模态内容需默认避让窗口安全区，否则会有重叠区域。 101 102**变更影响** 103 104此变更涉及应用适配。 105 106当自由窗口标题栏类型为悬浮标题栏时，需要半模态面板默认避让标题安全区。 107 108场景1：半模态居中弹窗样式 109 110- 变更前：半模态居中弹窗样式的面板最大高度为窗口高度的90%。 111- 变更后：该样式的最大高度为窗口高度 - (窗口安全区高度 + 安全间距8vp) * 2。 112 113| 变更前 | 变更后 | 114|------ |--------| 115||| 116 117场景2：半模态底部弹窗样式 118 119- 变更前：半模态底部弹窗样式的面板最大高度为窗口高度 - 8vp。 120- 变更后：该样式的最大高度为窗口高度 - (窗口安全区高度 + 安全间距8vp)。 121 122| 变更前 | 变更后 | 123|------ |--------| 124||| 125 126**起始API Level** 127 12811 129 130**变更发生版本** 131 132从OpenHarmony SDK 5.1.0.54版本开始。 133 134**变更的接口/组件** 135 136bindSheet的preferType属性 137 138**适配指导** 139 140若开发者自定义的builder面板内容是固定高度，建议使用100%布局，变更后自定义的内容也可以自动撑满半模态面板。 141 142若按变更前的最大高度规格限制的builder内容，需要变更为新规格计算。 143 144## cl.arkui.4 XComponent设置为Texture模式使用blendMode接口的行为由不生效变更为正常生效 145**访问级别** 146 147公开接口 148 149**变更原因** 150 151用户使用XComponent组件并设置为Texture模式时，使用blendMode接口没有效果，不符合接口正常规格，需要变更为blendMode接口正常生效。 152 153**变更影响** 154 155此变更涉及应用适配。 156 157变更前：XComponent组件设置为Texture模式，使用blendMode接口不生效。 158 159变更后：XComponent组件设置为Texture模式，使用blendMode接口正常生效。 160 161**起始API Level** 162 163API 11 164 165**变更发生版本** 166 167从OpenHarmony SDK 5.1.0.54开始。 168 169**变更的接口/组件** 170 171common.d.ts文件的blendMode接口。 172 173**适配指导** 174 175需适配场景： 176当应用使用XComponent组件并设置为Texture模式（`type`设置为`XComponentType.TEXTURE`）时，使用blendMode接口，可能会出现显示效果变更前后不一致的情况，以下是使用场景示意： 177 178```ts 179@Entry 180@Component 181struct Index { 182 private contextOne: Record<string, () => void> = {}; 183 private contextTwo: Record<string, () => void> = {}; 184 185 build() { 186 Column() { 187 Stack() { 188 XComponent({ 189 id: 'circle', 190 type: XComponentType.TEXTURE, 191 libraryname: 'nativerender' 192 }).height(50) 193 .backgroundColor(Color.Transparent) 194 .onLoad((contextOne?: object | Record<string, () => void>) => { 195 if (contextOne) { 196 this.contextOne = contextOne as Record<string, () => void>; 197 } 198 }) 199 200 XComponent({ 201 id: 'rect', 202 type: XComponentType.TEXTURE, 203 libraryname: 'nativerender' 204 }).height(50) 205 .backgroundColor(Color.Transparent) 206 .onLoad((contextTwo?: object | Record<string, () => void>) => { 207 if (contextTwo) { 208 this.contextTwo = contextTwo as Record<string, () => void>; 209 } 210 }) 211 .blendMode(BlendMode.XOR) // 变更后生效，若需保持变更前行为，可使用BlendMode.None入参 212 } 213 .height(50) 214 .onClick(() => { 215 if (this.contextOne) { 216 this.contextOne.drawCircle(); 217 } 218 if (this.contextTwo) { 219 this.contextTwo.drawRectangle(); 220 } 221 }) 222 } 223 .blendMode(BlendMode.SRC_OVER, BlendApplyType.OFFSCREEN) 224 .width('100%') 225 .height('100%') 226 } 227} 228``` 229| 混合类型 | 变更前 | 变更后 | 230| ------- | - | ---- | 231| BlendMode.XOR |  |  | 232| BlendMode.NONE |  |  | 233 234应用若需保持变更前行为，XComponent组件上的blendMode接口使用BlendMode.None入参即可。 235 236## cl.arkui.5 半模态跟手样式弹窗显示位置避让规则变更 237**访问级别** 238 239公开接口 240 241**变更原因** 242 243基础能力增强，半模态跟手样式弹窗支持开发者自定义弹出方向，并根据位置避让流程决定弹窗最终显示位置 244 245**变更影响** 246 247此变更不涉及应用适配， 248 249变更前行为：半模态跟手样式弹窗默认弹出位置为绑定组件底部，会根据剩余空间情况同绑定组件左边和右边作对齐布局，不做任何半模态面板高度的压缩。 250 251变更后行为：开发者可使用bindOptions中的placement(设置弹窗默认弹出位置，默认值Bottom) 和 placementOnTarget(所有位置均放不下时，是否允许弹窗覆盖在绑定节点上)两个字段，自定义半模态跟手样式弹窗相关的弹出位置信息。半模态跟手样式弹窗在确保指定位置能容纳弹窗尺寸的前提下，优先依据设定的placement展示弹窗。若不可行，则遵循先垂直翻转，后尝试90°水平旋转的规则调整显示位置，以预设方向为下方为例，调整顺序依次为：下、上、右、左。如果设置的对齐方式导致组件布局超出窗口范围，将根据该对齐方式在水平或垂直方向上进行位移，直至组件完全显示在窗口内。如果在四个方向上均无法容纳跟手样式弹窗，处理方式遵循开发者设置的placementOnTarget属性。若属性值为True，将依据设定的placement，向其镜像方向平移，直至弹窗能够完全显示，且允许覆盖在绑定的弹出节点上；若属性值为false，则在四个方向中，选择能够完全展示弹窗宽度且剩余高度最大的方向，通过调整半模态高度以适应当前方向，确保弹窗能够放下，同时保持预设placement对应的对齐方式不变。 252 253| 场景 | 变更前 | 变更后placementOnTarget为true | 变更后placementOnTarget为false | 254|------ |------ |--------|--------| 255|半模态跟手弹窗大小过大导致底部空间不足以容纳弹窗面板|||| 256 257| 场景 | 变更前 | 变更后 | 258|------ |--------|--------| 259|半模态跟手弹窗弹出位置过于靠近左侧边界导致左侧剩余空间不足以保持同绑定节点居中对齐||| 260|半模态跟手弹窗弹出位置过于靠近右侧边界导致右侧剩余空间不足以保持同绑定节点居中对齐||| 261|半模态绑定的弹出节点在y轴位置上更偏底部，但绑定节点的底部空间不足以容纳半模态弹窗面板，而顶部空间足以容纳||| 262|半模态绑定的弹出节点在x轴位置上更偏左边，但绑定节点的底部、顶部空间不足以容纳半模态弹窗面板，而右边空间足以容纳||| 263|半模态绑定的弹出节点在x轴位置上更偏右边，但绑定节点的底部、顶部、右边空间不足以容纳半模态弹窗面板，而左边空间足以容纳||| 264 265**起始API Level** 266 26711 268 269**变更发生版本** 270 271从OpenHarmony SDK 5.1.0.54 版本开始。 272 273**变更的接口/组件** 274 275bindSheet 276SheetType.POPUP 277 278**适配指导** 279 280默认行为变更，开发者无需适配。若API version 18前，希望实现的效果为位于弹出节点底部并且同弹出节点左对齐或者右对齐，那么在API version 18及以后，可以通过设置字段placement的值为BottomLeft或BottomRight，来实现对应显示效果。 281 282 283## cl.arkui. 6当使用自定义组件名和系统组件属性重名时编译报错变更 284 285**访问级别** 286 287公开接口 288 289**变更原因** 290 291当使用的自定义组件名称与系统组件属性名称相同时，编译过程将依据系统组件属性列表进行校验。如果该属性未在系统组件属性列表中列出，编译过程将无法识别，导致编译后的产物出现问题。 292 293**变更影响** 294 295该变更涉及应用适配。 296 297举例说明，执行以下用例： 298 299```ts 300@Entry 301@Component 302struct enableAnalyzer { 303 build() { 304 Canvas() 305 .enableAnalyzer(true) 306 } 307} 308``` 309 310变更前：当开发者定义的自定义组件名称与系统组件属性名称重名时，部分重名名称在编译过程中不会被拦截，导致运行时崩溃。 311 312变更后：当自定义组件名称与系统组件属性名称发生同名冲突时，编译阶段将触发错误拦截机制并报错。 313 314 315 316**起始API Level** 317 318API 10 319 320**变更发生版本** 321 322从OpenHarmony SDK 5.1.0.54开始。 323 324**变更的接口/组件** 325 326ArkUI 系统组件属性API。 327 328**适配指导** 329 330自定义组件名和系统组件属性重名时，编译报错，修改自定义组件名为其他非系统组件属性名即可解决。 331 332修改前： 333 334自定义组件enableAnalyzer和Canvas的enableAnalyzer重名。 335 336```ts 337@Entry 338@Component 339struct enableAnalyzer { 340 build() { 341 Canvas() 342 .enableAnalyzer(true) 343 } 344} 345``` 346 347修改后： 348 349将自定义组件名改为任意不和系统组件重名的名称，如EnableAnalyzerComp。 350 351```ts 352@Entry 353@Component 354struct EnableAnalyzerComp { 355 build() { 356 Canvas() 357 .enableAnalyzer(true) 358 } 359} 360``` 361
