1# ArkUI子系统Changelog 2 3## cl.arkui.1 弹窗类组件适配系统窗口安全区 4 5**访问级别** 6 7公开接口 8 9**变更原因** 10 11系统类型窗口下，弹窗类组件未避让安全区，导致弹窗显示内容与状态栏、导航条发生重叠 12 13**变更影响** 14 15该变更不涉及应用适配 16 17变更前：系统类型窗口下，弹窗类组件未避让安全区，显示内容与状态栏、导航条重叠 18 19变更后：系统类型窗口下，弹窗类组件避让安全区，显示内容与状态栏、导航条不重叠 20 21 22| 组件 | 变更前 | 变更后 | 23| :---: | :---: | :---: | 24| Menu (无预览图) | <img width=150px src="figures/avoidSafeArea/menu1_1.png"> <br> <img width=150px src="figures/avoidSafeArea/menu2_1.png"> | <img width=150px src="figures/avoidSafeArea/menu1_2.png"> <br> <img width=150px src="figures/avoidSafeArea/menu2_2.png"> | 25| Menu (有预览图) | <img width=150px src="figures/avoidSafeArea/menu3_1.png"> <br> <img width=150px src="figures/avoidSafeArea/menu4_1.png"> | <img width=150px src="figures/avoidSafeArea/menu3_2.png"> <br> <img width=150px src="figures/avoidSafeArea/menu4_2.png"> | 26| Popup | <img width=150px src="figures/avoidSafeArea/popup1_1.png"> <br> <img width=150px src="figures/avoidSafeArea/popup2_1.png"> | <img width=150px src="figures/avoidSafeArea/popup1_2.png"> <br> <img width=150px src="figures/avoidSafeArea/popup2_2.png"> | 27| Dialog | <img width=150px src="figures/avoidSafeArea/dialog1_1.png"> <br> <img width=150px src="figures/avoidSafeArea/dialog2_1.png"> | <img width=150px src="figures/avoidSafeArea/dialog1_2.png"> <br> <img width=150px src="figures/avoidSafeArea/dialog2_2.png"> | 28| Toast | <img width=150px src="figures/avoidSafeArea/toast1_1.png"> <br> <img width=150px src="figures/avoidSafeArea/toast2_1.png"> | <img width=150px src="figures/avoidSafeArea/toast1_2.png"> <br> <img width=150px src="figures/avoidSafeArea/toast2_2.png"> | 29 30**起始API Level** 31 32Menu: API 7 33 34Popup: API 7 35 36Dialog: API 7 37 38Toast: API 9 39 40**变更发生版本** 41 42从OpenHarmony SDK 5.1.0.50开始。 43 44**变更的接口/组件** 45 46Menu组件、Dialog组件、Popup组件、Toast组件。 47 48**适配指导** 49 50默认避让行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则应自定义修改效果控制变量以达到预期。 51 52## cl.arkui.2 animation动画接口在播放次数为无限循环时的行为变更 53 54**访问级别** 55 56公开接口 57 58**变更原因** 59 60布局过程中触发的同步回调里所做的修改，可能会被纳入animation的无限循环动画中，产生预期外的无限循环动画且无法停止。 61 62**变更影响** 63 64此变更涉及应用适配。 65 66变更前：在调用无限循环的animation动画接口时，若在布局过程中触发的同步回调里进行修改，这些修改可能会被纳入无限循环动画中，从而导致产生非预期的无限循环动画，且该动画将无法停止。 67 68变更后：在调用无限循环的animation动画接口时，为避免布局过程中触发的同步回调里所做的修改被纳入animation无限循环动画中，动画闭包开启前将执行最多两次额外刷新作为保护措施。对于两次额外刷新仍无法有效保护的场景，其表现将与原有行为一致，同样可能产生无限循环动画。 69 70**起始API Level** 71 72API 7 73 74**变更发生版本** 75 76从OpenHarmony SDK 5.1.0.49开始。 77 78**变更的接口/组件** 79 80common.d.ts文件animation接口。 81 82**适配指导** 83 84为避免布局过程中触发的同步回调里所做的修改被纳入animation无限循环动画，应将修改置于恰当的逻辑，即相对独立时机的事件中，如onClick事件。如果不需要产生动画，直接在onClick事件中设置即可，如果需要产生动画，需要在onClick事件中显式的将操作写入animateTo动画。 85适配后： 86 87```ts 88@Entry 89@Component 90struct AttrAnimationExample { 91 @State rotateAngle: number = 0 92 @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 93 scroller:Scroller = new Scroller(); 94 @State h: number|string = "70%"; 95 96 build() { 97 Column() { 98 List({space:10, scroller:this.scroller}) { 99 ForEach(this.arr, (index: number, item: number)=>{ 100 ListItem() { 101 Text(item.toString()) 102 } 103 .height(200) 104 .borderRadius(10) 105 .backgroundColor(0xDCDCDC) 106 .width("100%") 107 }) 108 } 109 .width("100%") 110 .height(this.h) 111 // 在当前页面存在触发动效逻辑的情况下，不建议将操作放在同步回调中执行，建议写法参考onClick事件中的注释 112 // .onSizeChange((oldValue: SizeOptions, newValue: SizeOptions)=>{ 113 // this.scroller.scrollEdge(Edge.Bottom) // 同步回调中触发的操作可能会被纳入animation无限动画，产生预期外的效果 114 // }) 115 116 Button('click') 117 .rotate({ angle: this.rotateAngle }) 118 .animation({ 119 duration: 1000, 120 curve: Curve.Linear, 121 iterations: -1, // 设置-1表示动画无限循环 122 }) 123 .onClick(() => { 124 this.h = "80%" 125 this.rotateAngle = 360 126 127 // 无需产生动画，在onClick中直接设置即可 128 // this.scroller.scrollEdge(Edge.Bottom) 129 130 // 需要产生动画，在animateTo中设置 131 // animateTo({}, () => { 132 // this.scroller.scrollEdge(Edge.Bottom) 133 // }) 134 }) 135 } 136 .width('100%') 137 } 138} 139``` 140 141## cl.arkui.3 滚动类组件（List、Scroll、Grid、WaterFlow）和Refresh组件过界跟手系数变更 142 143**访问级别** 144 145公开接口 146 147**变更原因** 148 149滚动类组件（List、Scroll、Grid、WaterFlow）和Refresh组件最大下拉过界距离太大，需要调整过界跟手系数，优化体验。 150 151**变更影响** 152 153此变更不涉及应用适配。 154 155| 变更前 | 变更后 | 156|---------|---------| 157| 滚动类组件和Refresh组件下拉过界时，相同手指滑动，下拉过界距离较大。<br>  | 滚动类组件和Refresh组件下拉过界时，相同手指滑动，下拉过界距离较小。 <br>  | 158| <br>  | <br>  | 159 160**起始API Level** 161 162API 7 163 164**变更发生版本** 165 166从OpenHarmony SDK 5.1.0.52开始。 167 168**变更的接口/组件** 169 170ArkUI 滚动类组件（List、Scroll、Grid、WaterFlow）和Refresh组件。 171 172**适配指导** 173 174变更后下拉过界效果更优，无需适配。 175 176## cl.arkui.4 轴事件支持BEGIN、END及CANCEL类型回调触发 177 178**访问级别** 179 180公开接口 181 182**变更原因** 183 184开发者无法监听到轴事件的BEGIN、END、CANCEL类型的事件回调。 185 186**变更影响** 187 188此变更不涉及应用适配。 189 190变更前：开发者通过OH_NativeXComponent_RegisterUIInputEventCallback接口监听轴事件回调，无法收到BEGIN、END、CANCEL类型的事件回调。 191 192变更后：开发者通过OH_NativeXComponent_RegisterUIInputEventCallback接口监听轴事件回调，可以收到BEGIN、END、CANCEL类型的事件回调。 193 194**起始API Level** 195 196API 12 197 198**变更发生版本** 199 200从OpenHarmony SDK 5.1.0.50开始。 201 202**变更的接口/组件** 203 204OH_NativeXComponent_RegisterUIInputEventCallback接口。 205 206**适配指导** 207 208默认行为变更，无需适配。 209 210## cl.arkui.6 CanvasRenderingContext2D的drawImage接口联合阴影绘制由阴影无法正确绘制变更为阴影正确绘制 211 212**访问级别** 213 214公开接口 215 216**变更原因** 217 218drawImage同名接口根据传入参数的不同，视为不同方法。当drawImage传入image、dx和dy三个参数，且与阴影颜色（shadowColor）、阴影偏置距离（shadowOffsetX和shadowOffsetY）联合绘制时，阴影无法正确绘制。变更后，阴影可以正确绘制。 219 220**变更影响** 221 222该变更涉及应用适配。 223 224- 变更前：当drawImage接口传入image、dx和dy三个参数，且与阴影进行联合绘制时，阴影无法正确绘制。 225- 变更后：当drawImage接口传入image、dx和dy三个参数，且与阴影进行联合绘制时，阴影可以正确绘制。 226 227| 变更前 | 变更后 | 228| :---------------------------------: | :-------------------------------: | 229|  |  | 230 231**起始API Level** 232 2339 234 235**变更发生版本** 236 237从OpenHarmony SDK 5.1.0.50 版本开始。 238 239**变更的接口/组件** 240 241CanvasRenderingContext2D的drawImage接口 242 243**适配指导** 244 245变更后，使用drawImage接口与阴影进行联合绘制时，阴影能够被正确绘制。 246 247**示例** 248 249```ts 250@Entry 251@Component 252struct Page1 { 253 private settings: RenderingContextSettings = new RenderingContextSettings(true) 254 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 255 private img: ImageBitmap = new ImageBitmap("common/images/example.png") 256 257 build() { 258 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 259 Canvas(this.context) 260 .width('100%') 261 .height('100%') 262 .onReady(() => { 263 this.context.shadowColor = "rgb(213,213,213)" 264 this.context.shadowOffsetX = 40 265 this.context.shadowOffsetY = 40 266 this.context.drawImage(this.img, 20, 20) 267 }) 268 } 269 .width('100%') 270 .height('100%') 271 } 272} 273``` 274 275## cl.arkui.7 CanvasRenderingContext2D的measureText接口测算文本的结果变更 276 277**访问级别** 278 279公开接口 280 281**变更原因** 282 283在运用measureText接口进行文本尺寸测量时，在下述场景1与场景2中，所测得的文本宽度呈现异常值： 284- 场景1：当Context与某一Canvas解除绑定后，再与另一Canvas重新绑定时，若未重新设定font属性，或在重新设定font属性时遗漏了font-size的指定，那么在绘制文本时将采用重置后的font-size（即默认值）。然而，在进行文本尺寸测量时，系统会错误地沿用前一Canvas中设定的font-size，从而导致文本宽度测量结果出现偏差。 285- 场景2：在font属性的设定过程中，若首次已明确指定font-style，而第二次设定了不同的font-style，虽然在绘制文本时会采用新设定的font-style，但在进行文本尺寸测量时，系统却依旧沿用上一次设定的font-style，同样造成文本宽度测量结果的不准确。 286 287**变更影响** 288 289该变更不涉及应用适配。 290 291使用measureText接口进行文本测算时： 292 293- 变更前：在场景1和场景2中，文本测算得到的文本宽度均为错误值。 294- 变更后：在场景1和场景2中，文本测算得到的文本宽度均为正确值。 295 296运行场景1的示例： 297 298```ts 299@Entry 300@Component 301struct example1 { 302 private settings: RenderingContextSettings = new RenderingContextSettings(true) 303 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 304 @State flag: boolean = false 305 306 build() { 307 Column() { 308 Button('transfer') 309 .position({x:200, y:0}) 310 .width(100) 311 .height(40) 312 .onClick(() => { 313 this.flag = !this.flag 314 }) 315 Canvas(this.context) 316 .position({x:100, y:45}) 317 .width('300') 318 .height('100') 319 .backgroundColor('rgb(39,135,237)') 320 .onReady(() => { 321 this.context.textAlign = 'center' 322 this.context.font = '20vp' 323 this.context.fillText('width:' + this.context.measureText('Hello World').width, this.context.width/2, 30) 324 }) 325 if (this.flag) { 326 Canvas(this.context) 327 .position({x:100, y:145}) 328 .width('300') 329 .height('100') 330 .backgroundColor('rgb(213,213,213)') 331 .onReady(() => { 332 this.context.textAlign = 'center' 333 this.context.fillText('width:' + this.context.measureText('Hello World').width, this.context.width/2, 30) 334 }) 335 } 336 } 337 .width('100%') 338 .height('100%') 339 } 340} 341``` 342 343| 变更前 | 变更后 | 344| :----------------------------------------: | :-------------------------------------: | 345|  |  | 346 347运行场景2的示例： 348 349```ts 350@Entry 351@Component 352struct example2 { 353 private settings: RenderingContextSettings = new RenderingContextSettings(true) 354 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 355 356 build() { 357 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 358 Canvas(this.context) 359 .width('100%') 360 .height('100%') 361 .backgroundColor('rgb(255,192,0)') 362 .onReady(() => { 363 this.context.font = 'italic 25vp' 364 this.context.fillText('width:' + this.context.measureText('Hello World').width, 10, 50) 365 this.context.font = 'normal' 366 this.context.fillText('width:' + this.context.measureText('Hello World').width, 10, 100) 367 }) 368 } 369 .width('100%') 370 .height('100%') 371 } 372} 373``` 374 375| 变更前 | 变更后 | 376| :----------------------------------------: | :-------------------------------------: | 377|  |  | 378 379**起始API Level** 380 3819 382 383**变更发生版本** 384 385从OpenHarmony SDK 5.1.0.50 版本开始。 386 387**变更的接口/组件** 388 389CanvasRenderingContext2D的measureText接口 390 391**适配指导** 392 393无需适配，但应注意变更后的行为是否对整体应用逻辑产生影响。 394 395## cl.arkui.8 CanvasRenderingContext2D的miterLimit接口，当传入参数为0时，其异常值的处理方式发生变更 396 397**访问级别** 398 399公开接口 400 401**变更原因** 402 403CanvasRenderingContext2D的miterLimit接口，当传入参数为0时，未按照默认值设置参数，与文档所规定的处理异常值的方式不符。 404 405**变更影响** 406 407该变更涉及应用适配。 408 409| 变更前 | 变更后 | 410| :---------------------------------: | :-------------------------------: | 411| 当传入参数0为时，未按照默认值进行参数设置。<br> | 当传入参数为0时，按照默认值进行参数设置。<br> | 412 413**起始API Level** 414 4159 416 417**变更发生版本** 418 419从OpenHarmony SDK 5.1.0.50 版本开始。 420 421**变更的接口/组件** 422 423CanvasRenderingContext2D的miterLimit接口 424 425**适配指导** 426 427变更后，使用miterLimit接口，当传入参数0为时，按照默认值进行参数设置，即miterLimit被设置为10。 428 429**示例** 430 431```ts 432@Entry 433@Component 434struct MiterLimit { 435 private settings: RenderingContextSettings = new RenderingContextSettings(true) 436 private context: CanvasRenderingContext2D = new CanvasRenderingContext2D(this.settings) 437 438 build() { 439 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 440 Canvas(this.context) 441 .width('100%') 442 .height('100%') 443 .backgroundColor('rgb(213,213,213)') 444 .onReady(() => { 445 this.context.lineWidth = 10 446 this.context.lineJoin = 'miter' 447 this.context.miterLimit = 0 448 this.context.moveTo(50, 30) 449 this.context.lineTo(170, 90) 450 this.context.lineTo(50, 150) 451 this.context.stroke() 452 }) 453 } 454 .width('100%') 455 .height('100%') 456 } 457} 458``` 459 460## cl.arkui.9 弹出框标题换行优先策略及内容区默认对齐方式变更 461 462**访问级别** 463 464公开接口 465 466**变更原因** 467 468弹窗标题及内容风格优化，增强用户体验。 469 470**变更影响** 471 472此变更不涉及应用适配。 473 474变更点1：弹窗标题超长换行优先规则变更。 475 476| 变更前 | 变更后 | 477|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| 478| 弹窗标题超长时，优先缩小字号，最小至9vp，然后再换行展示。<br>  | 弹窗标题超长时，优先换行，再缩小字号展示，最小至9vp。<br> | 479 480变更点2：弹窗内容超过一行时默认对齐行为变更。 481 482| 变更前 | 变更后 | 483|----------------------------------------------------------------------|------------------------------------------------------------------| 484| 弹窗内容多行文本时居左对齐。<br>  | 弹窗内容文本居中对齐。<br>  | 485 486**起始API Level** 487 488API 10 489 490**变更发生版本** 491 492从OpenHarmony SDK 5.1.0.50开始。 493 494**变更的接口/组件** 495 496advancedDialog 497 498**适配指导** 499 500默认行为变更，无需适配。系统弹窗默认规格优化演进，若开发者有其他布局、样式诉求，建议使用CustomDialog自定义实现。
