1# ArkUI子系统Changelog 2 3## cl.arkui.1 TextClock组件构造参数timeZoneOffset支持设置特定浮点数 4 5**访问级别** 6 7公开接口 8 9**变更原因** 10 11某些国家和地区时区偏移量为浮点数，因此需要支持设置浮点数。 12 13**变更影响** 14 15该变更为兼容性变更，变更后timeZoneOffset支持设置特定浮点数。 16 17**API Level** 18 198 20 21**变更发生版本** 22 23从OpenHarmony SDK 4.1.6.5 版本开始。 24 25**变更的接口/组件** 26 27API 11之前，TextClock组件构造参数timeZoneOffset设置浮点数会取对应的整数值。 28 29API 11及之后，TextClock组件构造参数timeZoneOffset设置{ 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 }里的值会取对应的浮点数。 30 31**适配指导** 32 33请查阅[TextClock组件](../../../application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-textclock.md)文档进行适配。 34 35## cl.arkui.2 Gauge组件的默认阴影模糊半径变更 36 37**访问级别** 38 39公开接口 40 41**变更原因** 42 43当前Gauge组件的默认阴影模糊半径为5vp、UX检视时发现模糊半径过小，因此依照UX规范增加阴影模糊半径到20vp。 44 45**变更影响** 46 47该变更为兼容性变更，改变了组件默认情况下的阴影模糊半径，提升了组件的默认显示效果。 48 49**API Level** 50 5111 52 53**变更发生版本** 54 55从OpenHarmony SDK 4.1.6.5开始。 56 57**变更的接口/组件** 58 59OpenHarmony SDK 4.1.6.5前，Gauge组件的默认阴影模糊半径为5vp。 60 61 62 63OpenHarmony SDK 4.1.6.5及以后，Gauge组件的默认阴影模糊半径为20vp。 64 65 66 67**适配指导** 68 69默认效果变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则应自定义修改效果控制变量以达到预期。 70 71## cl.arkui.3 getItemRect, getItemRectInGroup接口返回值单位变更 72 73**访问级别** 74 75公开接口 76 77**变更原因** 78 79返回值类型为RectResult，位置和宽高以px为单位不合理，故变更返回值单位为vp。 80 81**变更影响** 82 83该变更为非兼容性变更。滚动组件getItemRect接口和List组件getItemRectInGroup接口的返回值单位从px变更为vp。具体受影响的场景如下： 84 85a) 滚动组件通过getItemRect接口获取子组件大小位置 86 87API version 11变更前：大小位置返回值都以px为单位。 88 89API version 11变更后：大小位置返回值都以vp为单位。 90 91b) List组件通过getItemRectInGroup接口获取子组件ListItemGroup内子组件ListItem的大小位置 92 93API version 11变更前：大小位置返回值都以px为单位。 94 95API version 11变更后：大小位置返回值都以vp为单位。 96 97**API Level** 98 9911 100 101**变更发生版本** 102 103从OpenHarmony SDK 4.1.6.5开始。 104 105**变更的接口/组件** 106 107滚动组件（List、Grid、WaterFlow、Scroll）getItemRect接口、List组件getItemRectInGroup接口 108 109**适配指导** 110 111滚动组件（List、Grid、WaterFlow、Scroll）getItemRect接口、List组件getItemRectInGroup接口的返回值单位由原来的px变更为vp。如果需要使用px单位类型，可用vp2px接口做单位转换。 112## cl.arkui.4 自定义组件构造传参赋值中装饰器变量@Link/@ObjectLink校验日志级别变更 113 114**访问级别** 115 116公开接口 117 118**变更原因** 119 120装饰器@Link/@ObjectLink父组件校验由WARN 变成ERROR。 121 122**变更影响** 123 124该变更为非兼容性变更，变更后@Link/@ObjectLink父组件校验报错。 125 126**API Level** 127 12811 129 130**变更发生版本** 131 132从OpenHarmony SDK 4.1.6.5 版本开始。 133 134**示例：** 135 136``` 137let NextID: number = 1; 138 139@Observed 140class ClassA { 141 public id: number; 142 public c: number; 143 144 constructor(c: number) { 145 this.id = NextID++; 146 this.c = c; 147 } 148} 149 150@Entry 151@Component 152struct Parent { 153 @State message: string = 'Hello'; 154 155 build() { 156 Column() { 157 // ERROR: Property 'message' in the custom component 'Child' is missing (mandatory to specify). 158 // ERROR: Property 'message1' in the custom component 'Child' is missing (mandatory to specify). 159 Child(); 160 } 161 } 162} 163 164@Component 165struct Child { 166 @Link message: string; 167 @ObjectLink message1: ClassA; 168 169 build() { 170 Row() { 171 } 172 } 173} 174``` 175 176**变更的接口/组件** 177 178不涉及 179 180**适配指导** 181 182子组件使用了装饰器@Link/@ObjectLink，父组件使用带有装饰器@Link/@ObjectLink的自定义组件时，父组件必须给@Link/@ObjectLink修饰的变量传值。 183## cl.arkui.5 bindmenu使用isShow时点击事件变更 184 185**访问级别** 186 187公开接口 188 189**变更原因** 190 191在bindMenu使用isShow时，只允许isShow控制menu的开启。 192 193**变更影响** 194 195该变更为非兼容性变更，变更后在bindMenu使用isShow的情况下，点击父组件不会弹出menu。 196 197**API Level** 198 19911 200 201**变更发生版本** 202 203从OpenHarmony SDK 4.1.6.5 版本开始。 204**示例：** 205 206``` 207@Entry 208@Component 209struct MenuExample { 210 @State listData: number[] = [0, 0, 0] 211 @State isShow: boolean = false 212 213 @Builder MenuBuilder() { 214 Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 215 ForEach(this.listData, (item:number, index) => { 216 Column() { 217 Row() { 218 Image($r("app.media.icon")).width(20).height(20).margin({ right: 5 }) 219 Text(`Menu${index as number + 1}`).fontSize(20) 220 } 221 .width('100%') 222 .height(30) 223 .justifyContent(FlexAlign.Center) 224 .align(Alignment.Center) 225 .onClick(() => { 226 console.info(`Menu${index as number + 1} Clicked!`) 227 }) 228 229 if (index != this.listData.length - 1) { 230 Divider().height(10).width('80%').color('#ccc') 231 } 232 }.padding(5).height(40) 233 }) 234 }.width(100) 235 } 236 237 build() { 238 Column() { 239 Text('click for menu') 240 .fontSize(20) 241 .margin({ top: 20 }) 242 .onClick(()=>{ 243 this.isShow = true 244 }) 245 .bindMenu(this.isShow, this.MenuBuilder, 246 { 247 onDisappear: ()=>{ 248 this.isShow = false 249 } 250 } 251 ) 252 } 253 .height('100%') 254 .width('100%') 255 .backgroundColor('#f0f0f0') 256 } 257} 258``` 259 260**变更的接口/组件** 261 262bindMenu 263 264**适配指导** 265 266使用isShow后，需要在其他事件中将isShow从false改成true，menu才会弹出，例如点击事件、手势事件以及hover等，如果出现修改isShow的值后，菜单无法弹出，可以在isShow修改前后加上日志打印该值，判断isShow是否有变化, 如果没有变化，需要检查是不是在menu消失的时候没有在onDisappear里更新isShow的值为false，或者初始情况下将isShow设置为了true。 267 268## cl.arkui.6 OffscreenCanvas类声明式继承错误删除 269 270**访问级别** 271 272公开接口 273 274**变更原因** 275 276OffscreenCanvas类声明时父类关系继承错误会导致DevEco Studio错误联想出非OffscreenCanvas本身的方法和属性。 277 278**变更影响** 279 280该变更为兼容性变更，变更后OffscreenCanvas类的方法和属性在DevEco studio中可正确联想，先前因OffscreenCanvas类声明时父类继承错误导致的非OffscreenCanvas本身的方法和属性不再被联想出来。 281 282**API Level** 283 28411 285 286**变更发生版本** 287 288从OpenHarmony SDK 4.1.6.5 版本开始。 289 290**变更的接口/组件** 291 292OffscreenCanvas 293 294**适配指导** 295 296DevEco Studio中OffscreenCanvas代码编辑联想功能，不涉及适配。 297 298## cl.arkui.7 layoutWeight支持float类型变更 299 300**访问级别** 301 302公开接口 303 304**变更原因** 305 306layoutWeight需要更精细的设置。 307 308**变更影响** 309 310该变更为兼容性变更，变更后layoutWeight参数支持float类型。 311 312**API Level** 313 3149 315 316**变更发生版本** 317 318从OpenHarmony SDK 4.1.6.5开始。 319 320**变更的接口/组件** 321 322涉及到layoutWeight接口 323 324API 12前，参数为float类型，小数点后不生效。 325 326API 12及以后，参数为float类型，小数点后生效。 327 328**适配指导** 329 330接口参数类型变更，不涉及适配。 331 332## cl.arkui.8 GridRow组件高度自适应变更 333 334**访问级别** 335 336公开接口 337 338**变更原因** 339 340原规格遗留问题，变更前用户设置了GridRow组件的height属性，而实际上GridRow组件的高度并不会按设置的height进行绘制，而是会自适应子组件高度。 341现将规格确定为：若用户设置了GridRow组件的height属性，则GridRow组件的高度按设置的height进行绘制，若用户没有设置GridRow组件的height属性，则自适应子组件高度。 342 343**变更影响** 344 345该变更为非兼容性变更。改变了GridRow组件的高度设置，可按照用户设置的高度进行绘制。 346 347**API Level** 348 3499 350 351**变更发生版本** 352 353从OpenHarmony SDK 4.1.6.5开始。 354 355**变更的接口/组件** 356 357涉及到GridRow组件 358 359API 11前，GridRow组件无论是否设置height属性，其高度都会自适应子组件高度。 360 361API 11及以后，GridRow组件设置了height属性后不再自适应子组件高度，而是按用户设置高度进行绘制；如果没有设置height属性，则仍会自适应子组件高度。 362 363**适配指导** 364 365组件高度自适应变更，不涉及适配。 366 367## cl.arkui.9 surface类型XComponent组件backgroundColor属性行为变更 368 369**访问级别** 370 371公开接口 372 373**变更原因** 374 375surface类型的XComponent组件需支持设置背景色。 376 377**变更影响** 378 379该变更为非兼容性变更，场景为给surface类型的XComponent组件设置backgroundColor属性，具体行为如下： 380 381API version 11变更前：无论设置何种属性，背景色均为默认黑色背景色。 382 383API version 11变更后：组件背景色会生效所设置的颜色。 384 385**API Level** 386 3879 388 389**变更发生版本** 390 391从OpenHarmony SDK 4.1.6.5 版本开始。 392 393**示例：** 394 395``` 396@Entry 397@Component 398struct XComponentBKColor { 399 private surfaceId: string = '' 400 private xComponentContext: Record<string, () => void> = {} 401 xComponentController: XComponentController = new XComponentController() 402 403 build() { 404 Row() { 405 XComponent({ 406 id: 'xcomponentid', 407 type: XComponentType.SURFACE, 408 controller: this.xComponentController 409 }) 410 .onLoad(() => { 411 this.xComponentController.setXComponentSurfaceSize({ surfaceWidth: 1920, surfaceHeight: 1080 }) 412 this.surfaceId = this.xComponentController.getXComponentSurfaceId() 413 this.xComponentContext = this.xComponentController.getXComponentContext() as Record<string, () => void> 414 }) 415 .width('640px') 416 .height('480px') 417 .backgroundColor(Color.White) 418 } 419 } 420} 421``` 422 423**变更的接口/组件** 424 425XComponent 426 427**适配指导** 428 429给surface类型的XComponent组件设置backgroundColor属性后，确认是应用的场景所需要的背景色。 430 431## cl.arkui.10 TextInput/TextArea组件光标超出圆角部分截断显示效果变更 432 433**访问级别** 434 435公开接口 436 437**变更原因** 438 439该变更为非兼容性变更，当设置TextInput组件padding为0时，光标会显示在输入框默认圆角外，不符合应用诉求。 440 441**变更影响** 442 443API version 11变更前：输入框使用默认圆角， 设置padding为0，光标超出输入框组件圆角的部分未被截断。 444 445 446 447API version 11变更后：输入框使用默认圆角， 设置padding为0，光标超出输入框组件圆角的部分会被截断。 448 449 450 451**API Level** 452 4539 454 455**变更发生版本** 456 457从OpenHarmony SDK 4.1.6.5开始。 458 459**变更的接口/组件** 460 461TextInput/TextArea 462 463**适配指导** 464 465默认行为变更，不涉及适配。 466 467## cl.arkui.11 全局接口作用的UI实例跟踪匹配规则变更 468 469**访问级别** 470 471公开接口 472 473**变更原因** 474 475规范全局接口UI实例匹配行为，避免因实例不明确造成的非预期行为。 476 477**变更影响** 478 479多实例场景下，在未绑定UI实例的上下文中调用全局接口（如在异步回调中使用路由接口），接口的作用实例可能发生变化。 480 481全局接口需要明确的UI实例上下文以确定作用的UI实例，建议通过绑定实例的接口进行调用。 482 483**API Level** 484 4858 486 487**变更发生版本** 488 489从OpenHarmony SDK 4.1.6.5开始。 490 491**变更的接口/组件** 492 493不推荐开发者在多实例场景下使用如下接口，建议开发者使用适配指导中的替代接口。 494 495| API | 说明 | 496| :-----------------------------------: | :------------------------: | 497| @ohos.animator | 自定义动画控制器 | 498| @ohos.arkui.componentSnapshot | 组件截图 | 499| @ohos.arkui.componentUtils | 组件工具类 | 500| @ohos.arkui.dragController | 拖拽控制器 | 501| @ohos.arkui.inspector | 组件布局回调 | 502| @ohos.arkui.observer | 无感监听 | 503| @ohos.font | 自定义字体 | 504| @ohos.measure | 文本计算 | 505| @ohos.mediaquery | 媒体查询 | 506| @ohos.promptAction | 弹窗 | 507| @ohos.router | 页面路由 | 508| AlertDialog | 警告弹窗 | 509| ActionSheet | 列表选择弹窗 | 510| CalendarPickerDialog | 日历选择器弹窗 | 511| DatePickerDialog | 日期滑动选择弹窗 | 512| TimePickerDialog | 时间滑动选择器弹窗 | 513| TextPickerDialog | 文本滑动选择器弹窗 | 514| ContextMenu | 菜单控制 | 515| vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx | 像素单位转换 | 516| focusControl | 焦点控制 | 517| cursorControl | 光标控制 | 518| getContext | 获取当前的Ability的Context | 519| LocalStorage.getShared | 获取Ability传递的Storage | 520| animateTo | 显式动画 | 521| animateToImmediately | 显式立即动画 | 522 523**适配指导** 524 525使用组件内置方法[`getUIContext`](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/arkui-ts/ts-custom-component-api.md#getuicontext)，可直接获取当前组件所在的UIContext，并使用如下[UIContext](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext)中的API获取与实例绑定的对象。 526 527| UIContext接口 | 说明 | 528| -------------------------------- | ------------------ | 529| getRouter | 页面路由 | 530| getComponentUtils | 组件工具类 | 531| getUIInspector | 组件布局回调 | 532| getUIObserver | 无感监听 | 533| getMediaQuery | 媒体查询 | 534| getFont | 字体 | 535| getPrompAction | 弹窗 | 536| animateTo | 显示动画 | 537| showAlerDialog | 警告弹窗 | 538| showActionSheet | 列表选择弹窗 | 539| showDatePickerDialog | 日期滑动选择弹窗 | 540| showTimePickerDialog | 时间滑动选择器弹窗 | 541| showTextPcikerDialog | 文本滑动选择器弹窗 | 542| createAnimator | 自定义动画控制器 | 543| KeyboardAvoidMode | 键盘避让 | 544| getAtomicServiceBar | 云服务 | 545| getDragController/getDragPreview | 拖拽 | 546| runScopedTask | 执行绑定实例的闭包 | 547 548对于以下UIContext中尚不具备的API，可使用runScopedTask进行适配： 549 550| 接口 | 说明 | 551| ------------------------------------- | -------------------------- | 552| measure | 文本计算 | 553| getContext | 获取当前的Ability的Context | 554| LocalStorage.getShared | 获取Ability传递的Storage | 555| animateToImmediately | 显式立即动画 | 556| ContextMenu | 菜单控制 | 557| vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx | 像素单位转换 | 558| focusControl | 焦点控制 | 559| cursorControl | 光标控制 | 560| @ohos.arkui.componentSnapshot | 组件截图 | 561 562示例1 563 564```ets 565// 使用绑定实例的路由对象进行页面路由 566@Entry 567@Component 568struct Index { 569 build() { 570 Row() { 571 Button() 572 .onClick(() => { 573 let uiContext = this.getUIContext(); 574 let uiRouter = uiContext.getRouter(); 575 uiRouter.pushUrl({ 576 url: 'pages/Page' 577 }) 578 }) 579 } 580 } 581} 582``` 583 584示例2 585 586```ets 587// 执行绑定实例的闭包 588@Entry 589@Component 590struct Index { 591 build() { 592 Row() { 593 Button() 594 .onClick(() => { 595 let uiContext = this.getUIContext(); 596 uiContext.runScopedTask(() => { 597 let context = getContext(); 598 console.log('Get context: ' + JSON.stringify(context)) 599 }) 600 }) 601 } 602 } 603} 604``` 605 606
