1# ArkUI子系统Changelog 2 3## cl.arkui.1 bindMenu新增指向性菜单样式 4 5**访问级别** 6 7公开接口 8 9**变更原因** 10 11UX规格增强 12 13**变更影响** 14 15该变更为非兼容性变更。 16 17变更前：在bindMenu的MenuOptions中将enableArrow属性设为true时，不展示指向性菜单样式。 18 19变更后：在bindMenu的MenuOptions中将enableArrow属性设为true且菜单的大小和位置足以放置箭头时，会展示指向性菜单样式。 20 21**API Level** 22 23enableArrow、arrowOffset属性的起始支持版本为API version 10。 24 25**变更发生版本** 26 27从OpenHarmony SDK 5.0.0.23开始。 28 29**适配指导** 30 31如果不需要bindMenu展示指向性菜单样式，在bindMenu的MenuOptions中不设置enableArrow属性或将enableArrow属性设置为false； 32如果需要bindMenu展示指向性菜单样式，在bindMenu的MenuOptions中将enableArrow属性设置为true，并根据需要决定是否设置arrowOffset属性值。 33 34## cl.arkui.2 应用可获焦的默认行为变更 35 36**访问级别** 37 38公开接口 39 40**变更原因** 41 42优化默认走焦行为。 43 44**变更影响** 45 46该变更为非兼容性变更。 47 48变更前：有获焦能力但默认不可获焦的组件，需要通过配置属性`.focusable(true)`使得自身可获焦，且走焦时没有默认焦点框，需要配置焦点态样式。 49 50变更后：注册了onClick或者单指单击手势的组件默认可获焦，走焦时无需配置焦点态样式也能显示默认焦点框。 51 52**API Level** 53 54该特性变更起始支持版本为 API 12。 55 56**变更发生版本** 57 58从OpenHarmony SDK 5.0.0.23开始。 59 60**适配指导** 61 62可点击组件不希望参与走焦，需要显示配置`.focusable(false)`； 63 64## cl.arkui.3 Dialog组件弹窗圆角、背景色、背景模糊、宽高限制、响应式/自适应、阴影样式等默认样式变更 65 66**访问级别** 67 68公开接口 69 70**变更原因** 71 72对弹窗视觉风格进行优化，包括圆角、背景色、材质、阴影；对弹窗响应式布局进行优化，在多设备上获得更好的用户体验。 73 74**变更影响** 75 76该变更为非兼容性变更，只影响弹窗的默认样式，自定义样式后以设置为准，自定义设置非法值时，效果等同默认场景。 77 78- 变更前 79 1. 弹窗圆角默认四个角均为24vp 80 2. 弹窗浅色模式默认背景色为0xd9fffff 81 3. 大部分弹窗默认均为背景色为透明（Color.Transparent）和 背景模糊（COMPONENT_ULTRA_THICK）叠加，customDialog和PromptAction中showDialog和openCustomDialog还是使用的默认背景色。 82 4. 弹窗默认宽度为栅格系统控制，最大宽度400vp，当设备为2in1时，弹窗固定大小为400vp不可改变，无法自定义设置宽度。 83 5. 弹窗默认最大高度为（屏幕高度 - 安全区域）* 0.8， 当设备为2in1时，高度最大为全屏 * 0.67 * 0.9。 84 6. 弹窗响应式/自适应场景下，居中样式为避让导航条后的居中；默认场景下弹窗对齐方式是DialogAlignment.Bottom样式，其余设备均为居中样式。 85 7. 所有设备都没有默认的阴影样式。 86 87 <br/> 88- 变更后 89 1. 弹窗圆角默认四个角均为32vp 90 2. 弹窗浅色模式默认背景色为0xfffff 91 3. 所有弹窗默认均为背景色为透明（Color.Transparent）和 背景模糊（COMPONENT_ULTRA_THICK）叠加 92 4. 弹窗默认宽度为所在窗口宽度 - 左右margin，设备上margin为16；当设备为2in1时，左右margin为40。默认最大宽度为400vp，可以随所在窗口大小变化。当自定义设置width接口值时，以自定义设置为准， 弹窗参考宽度为所在窗口的宽度，在此基础上调小或调大；自定义设置非法值时，效果等同默认场景。 93 5. 弹窗默认最小高度为70vp，默认最大高度均为（窗口高度 - 安全区域）* 0.9，无设备差异。当自定义设置Height接口值时，以自定义设置为准，弹窗参考高度为（窗口高度 - 安全区域），在此基础上调小或调大；自定义设置非法值时，效果等同默认场景。 94 6. 弹窗响应式/自适应场景下，居中样式为全屏居中，所有设备都默认弹窗居中。 95 7. 当设备为2in1时，默认场景下获焦阴影值为ShadowStyle.OUTER_FLOATING_MD，失焦为ShadowStyle.OUTER_FLOATING_SM；其余设备没有默认阴影样式。 96 97 如下图所示为变更前后效果对比： 98 99| 变更前 | 变更后 | 100|---------|---------| 101|  |  | 102|  |  | 103|  |  | 104|  |  | 105 106**API Level** 107 108在API 12进行版本隔离 109 110**变更发生版本** 111 112从OpenHarmony SDK 5.0.0.23 版本开始。 113 114**变更的接口/组件** 115 116Dialog组件。 117 118**适配指导** 119 120默认效果变更：默认效果变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则应自定义修改效果控制变量以达到预期。 121 122## cl.arkui.4 拖拽预览图支持透明度效果及应用自定义 123 124**访问级别** 125 126公开接口 127 128**变更原因** 129 130依照UX规范 131 132**变更影响** 133 134该变更为非兼容性变更。 135 136API version 11及以前：可拖拽组件长按浮起预览图后没有透明度。 137 138API version 12及以后：可拖拽组件长按浮起预览图默认为95%透明度，应用可自定义透明度数值。 139 140**API Level** 141 14212 143 144**变更发生版本** 145 146从OpenHarmony SDK 5.0.0.23开始。 147 148**适配指导** 149 150默认样式变更调整，无需适配。 151 152## cl.arkui.5 @Observed/@Track/@ObservedV2新增校验变更 153**访问级别** 154 155公开接口 156 157**变更原因** 158 159深度观察的装饰器存在新旧两个接口，增加编译校验，防止开发者混用，导致运行时功能异常。 160 161**变更影响** 162 163变更前：不校验报错。 164 165变更后： 166如果开发者存在以下场景，不按规范使用，编译会报错。 167 168- 在@ObservedV2修饰的class内使用@Track。 169 170> **说明：** 171> 172> 因为新的@ObservedV2采用了和@Observed不同的实现逻辑，因此不能在@ObservedV2修饰的class内使用@Track。@Track可以和@Observed一起使用，@Trace可以和@ObservedV2一起使用。 173 174- 一个class同时被@Observed和@ObservedV2装饰。 175 176> **说明：** 177> 178> 将Observed和@ObservedV2混合使用，会出现未定义行为，表现为冗余刷新、失去深度观测能力、失去自身属性观测能力、失去属性级更新能力等。因此不能将Observed和@ObservedV2混合使用。 179 180- 装饰子类和父类的@Observed和@ObservedV2不一致。 181 182错误示例如下： 183 184```ts 185// @Track不能使用在@ObservedV2修饰的class内 186@ObservedV2 187class TestObserved { 188 @Track value: string = "hello" 189} 190// 一个class不能同时被@Observed和@ObservedV2装饰 191@Observed 192@ObservedV2 193class TestObserved1 { 194 value: string = "hello" 195} 196// 装饰子类和父类的@Observed和@ObservedV2需要保持一致 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**起始API Level** 217 218起始支持版本为 API 12。 219 220**变更发生版本** 221 222从OpenHarmony SDK 5.0.0.23开始。 223 224**适配指导** 225 226开发者需要根据错误提示信息，进行适配整改。 227 228## cl.arkui.6 TextInput、TextArea、Search、RichEditor空间文本菜单样式变更 229 230**访问级别** 231 232公开接口 233 234**变更原因** 235 236规格变更 237 238**变更影响** 239 240该变更为兼容性变更。 241API Version 11 以及之前的版本：文本选择菜单，包含分享、搜索、翻译按钮，三个按钮都是灰色，并且有拓展菜单。 242 243API Version 12 变更后：文本选择菜单，不包含分享、搜索、翻译按钮，不出现拓展菜单。 244 245**起始 API Level** 246 247文本菜单是系统能力，无对外接口。 248 249**变更发生版本** 250 251从OpenHarmony SDK 5.0.0.23 版本开始。 252 253**变更的接口/组件** 254 255TextInput、TextArea、Search、RichEditor。 256 257**适配指导** 258 259默认行为变更，无需适配，但应注意变更后的行为是否对整体应用逻辑产生影响。 260 261## cl.arkui.7 ImageSpan、ContainerSpan单独使用在DevEco Studio中报错变更 262 263**访问级别** 264 265公开接口 266 267**变更原因** 268 269规格变更 270 271**变更影响** 272 273该变更为非兼容性变更。 274变更前：Text子组件ImageSpan、ContainerSpan放在其他组件下使用，编译无报错。 275变更后：DevEco Studio中单独使用ImageSpan、ContainerSpan组件，而不是作为Text的子组件被使用，编译报错。 276 277**起始 API Level** 278 27912 280 281**变更发生版本** 282 283从OpenHarmony SDK 5.0.0.23 版本开始。 284 285**变更的接口/组件** 286 287ImageSpan、ContainerSpan。 288 289**适配指导** 290 291默认行为变更，开发者按照报错提示修改。 292 293## cl.arkui.8 Popup组件宽度设置100%场景下避让位置变更 294 295**访问级别** 296 297公开接口 298 299**变更原因** 300 301UX样式变更 302 303**变更影响** 304 305该变更为非兼容性变更。 306 307变更前，Popup宽度大于等于100% - 6vp时，Popup会进行默认避让，且距离窗口左侧有6vp边距。 308 309变更后，Popup宽度大于等于100% - 6vp时，Popup不会进行默认避让，且距离窗口左侧没有6vp边距。 310 311| 变更前 | 变更后 | 312|---------|---------| 313|  |  | 314 315**起始API Level** 316 3177 318 319**变更发生版本** 320 321从OpenHarmony SDK 5.0.0.23 版本开始。 322 323**变更的接口/组件** 324 325Popup组件。 326 327**适配指导** 328 329默认效果变更，应注意变更后的默认效果是否符合开发者预期，如不符合可以使用offset属性自行调整Popup位置，请查阅[Popup控制](../../../application-dev/reference/apis-arkui/arkui-ts/ts-universal-attributes-popup.md)文档。 330 331## cl.arkui.9 拖拽预览图支持统一圆角及应用自定义 332 333**访问级别** 334 335公开接口 336 337**变更原因** 338 339依照UX规范 340 341**变更影响** 342 343该变更为非兼容性变更。 344 345API version 11及以前：非文本类组件长按浮起预览图显示应用自定义的圆角效果。 346 347API version 12及以后：非文本类组件长按浮起预览图通过检查DragPreviewOptions.mode来判断是否启用非文本类组件统一圆角效果，默认值12vp。当应用自身设置的圆角值大于默认值时，则显示应用自定义圆角效果。 348 349**API Level** 350 35112 352 353**变更发生版本** 354 355从OpenHarmony SDK 5.0.0.23开始。 356 357**适配指导** 358 359默认样式变更调整，无需适配。 360 361## cl.arkui.10 拖拽支持预览图背景模糊效果 362 363**访问级别** 364 365公开接口 366 367**变更原因** 368 369依照UX规范 370 371**变更影响** 372 373该变更为非兼容性变更。 374 375API version 11及以前：非文本类组件长按浮起预览图，预览图无背景模糊效果。 376 377API version 12及以后：非文本类组件长按浮起预览图，预览图有背景模糊效果。 378 379**API Level** 380 38112 382 383**变更发生版本** 384 385从OpenHarmony SDK 5.0.0.23开始。 386 387**适配指导** 388 389默认样式变更调整，无需适配。 390 391## cl.arkui.11 DatePickerDialog标题按钮大小及布局变更 392 393**访问级别** 394 395公开接口 396 397**变更原因** 398 399UX规格增强 400 401**变更影响** 402 403该变更为非兼容性变更。 404 405变更前：DatePickerDialog标题按钮大小与文本大小一致，底部操作区距离弹窗边缘24vp。 406 407变更后：DatePickerDialog标题按钮高度为32vp，距离弹窗左右边界为16vp，底部操作区与离弹窗边缘无间距。 408 409如下图所示为变更前后效果对比： 410 411| 变更前 | 变更后 | 412|---------|---------| 413|  |  | 414 415**起始API Level** 416 41712 418 419**变更发生版本** 420 421从OpenHarmony SDK 5.0.0.23开始。 422 423**适配指导** 424 425默认行为变更，无需适配，但应注意变更后的行为是否对整体应用逻辑产生影响。 426 427## cl.arkui.12 bindSheet组件修改标题与关闭按钮之间的间距 428 429**访问级别** 430 431公开接口 432 433**变更原因** 434 435为满足应用述求和新的UX规格，标题与关闭按钮的间距调整为8vp。 436 437**变更影响** 438 439该变更为非兼容性变更。 440 441API version 12之前，标题与关闭按钮之间的距离为32vp。 442 443API version 12及以后，标题与关闭按钮之间的距离为8vp。 444 445变更示例图： 446 447 448 449**起始API Level** 450 45111 452 453**变更发生版本** 454 455从OpenHarmony SDK 5.0.0.23开始。 456 457**变更的接口/组件** 458 459bindSheet组件 460 461**适配指导** 462 463默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 464 465## c1.arkui.13 bindSheet半模态面板的backgroundColor属性异常值处理逻辑变更 466 467**访问级别** 468 469公开接口 470 471**变更原因** 472 473bindSheet半模态面板的backgroundColor属性设置从正常值更新为异常值时，使用默认值。 474 475**变更影响** 476 477该变更为非兼容性变更。 478 479变更前，当开发者对bindSheet半模态面板的backgroundColor属性设置从正常值更新为异常值时，采用不操作处理。 480 481变更后，当开发者对bindSheet半模态面板的backgroundColor属性设置从正常值更新为异常值时，采用默认颜色处理。 482 483**起始API Level** 484 48511 486 487**变更发生版本** 488 489从OpenHarmony SDK 5.0.0.23 版本开始。 490 491**变更的接口/组件** 492 493bindSheet半模态面板。 494 495**适配指导** 496 497异常值处理逻辑变更，不涉及适配。 498 499默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 500 501## cl.arkui.14 Menu 组件边距 margin 变更 502 503**访问级别** 504 505公开接口 506 507**变更原因** 508 509菜单弹出 UX 默认行为改变 510 511**变更影响** 512 513API12变更之前：菜单带有边距 margin，左右方向为 12vp，上下方向为 24vp。 514 515API12变更之后：如果配置菜单在应用窗口内弹出，左右方向的 margin 为 16vp，上下侧默认规避状态栏与导航条，不额外增加避让距离；如果配置菜单在应用窗口外弹出，左右方向的 margin 为 8vp，上下侧默认规避状态栏与 Dock 区域，不额外增加避让距离。 516 517**起始API Level** 518 5199 520 521**变更发生版本** 522 523从OpenHarmony SDK 5.0.0.23版本开始。 524 525**变更的接口/组件** 526 527Menu 组件 528 529**适配指导** 530 531默认效果变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则应自定义修改效果控制变量以达到预期。 532 533## cl.arkui.15 TabContent组件底部页签水平方向排列情景默认字体大小变更 534 535**访问级别** 536 537公开接口 538 539**变更原因** 540 541当前TabContent组件底部页签水平方向排列情景时默认字体大小为10vp，字体偏小，视觉效果较差，变更为12vp，以提升视觉效果。 542 543**变更影响** 544 545该变更为非兼容性变更。 546 547API version 12之前，TabContent组件底部页签水平方向排布情景默认字体大小为10vp。 548 549 550 551API version 12及以后，TabContent组件底部页签水平方向排布情景默认字体大小为12vp。 552 553 554 555**起始API Level** 556 55710 558 559**变更发生版本** 560 561从OpenHarmony SDK 5.0.0.23开始。 562 563**变更的接口/组件** 564 565TabContent组件 566 567**适配指导** 568 569默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合可参照[TabContent组件](../../../application-dev/reference/apis-arkui/arkui-ts/ts-container-tabcontent.md)说明文档设置相关属性以达到预期。 570 571## cl.arkui.16 backgroundImage异常参数处理规格变更 572 573**访问级别** 574 575公开接口 576 577**变更原因** 578 579接口异常值处理变更。 580 581**变更影响** 582 583变更前：异常值时不处理。 584 585变更后：异常值时清除背景图，作默认值处理。 586 587**起始API Level** 588 589该特性版本为API 7,变更版本为API 12。 590 591**变更发生版本** 592 593从OpenHarmony SDK 5.0.0.23开始。 594 595**适配指导** 596 597异常值处理逻辑变更，不涉及适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 598 599## cl.arkui.17 backgroundImageSize异常参数处理规格变更 600 601**访问级别** 602 603公开接口 604 605**变更原因** 606 607接口异常值处理变更。 608 609**变更影响** 610 611变更前：异常值时当作宽高为0处理。 612 613变更后：异常值时当作默认值ImageSize.Auto处理。 614 615**起始API Level** 616 617该特性版本为API 7,变更版本为API 12。 618 619**变更发生版本** 620 621从OpenHarmony SDK 5.0.0.23开始。 622 623**适配指导** 624 625异常值处理逻辑变更，不涉及适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 626 627## cl.arkui.18 border中对部分接口新增参数类型 628 629**访问级别** 630 631公开接口 632 633**变更原因** 634 635扩展border成员属性类型，提供镜像能力。 636 637**变更影响** 638 639该变更为不兼容变更。 640 641变更前：borderWidth 参数类型为Length | EdgeWidths； 642 643 borderColor 参数类型为ResourceColor | EdgeColors； 644 645 borderRadius 参数类型为 Length | BorderRadiuses； 646 647 borderOptions同理 648 649变更后：borderWidth 参数类型为Length | EdgeWidths | LocalizedEdgeWidths； 650 651 borderColor 参数类型为ResourceColor | EdgeColors | LocalizedEdgeColors； 652 653 borderRadius 参数类型为Length | BorderRadiuses | LocalizedBorderRadiuses； 654 655 borderOptions同理 656 657**起始API Level** 658 65912 660 661**变更发生版本** 662 663从OpenHarmony SDK 5.0.0.23开始。 664 665**变更的接口/组件** 666 667新增 borderWidth参数LocalizedEdgeWidths，borderColor参数LocalizedEdgeColors，borderRadius参数LocalizedBorderRadiuses以及borderOptions中width、color、radius参数的类型扩充。 668 669**适配指导** 670 671开发者需要根据错误提示信息，进行适配整改。 672 673针对以下场景，会存在类型不兼容报错。 674 675```ts 676const item: BorderOptions = { width: "10px",color: 0x000000,radius: 10 } 677 678const value1 : Length | EdgeWidths = item.width 679 680const value2 : ResourceColor | EdgeColors = item.color 681 682const value3 : Length | BorderRadiuses = item.radius 683``` 684 685需要开发者手动修改代码。 686 687```ts 688const item: BorderOptions = { width: "10px",color: 0x000000,radius: 10 } 689 690const value1 : Length | EdgeWidths | LocalizedEdgeWidths | undefined = item.width 691 692const value2 : ResourceColor | EdgeColors | LocalizedEdgeColors | undefined = item.color 693 694const value3 : Length | BorderRadiuses | LocalizedBorderRadiuses | undefined = item.radius 695``` 696 697
