1# ArkUI Subsystem Changelog 2 3## cl.arkui.1 New Directional Menu Style for bindMenu 4 5**Access Level** 6 7Public API 8 9**Reason for Change** 10 11This change is made for enhancement of UX specifications. 12 13**Change Impact** 14 15This change is a non-compatible change. 16 17Before change: Setting the **enableArrow** attribute to **true** in **MenuOptions** of **bindMenu** does not display a directional menu style. 18 19After change: Setting the **enableArrow** attribute to **true** in **MenuOptions** of **bindMenu** and having a menu size and position sufficient to accommodate an arrow will display a directional menu style. 20 21**API Level** 22 23The **enableArrow** and **arrowOffset** attributes are supported since API version 10. 24 25**Change Since** 26 27OpenHarmony SDK 5.0.0.23 28 29**Adaptation Guide** 30 31To avoid displaying a directional menu style in **bindMenu**, either do not set the **enableArrow** attribute or set it to **false** in **MenuOptions**. 32To display a directional menu style, set the **enableArrow** attribute to **true** and optionally set the **arrowOffset** attribute. 33 34## cl.arkui.2 Default Focus Navigation Behavior Change 35 36**Access Level** 37 38Public API 39 40**Reason for Change** 41 42This change is made to optimize the default focus behavior. 43 44**Change Impact** 45 46This change is a non-compatible change. 47 48Before change: Components with focus capability but not focusable by default require **.focusable(true)** to become focusable, and do not have the default focus frame; focused state styles needed to be configured. 49 50After change: Components registered with **onClick** or single-tap gestures are focusable by default, displaying a default focus box without the need for focused state style configuration. 51 52**Start API Level** 53 5412 55 56**Change Since** 57 58OpenHarmony SDK 5.0.0.23 59 60**Adaptation Guide** 61 62If you do not want a clickable component to participate in focus navigation, set **.focusable(false)**. 63 64## cl.arkui.3 Default Style Changes of the Dialog Component 65 66**Access Level** 67 68Public API 69 70**Reason for Change** 71 72This change is made to optimize the visual style of the dialog box, including corner radius, background color, material, and shadow, and to optimize the dialog box's responsive layout for a better user experience across devices. 73 74**Change Impact** 75 76This change is a non-compatible change. It affects only the default styles of dialog boxes. Custom styles will override the defaults, and illegal custom values will result in default behavior. 77 78- Before change: 79 1. The default corner radius is 24 vp on all corners of the dialog box. 80 2. The default background color of the dialog box in light color mode is 0xd9fffff. 81 3. By default, most dialog boxes have a transparent background and ultra-thick blur, except for **customDialog** and **PromptAction**. 82 4. The default width of the dialog box is controlled by the grid system, with a maximum width of 400 vp. For 2-in-1 devices, the width of the dialog box is fixed at 400 vp and cannot be changed. 83 5. The default maximum height of the dialog box is (Screen Height - Safe Area) x 0.8. For 2-in-1 devices, the maximum height is (Full screen x 0.67 x 0.9). 84 6. Responsive and adaptive dialog boxes are centered after avoiding the navigation bar. The alignment mode is **DialogAlignment.Bottom** on default devices and **DialogAlignment.Center** on other devices. 85 7. There is no default shadow style for any device. 86 87 <br/> 88- After change: 89 1. The default corner radius is 32 vp on all corners of the dialog box. 90 2. The default background color of the dialog box in light color mode is 0xfffff. 91 3. By default, all dialog boxes have a transparent background and ultra-thick blur. 92 4. The default width of the dialog box is the window width minus left and right margins, which are 40 on 2-in-1 devices and 16 on other devices. The default maximum width is 400 vp, which varies with the window size. When a custom value is specified for the width of the dialog box, this custom value will be used. The reference width for the dialog box is the width of its containing window. You can adjust the width based on this reference. If an invalid value is set, the dialog box will fall back to its default appearance. 93 5. The default minimum height of the dialog box is 70 vp, and the default maximum height is (Window height - Safe area) x 0.9. When a custom value is specified for the height of the dialog box, this custom value will be used. The reference height for the dialog box is calculated as the window height minus the safe area. You can adjust the height based on this reference. If an invalid value is set, the dialog box will fall back to its default appearance. 94 6. Responsive and adaptive dialog boxes are centered based on the full screen on all devices. 95 7. For 2-in-1 devices, the shadow style is **ShadowStyle.OUTER_FLOATING_MD** for components in the focused state and **ShadowStyle.OUTER_FLOATING_SM** for components in the unfocused state. There is no default shadow style for other devices. 96 97 The following figures show the comparison before and after the change. 98 99| Before Change| After Change| 100|---------|---------| 101|  |  | 102|  |  | 103|  |  | 104|  |  | 105 106**API Level** 107 10812 109 110**Change Since** 111 112OpenHarmony SDK 5.0.0.23 113 114**Key API/Component Changes** 115 116**Dialog** component 117 118**Adaptation Guide** 119 120No 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. 121 122## cl.arkui.4 Default Transparency Effect and Opacity Customization for Drag Previews 123 124**Access Level** 125 126Public API 127 128**Reason for Change** 129 130This change is made in accordance with UX specifications. 131 132**Change Impact** 133 134This change is a non-compatible change. 135 136API version 11 and earlier: The drag preview does not have transparency. 137 138API version 12 and later: The drag preview has a 95% transparency, and the transparency value can be customized. 139 140**API Level** 141 14212 143 144**Change Since** 145 146OpenHarmony SDK 5.0.0.23 147 148**Adaptation Guide** 149 150No adaptation is required as this is a default style change. 151 152## cl.arkui.5 @Observed/@Track/@ObservedV2 Validation Change 153**Access Level** 154 155Public API 156 157**Reason for Change** 158 159Compile-time validation is added to prevent incorrect use of the deep observation decorators, which could lead to functional errors at runtime. 160 161**Change Impact** 162 163Before change: No error is reported during validation. 164 165After change: 166In the following scenarios, which do not comply with the specifications, the compiler will report errors. 167 168- Using @Track within a class decorated by @ObservedV2 169 170> **NOTE** 171> 172> Since @ObservedV2 uses a different implementation logic from @Observed, @Track cannot be used within a class decorated by @ObservedV2. @Track can be used with @Observed, and @Trace can be used with @ObservedV2. 173 174- Decorating a class with both @Observed and @ObservedV2 175 176> **NOTE** 177> 178> Mixing the use of @Observed and @ObservedV2 may cause undefined behavior, including redundant re-renders and loss of the in-depth observation, property observation, or property-level update capability. 179 180- Inconsistent use of @Observed and @ObservedV2 when decorating child classes and parent classes 181 182The following is an example of incorrect code: 183 184```ts 185// @Track cannot be used within a class decorated by @ObservedV2. 186@ObservedV2 187class TestObserved { 188 @Track value: string = "hello" 189} 190// A class cannot be decorated by both @Observed and @ObservedV2. 191@Observed 192@ObservedV2 193class TestObserved1 { 194 value: string = "hello" 195} 196// The use of @Observed and @ObservedV2 must be consistent when decorating chid classes and parent classes. 197@Observed 198class TestObserved3 { 199 @Track value: string = "hello" 200} 201@ObservedV2 202class TestObserved4 extends TestObserved3 { 203 @Trace value: string = "hello" 204} 205 206@ObservedV2 207class TestObserved5 { 208 @Trace value: string = "hello" 209} 210@Observed 211class TestObserved6 extends TestObserved5 { 212 @Track value: string = "hello" 213} 214``` 215 216**Start API Level** 217 21812 219 220**Change Since** 221 222OpenHarmony SDK 5.0.0.23 223 224**Adaptation Guide** 225 226Adapt and rectify code according to the error messages. 227 228## cl.arkui.6 TextInput, TextArea, Search, and RichEditor Text Menu Style Changes 229 230**Access Level** 231 232Public API 233 234**Reason for Change** 235 236This change is made in accordance with specifications. 237 238**Change Impact** 239 240This change is a compatible change. 241API version 11 and earlier: The text selection menu includes share, search, and translate buttons, all of which are gray, and has an expanded menu. 242 243API version 12 and later: The text selection menu does not include share, search, and translate buttons, and the expanded menu does not appear. 244 245**Start API Level** 246 247The text menu is a system capability with no external APIs. 248 249**Change Since** 250 251OpenHarmony SDK 5.0.0.23 252 253**Key API/Component Changes** 254 255**TextInput**, **TextArea**, **Search**, and **RichEditor** components 256 257**Adaptation Guide** 258 259No adaptation is required. However, you need to check whether the changed behavior affects the overall application logic. 260 261## cl.arkui.7 Disallowing of Using ImageSpan and ContainerSpan Alone 262 263**Access Level** 264 265Public API 266 267**Reason for Change** 268 269This change is made in accordance with specifications. 270 271**Change Impact** 272 273This change is a non-compatible change. 274Before change: Using the **ImageSpan** and **ContainerSpan** components in a component other than **Text** does not result in compilation errors. 275After change: Using the **ImageSpan** and **ContainerSpan** components in a component other than **Text** results in compilation errors. 276 277**Start API Level** 278 27912 280 281**Change Since** 282 283OpenHarmony SDK 5.0.0.23 284 285**Key API/Component Changes** 286 287**ImageSpan** and **ContainerSpan** components 288 289**Adaptation Guide** 290 291Modify your code according to the error messages. 292 293## cl.arkui.8 Change in the Popup Avoidance Position When Width Is Set to 100% 294 295**Access Level** 296 297Public API 298 299**Reason for Change** 300 301This change is made to match UX style changes. 302 303**Change Impact** 304 305This change is a non-compatible change. 306 307Before change: When the popup width is greater than or equal to 100% minus 6 vp, the popup is avoided by default, and there is a 6 vp margin from the left edge of the window. 308 309After change: When the popup width is greater than or equal to 100% minus 6 vp, the popup is not avoided by default, and there is no 6 vp margin from the left edge of the window. 310 311| Before Change| After Change| 312|---------|---------| 313|  |  | 314 315**Start API Level** 316 3177 318 319**Change Since** 320 321OpenHarmony SDK 5.0.0.23 322 323**Key API/Component Changes** 324 325**Popup** component 326 327**Adaptation Guide** 328 329No adaptation is required. Yet, since the default display effect is changed, you need to check whether it meets your expectation. Adjust the popup position using the **offset** attribute where necessary. For details, see [Popup Control](../../../application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-popup.md). 330 331## cl.arkui.9 Unified Corner Radius and Customization Support for Drag Previews 332 333**Access Level** 334 335Public API 336 337**Reason for Change** 338 339This change is made in accordance with UX specifications. 340 341**Change Impact** 342 343This change is a non-compatible change. 344 345API version 11 and earlier: Non-text components display a drag preview with custom corner radius effects. 346 347API version 12 and later: When non-text components are long-pressed, **DragPreviewOptions.mode** is checked to determine whether to activate the unified corner radius effect for drag previews, with a default value of 12 vp. If the custom corner radius value set by the application is greater than the default value, the custom value will be used. 348 349**API Level** 350 35112 352 353**Change Since** 354 355OpenHarmony SDK 5.0.0.23 356 357**Adaptation Guide** 358 359No adaptation is required as this is a default style change. 360 361## cl.arkui.10 Background Blur Effect Support for Drag Previews 362 363**Access Level** 364 365Public API 366 367**Reason for Change** 368 369This change is made in accordance with UX specifications. 370 371**Change Impact** 372 373This change is a non-compatible change. 374 375API version 11 and earlier: Non-text components display a drag preview without a background blur effect when long-pressed. 376 377API version 12 and later: Non-text components display a drag preview with a background blur effect when long-pressed. 378 379**API Level** 380 38112 382 383**Change Since** 384 385OpenHarmony SDK 5.0.0.23 386 387**Adaptation Guide** 388 389No adaptation is required as this is a default style change. 390 391## cl.arkui.11 DatePickerDialog Title Button Size and Layout Change 392 393**Access Level** 394 395Public API 396 397**Reason for Change** 398 399This change is made for enhancement of UX specifications. 400 401**Change Impact** 402 403This change is a non-compatible change. 404 405Before change: The size of the **DatePickerDialog** title button is the same as the text size, and the bottom operation area is 24 vp away from the dialog box edge. 406 407After change: The height of the **DatePickerDialog** title button is 32 vp, with a distance of 16 vp from the left and right boundaries of the dialog box, and the bottom operation area is flush with the dialog box edge. 408 409The following figures show the comparison before and after the change. 410 411| Before Change| After Change| 412|---------|---------| 413|  |  | 414 415**Start API Level** 416 41712 418 419**Change Since** 420 421OpenHarmony SDK 5.0.0.23 422 423**Adaptation Guide** 424 425No adaptation is required. However, you need to check whether the changed behavior affects the overall application logic. 426 427## cl.arkui.12 Change in the Spacing Between the Title and Close Button of bindSheet 428 429**Access Level** 430 431Public API 432 433**Reason for Change** 434 435This change is made to meet application demands and new UX specifications. 436 437**Change Impact** 438 439This change is a non-compatible change. 440 441API version 11 and earlier: The spacing between the title and close button is 32 vp. 442 443API version 12 and later: The spacing between the title and close button is 8 vp. 444 445The figure below shows the change. 446 447 448 449**Start API Level** 450 45111 452 453**Change Since** 454 455OpenHarmony SDK 5.0.0.23 456 457**Key API/Component Changes** 458 459bindSheet 460 461**Adaptation Guide** 462 463No 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. 464 465## c1.arkui.13 Change to Exception Handling for bindSheet's backgroundColor Attribute 466 467**Access Level** 468 469Public API 470 471**Reason for Change** 472 473To align with user experience guidelines, the sheet reverts to the default background color when an invalid value is assigned to the **backgroundColor** attribute. 474 475**Change Impact** 476 477This change is a non-compatible change. 478 479Before change: Assigning an invalid value to the **backgroundColor** attribute of a sheet has no effect. 480 481After change: Assigning an invalid value to the **backgroundColor** attribute of a sheet restores the sheet to the default background color. 482 483**Start API Level** 484 48511 486 487**Change Since** 488 489OpenHarmony SDK 5.0.0.23 490 491**Key API/Component Changes** 492 493bindSheet 494 495**Adaptation Guide** 496 497No 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. 498 499## cl.arkui.14 Change to the Menu Component Margin 500 501**Access Level** 502 503Public API 504 505**Reason for Change** 506 507This change is made in accordance with UX specifications. 508 509**Change Impact** 510 511Before change: The menu has margins set to 12 vp on the horizontal sides and 24 vp on the vertical sides. 512 513After change: The left and right margins are adjusted to 16 vp, and the top and bottom margins are automatically adjusted to avoid the status bar and navigation bar without additional spacing. For menus configured to appear outside the application window, the left and right margins are set to 8vp, with top and bottom margins are adjusted to avoid the status bar and dock area. 514 515**Start API Level** 516 5179 518 519**Change Since** 520 521OpenHarmony SDK 5.0.0.23 522 523**Key API/Component Changes** 524 525Menu 526 527**Adaptation Guide** 528 529No 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. 530 531## cl.arkui.15 Default Font Size Change for TabContent's Bottom Tabs in Horizontal Layout 532 533**Access Level** 534 535Public API 536 537**Reason for Change** 538 539This change is made to improve readability. 540 541**Change Impact** 542 543This change is a non-compatible change. 544 545Before change: The default font size for bottom tabs in a horizontal layout within the **TabContent** component is 10 vp. 546 547 548 549After change: The default font size for bottom tabs in a horizontal layout within the **TabContent** component is 12 vp. 550 551 552 553**Start API Level** 554 55510 556 557**Change Since** 558 559OpenHarmony SDK 5.0.0.23 560 561**Key API/Component Changes** 562 563TabContent 564 565**Adaptation Guide** 566 567No adaptation is required. Yet, since the default display effect is changed, you need to check whether it meets your expectation. Change the related attributes where necessary. For details, see [TabContent](../../../application-dev/reference/apis-arkui/arkui-ts/ts-container-tabcontent.md). 568 569## cl.arkui.16 Change to Exception Handling for the backgroundImage Attribute 570 571**Access Level** 572 573Public API 574 575**Reason for Change** 576 577This change is made to improve robustness. 578 579**Change Impact** 580 581Before change: Exceptional values for the **backgroundImage** attribute were left unhandled. 582 583After change: Exceptional values for the **backgroundImage** attribute clear the background image and handled as the default value. 584 585**Start API Level** 586 587The feature is supported since API version 7, and the change takes effective since API version 12. 588 589**Change Since** 590 591OpenHarmony SDK 5.0.0.23 592 593**Adaptation Guide** 594 595No adaptation is required. Yet, since the default exception handling logic is changed, you need to check whether it meets your expectation. Change the variables where necessary. 596 597## cl.arkui.17 Change to Exception Handling for the backgroundImageSize Attribute 598 599**Access Level** 600 601Public API 602 603**Reason for Change** 604 605This change is made to improve robustness. 606 607**Change Impact** 608 609Before change: Exceptional values for the **backgroundImageSize** attribute are treated as a width and height of 0. 610 611After change: Exceptional values are treated as the default value **ImageSize.Auto**. 612 613**Start API Level** 614 615The feature is supported since API version 7, and the change takes effective since API version 12. 616 617**Change Since** 618 619OpenHarmony SDK 5.0.0.23 620 621**Adaptation Guide** 622 623No adaptation is required. Yet, since the default exception handling logic is changed, you need to check whether it meets your expectation. Change the variables where necessary. 624 625## cl.arkui.18 Addition of New Parameter Types in border 626 627**Access Level** 628 629Public API 630 631**Reason for Change** 632 633This change is made to provide mirroring capabilities for the **border** member properties. 634 635**Change Impact** 636 637This change is a non-compatible change. 638 639Before change: The type of **borderWidth** is Length | EdgeWidths. 640 641 The type of **borderColor** is ResourceColor | EdgeColors. 642 643 The type of **borderRadius** is Length | BorderRadiuses. 644 645 The same applies to **borderOptions**. 646 647After change: The type of **borderWidth** is Length | EdgeWidths | LocalizedEdgeWidths. 648 649 The type of **borderColor** is ResourceColor | EdgeColors | LocalizedEdgeColors. 650 651 The type of **borderRadius** is Length | BorderRadiuses | LocalizedBorderRadiuses. 652 653 The same applies to **borderOptions**. 654 655**Start API Level** 656 65712 658 659**Change Since** 660 661OpenHarmony SDK 5.0.0.23 662 663**Key API/Component Changes** 664 665New parameter type LocalizedEdgeWidths for **borderWidth**, LocalizedEdgeColors for **borderColor**, and LocalizedBorderRadiuses for **borderRadius**, along with the expansion of types for **width**, **color**, and **radius** parameters in **borderOptions** 666 667**Adaptation Guide** 668 669Adapt and rectify code according to the error messages. 670 671In the following scenarios, a type incompatibility error is reported: 672 673```ts 674const item: BorderOptions = { width: "10px",color: 0x000000,radius: 10 } 675 676const value1 : Length | EdgeWidths = item.width 677 678const value2 : ResourceColor | EdgeColors = item.color 679 680const value3 : Length | BorderRadiuses = item.radius 681``` 682 683Manually modify the code. 684 685```ts 686const item: BorderOptions = { width: "10px",color: 0x000000,radius: 10 } 687 688const value1 : Length | EdgeWidths | LocalizedEdgeWidths | undefined = item.width 689 690const value2 : ResourceColor | EdgeColors | LocalizedEdgeColors | undefined = item.color 691 692const value3 : Length | BorderRadiuses | LocalizedBorderRadiuses | undefined = item.radius 693``` 694
