1# ArkUI Subsystem Changelog 2 3## cl.arkui.1 Floating Point Number Support Added for timeZoneOffset of the \<TextClock> Component 4 5**Access Level** 6 7Public 8 9**Reason for Change** 10 11The time zone offset for some countries and regions is a floating point number. Therefore, floating point numbers need to be supported. 12 13**Change Impact** 14 15This change is a compatible change. 16 17**API Level** 18 198 20 21**Change Since** 22 23OpenHarmony SDK 4.1.6.5 24 25**Key API/Component Changes** 26 27In versions earlier than API version 11, any floating point number set for the **timeZoneOffset** parameter of the **\<TextClock>** component is converted to the corresponding integer. 28 29Since API version 11, a floating point number in the { 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 } range can be set for the **timeZoneOffset** parameter of the **\<TextClock>** component. 30 31**Adaptation Guide** 32 33For details, see [TextClock](../../../application-dev/reference/apis-arkui/arkui-ts/ts-basic-components-textclock.md). 34 35## cl.arkui.2 Change in the Default Shadow Blur Radius of the \<Gauge> Component 36 37**Access Level** 38 39Public 40 41**Reason for Change** 42 43The original default shadow blur radius, 5 vp, is too small for the **\<Gauge>** component according to the UX specifications. Therefore, the default shadow blur radius is enlarged to 20 vp. 44 45**Change Impact** 46 47This change is a compatible change. It enhances the default display effect of the component. 48 49**API Level** 50 5111 52 53**Change Since** 54 55OpenHarmony SDK 4.1.6.5 56 57**Key API/Component Changes** 58 59Before OpenHarmony SDK 4.1.6.5, the default shadow blur radius of the **\<Gauge>** component is 5 vp. 60 61 62 63Since OpenHarmony SDK 4.1.6.5, the default shadow blur radius of the **\<Gauge>** component is 20 vp. 64 65 66 67**Adaptation Guide** 68 69No adaptation is required. Yet, since the default display effect is changed, you need to check whether it meets your expectation. Change the display variables where necessary. 70 71## cl.arkui.3 Return Value Unit Change for getItemRect and getItemRectInGroup 72 73**Access Level** 74 75Public 76 77**Reason for Change** 78 79The unit of the return value type **RectResult** should be vp, not previously px. 80 81**Change Impact** 82 83This change is a non-compatible change. The unit of the value returned by o the **getItemRect** API of a scrollable component and the **getItemRectInGroup** API of the **\<List>** component is changed from px to vp. The affected scenarios are as follows: 84 85(a) The **getItemRect** API is called in a scrollable component to obtain the size and position of a child component. 86 87Before change: The size and position returned are both in px. 88 89After change: The size and position returned are both in vp. 90 91(b) The **getItemRectInGroup** API is called in a **\<List>** component to obtain the size and position of a list item in a list item group. 92 93Before change: The size and position returned are both in px. 94 95After change: The size and position returned are both in vp. 96 97**API Level** 98 9911 100 101**Change Since** 102 103OpenHarmony SDK 4.1.6.5 104 105**Key API/Component Changes** 106 107**getItemRect** (**\<List>**, **\<Grid>**, **\<WaterFlow>**, **\<Scroll>**) and **getItemRectInGroup** (**\<List>**) 108 109**Adaptation Guide** 110 111 If the px unit is required, you can use the **vp2px** API to convert the unit. 112## cl.arkui.4 Log Level Change for Value Assignment of @Link/@ObjectLink Decorated Variables 113 114**Access Level** 115 116Public 117 118**Reason for Change** 119 120The log level for value assignment of an @Link/@ObjectLink decorated variable in the parent component is changed from WARN to ERROR. 121 122**Change Impact** 123 124This change is a non-compatible change. After the change, an error is reported if an @Link/@ObjectLink decorated variable is not assigned a value in the parent component. 125 126**API Level** 127 12811 129 130**Change Since** 131 132OpenHarmony SDK 4.1.6.5 133 134**Example** 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**Key API/Component Changes** 177 178N/A 179 180**Adaptation Guide** 181 182If a child component uses an @Link/@ObjectLink decorated variable, then the variable must be assigned a value in its parent component. 183## cl.arkui.5 Click Event Change for isShow in bindmenu 184 185**Access Level** 186 187Public 188 189**Reason for Change** 190 191When **isShow** is used in **bindMenu**, the menu can be displayed only through **isShow**. 192 193**Change Impact** 194 195This change is a non-compatible change. After the change, when **isShow** is used in **bindMenu**, clicking the parent component does not show the menu. 196 197**API Level** 198 19911 200 201**Change Since** 202 203OpenHarmony SDK 4.1.6.5 204**Example** 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**Key API/Component Changes** 261 262bindMenu 263 264**Adaptation Guide** 265 266When **isShow** is used in **bindMenu**, the menu is displayed only after **isShow** is changed from **false** to **true** in related click, gesture, and hover events. If the menu cannot be displayed after the value of **isShow** is changed, use logs to print the value of **isShow** before and after your change. If the value remains unchanged, check whether the value of **isShow** is not updated to **false** in **onDisappear** when the menu disappears, or whether **isShow** is set to **true** initially. 267 268## cl.arkui.6 Removal of Incorrect Inheritance from OffscreenCanvas Class Declaration 269 270**Access Level** 271 272Public 273 274**Reason for Change** 275 276In the previous **OffscreenCanvas** class declaration, the parent class incorrect. As a result, DevEco Studio incorrectly associates methods and attributes that are not of the **OffscreenCanvas** class. 277 278**Change Impact** 279 280This change is a compatible change. After the change, the methods and attributes of the **OffscreenCanvas** class can be correctly displayed for intelligent code completion in DevEco Studio. 281 282**API Level** 283 28411 285 286**Change Since** 287 288OpenHarmony SDK 4.1.6.5 289 290**Key API/Component Changes** 291 292OffscreenCanvas 293 294**Adaptation Guide** 295 296N/A 297 298## cl.arkui.7 Float Type Support Added for layoutWeight 299 300**Access Level** 301 302Public 303 304**Reason for Change** 305 306The **layoutWeight** parameter needs to be set more precisely. 307 308**Change Impact** 309 310This change is a compatible change. 311 312**API Level** 313 3149 315 316**Change Since** 317 318OpenHarmony SDK 4.1.6.5 319 320**Key API/Component Changes** 321 322**layoutWeight** 323 324Before API version 12, when the parameter is set to a float number, the digits after the decimal point are not counted. 325 326Since API version 12, when the parameter is set to a float number, the digits after the decimal point are counted. 327 328**Adaptation Guide** 329 330N/A 331 332## cl.arkui.8 Height Configuration Change for the \<GridRow> Component 333 334**Access Level** 335 336Public 337 338**Reason for Change** 339 340In previous versions, the **\<GridRow>** component always adapts its height to child components, regardless of whether the **height** is set. 341The change is to correct this known issue. 342 343**Change Impact** 344 345This change is a non-compatible change. The height of the **\<GridRow>** component can be customized. 346 347**API Level** 348 3499 350 351**Change Since** 352 353OpenHarmony SDK 4.1.6.5 354 355**Key API/Component Changes** 356 357**\<GridRow>** component 358 359Before API version 11, the **\<GridRow>** component always adapts its height to child components, regardless of whether the **height** is set. 360 361Since API version 11, the **\<GridRow>** component is drawn based on the specified height. If no height is specified, the component adapts its height to child components. 362 363**Adaptation Guide** 364 365N/A 366 367## cl.arkui.9 Behavior Change for backgroundColor in \<XComponent> of the surface Type 368 369**Access Level** 370 371Public 372 373**Reason for Change** 374 375Background color configuration is required for the **\<XComponent>** of the surface type. 376 377**Change Impact** 378 379This change is a non-compatible change. 380 381Before change: The background color is black by default regardless of the **backgroundColor** attribute settings. 382 383After change: The background color specified through the **backgroundColor** attribute takes effect. 384 385**API Level** 386 3879 388 389**Change Since** 390 391OpenHarmony SDK 4.1.6.5 392 393**Example** 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**Key API/Component Changes** 424 425XComponent 426 427**Adaptation Guide** 428 429After setting the **backgroundColor** attribute for the **\<XComponent>** component of the surface type, ensure that the background color is what is required by the use scenario. 430 431## cl.arkui.10 Display Effect Change for the \<TextInput> or \<TextArea> Component When the Caret Exceeds the Rounded Corner 432 433**Access Level** 434 435Public 436 437**Reason for Change** 438 439TThis change is a non-compatible change. Previously, when **padding** is set to **0**, the caret is displayed outside the default rounded corner of the text box, which does not meet application requirements. 440 441**Change Impact** 442 443Before change: When the text box uses the default rounded corners with a padding of **0**, the caret is not clipped if it exceeds the rounded corners. 444 445 446 447After change: When the text box uses the default rounded corners with a padding of **0**, the caret is clipped if it exceeds the rounded corners. 448 449 450 451**API Level** 452 4539 454 455**Change Since** 456 457OpenHarmony SDK 4.1.6.5 458 459**Key API/Component Changes** 460 461TextInput/TextArea 462 463**Adaptation Guide** 464 465N/A 466 467## cl.arkui.11 Matching Rule Change for UI Instances of Global APIs 468 469**Access Level** 470 471Public 472 473**Reason for Change** 474 475The change is to standardize the UI instance matching of global APIs to avoid unexpected behavior caused by unclear instances. 476 477**Change Impact** 478 479In the multi-instance scenario, if a global API is called in the context that is not bound to any UI instance (for example, the routing API is used in an asynchronous callback), the instance scope of the API may change. 480 481A global API requires a specific UI context to determine the UI instance that takes effect. You are advised to use the global APIs bound to an instance. 482 483**API Level** 484 4858 486 487**Change Since** 488 489OpenHarmony SDK 4.1.6.5 490 491**Key API/Component Changes** 492 493The following APIs are not recommended in multi-instance scenarios. You are advised to use the substitutes described in the adaptation guide. 494 495| API | Description | 496| :-----------------------------------: | :------------------------: | 497| @ohos.animator | Custom animation controller. | 498| @ohos.arkui.componentSnapshot | Component screenshot. | 499| @ohos.arkui.componentUtils | Component utility class. | 500| @ohos.arkui.dragController | Drag controller. | 501| @ohos.arkui.inspector | Layout callback. | 502| @ohos.arkui.observer | Observer. | 503| @ohos.font | Custom font registration. | 504| @ohos.measure | Text measurement. | 505| @ohos.mediaquery | Media query. | 506| @ohos.promptAction | Prompt. | 507| @ohos.router | Page routing. | 508| AlertDialog | Alert dialog box. | 509| ActionSheet | Action sheet. | 510| CalendarPickerDialog | Calendar picker dialog box. | 511| DatePickerDialog | Date picker dialog box. | 512| TimePickerDialog | Time picker dialog box. | 513| TextPickerDialog | Text picker dialog box. | 514| ContextMenu | Menu control. | 515| vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx | Pixel unit conversion. | 516| focusControl | Focus control. | 517| cursorControl | Cursor control. | 518| getContext | Obtains the context of the current ability.| 519| LocalStorage.getShared | Obtains the storage passed by the current ability. | 520| animateTo | Explicit animation. | 521| animateToImmediately | Explicit instant animation. | 522 523**Adaptation Guide** 524 525You can use the built-in method [getUIContext](../../../application-dev/reference/apis-arkui/arkui-ts/ts-custom-component-api.md#getuicontext) of a component to obtain the UI context where the component is located and use the APIs listed below in [UIContext](../../../application-dev/reference/apis-arkui/js-apis-arkui-UIContext.md#uicontext) to obtain the object bound to the instance. 526 527| API in UIContext | Description | 528| -------------------------------- | ------------------ | 529| getRouter | Page routing. | 530| getComponentUtils | Component utility class. | 531| getUIInspector | Layout callback. | 532| getUIObserver | Observer. | 533| getMediaQuery | Media query. | 534| getFont | Font. | 535| getPrompAction | Prompt. | 536| animateTo | Explicit animation. | 537| showAlerDialog | Alert dialog box. | 538| showActionSheet | Action sheet. | 539| showDatePickerDialog | Date picker dialog box. | 540| showTimePickerDialog | Time picker dialog box.| 541| showTextPcikerDialog | Text picker dialog box.| 542| createAnimator | Custom animation controller. | 543| KeyboardAvoidMode | Keyboard avoidance. | 544| getAtomicServiceBar | Cloud service. | 545| getDragController/getDragPreview | Drag and drop. | 546| runScopedTask | Executes the closure of the bound instance.| 547 548For the following APIs that are not provided in **UIContext**, you can use **runScopedTask** for adaptation. 549 550| API | Description | 551| ------------------------------------- | -------------------------- | 552| measure | Text measurement. | 553| getContext | Obtains the context of the current ability.| 554| LocalStorage.getShared | Obtains the storage passed by the current ability. | 555| animateToImmediately | Explicit instant animation. | 556| ContextMenu | Menu control. | 557| vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx | Pixel unit conversion. | 558| focusControl | Focus control. | 559| cursorControl | Cursor control. | 560| @ohos.arkui.componentSnapshot | Component screenshot. | 561 562Example 1 563 564```ets 565// Use the route object bound to the instance for page routing. 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 584Example 2 585 586```ets 587// Execute the closure of the bound instance. 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
