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 DatePickerDialog标题按钮大小及布局变更 332 333**访问级别** 334 335公开接口 336 337**变更原因** 338 339UX规格增强 340 341**变更影响** 342 343该变更为非兼容性变更。 344 345变更前：DatePickerDialog标题按钮大小与文本大小一致，底部操作区距离弹窗边缘24vp。 346 347变更后：DatePickerDialog标题按钮高度为32vp，距离弹窗左右边界为16vp，底部操作区与离弹窗边缘无间距。 348 349如下图所示为变更前后效果对比： 350 351| 变更前 | 变更后 | 352|---------|---------| 353|  |  | 354 355**起始API Level** 356 35712 358 359**变更发生版本** 360 361从OpenHarmony SDK 5.0.0.23开始。 362 363**适配指导** 364 365默认行为变更，无需适配，但应注意变更后的行为是否对整体应用逻辑产生影响。 366 367## cl.arkui.10 bindSheet组件修改标题与关闭按钮之间的间距 368 369**访问级别** 370 371公开接口 372 373**变更原因** 374 375为满足应用述求和新的UX规格，标题与关闭按钮的间距调整为8vp。 376 377**变更影响** 378 379该变更为非兼容性变更。 380 381API version 12之前，标题与关闭按钮之间的距离为32vp。 382 383API version 12及以后，标题与关闭按钮之间的距离为8vp。 384 385变更示例图： 386 387 388 389**起始API Level** 390 39111 392 393**变更发生版本** 394 395从OpenHarmony SDK 5.0.0.23开始。 396 397**变更的接口/组件** 398 399bindSheet组件 400 401**适配指导** 402 403默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 404 405## c1.arkui.13 bindSheet半模态面板的backgroundColor属性异常值处理逻辑变更 406 407**访问级别** 408 409公开接口 410 411**变更原因** 412 413bindSheet半模态面板的backgroundColor属性设置从正常值更新为异常值时，使用默认值。 414 415**变更影响** 416 417该变更为非兼容性变更。 418 419变更前，当开发者对bindSheet半模态面板的backgroundColor属性设置从正常值更新为异常值时，采用不操作处理。 420 421变更后，当开发者对bindSheet半模态面板的backgroundColor属性设置从正常值更新为异常值时，采用默认颜色处理。 422 423**起始API Level** 424 42511 426 427**变更发生版本** 428 429从OpenHarmony SDK 5.0.0.23 版本开始。 430 431**变更的接口/组件** 432 433bindSheet半模态面板。 434 435**适配指导** 436 437异常值处理逻辑变更，不涉及适配。 438 439默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 440 441## cl.arkui.11 Menu 组件边距 margin 变更 442 443**访问级别** 444 445公开接口 446 447**变更原因** 448 449菜单弹出 UX 默认行为改变 450 451**变更影响** 452 453API12变更之前：菜单带有边距 margin，左右方向为 12vp，上下方向为 24vp。 454 455API12变更之后：如果配置菜单在应用窗口内弹出，左右方向的 margin 为 16vp，上下侧默认规避状态栏与导航条，不额外增加避让距离；如果配置菜单在应用窗口外弹出，左右方向的 margin 为 8vp，上下侧默认规避状态栏与 Dock 区域，不额外增加避让距离。 456 457**起始API Level** 458 4599 460 461**变更发生版本** 462 463从OpenHarmony SDK 5.0.0.23版本开始。 464 465**变更的接口/组件** 466 467Menu 组件 468 469**适配指导** 470 471默认效果变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则应自定义修改效果控制变量以达到预期。 472 473## cl.arkui.12 TabContent组件底部页签水平方向排列情景默认字体大小变更 474 475**访问级别** 476 477公开接口 478 479**变更原因** 480 481当前TabContent组件底部页签水平方向排列情景时默认字体大小为10vp，字体偏小，视觉效果较差，变更为12vp，以提升视觉效果。 482 483**变更影响** 484 485该变更为非兼容性变更。 486 487API version 12之前，TabContent组件底部页签水平方向排布情景默认字体大小为10vp。 488 489 490 491API version 12及以后，TabContent组件底部页签水平方向排布情景默认字体大小为12vp。 492 493 494 495**起始API Level** 496 49710 498 499**变更发生版本** 500 501从OpenHarmony SDK 5.0.0.23开始。 502 503**变更的接口/组件** 504 505TabContent组件 506 507**适配指导** 508 509默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合可参照[TabContent组件](../../../application-dev/reference/apis-arkui/arkui-ts/ts-container-tabcontent.md)说明文档设置相关属性以达到预期。 510 511## cl.arkui.13 backgroundImage异常参数处理规格变更 512 513**访问级别** 514 515公开接口 516 517**变更原因** 518 519接口异常值处理变更。 520 521**变更影响** 522 523变更前：异常值时不处理。 524 525变更后：异常值时清除背景图，作默认值处理。 526 527**起始API Level** 528 529该特性版本为API 7,变更版本为API 12。 530 531**变更发生版本** 532 533从OpenHarmony SDK 5.0.0.23开始。 534 535**适配指导** 536 537异常值处理逻辑变更，不涉及适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 538 539## cl.arkui.14 backgroundImageSize异常参数处理规格变更 540 541**访问级别** 542 543公开接口 544 545**变更原因** 546 547接口异常值处理变更。 548 549**变更影响** 550 551变更前：异常值时当作宽高为0处理。 552 553变更后：异常值时当作默认值ImageSize.Auto处理。 554 555**起始API Level** 556 557该特性版本为API 7,变更版本为API 12。 558 559**变更发生版本** 560 561从OpenHarmony SDK 5.0.0.23开始。 562 563**适配指导** 564 565异常值处理逻辑变更，不涉及适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 566 567## cl.arkui.15 border中对部分接口新增参数类型 568 569**访问级别** 570 571公开接口 572 573**变更原因** 574 575扩展border成员属性类型，提供镜像能力。 576 577**变更影响** 578 579该变更为不兼容变更。 580 581变更前：borderWidth 参数类型为Length | EdgeWidths； 582 583 borderColor 参数类型为ResourceColor | EdgeColors； 584 585 borderRadius 参数类型为 Length | BorderRadiuses； 586 587 borderOptions同理 588 589变更后：borderWidth 参数类型为Length | EdgeWidths | LocalizedEdgeWidths； 590 591 borderColor 参数类型为ResourceColor | EdgeColors | LocalizedEdgeColors； 592 593 borderRadius 参数类型为Length | BorderRadiuses | LocalizedBorderRadiuses； 594 595 borderOptions同理 596 597**起始API Level** 598 59912 600 601**变更发生版本** 602 603从OpenHarmony SDK 5.0.0.23开始。 604 605**变更的接口/组件** 606 607新增 borderWidth参数LocalizedEdgeWidths，borderColor参数LocalizedEdgeColors，borderRadius参数LocalizedBorderRadiuses以及borderOptions中width、color、radius参数的类型扩充。 608 609**适配指导** 610 611开发者需要根据错误提示信息，进行适配整改。 612 613针对以下场景，会存在类型不兼容报错。 614 615```ts 616const item: BorderOptions = { width: "10px",color: 0x000000,radius: 10 } 617 618const value1 : Length | EdgeWidths = item.width 619 620const value2 : ResourceColor | EdgeColors = item.color 621 622const value3 : Length | BorderRadiuses = item.radius 623``` 624 625需要开发者手动修改代码。 626 627```ts 628const item: BorderOptions = { width: "10px",color: 0x000000,radius: 10 } 629 630const value1 : Length | EdgeWidths | LocalizedEdgeWidths | undefined = item.width 631 632const value2 : ResourceColor | EdgeColors | LocalizedEdgeColors | undefined = item.color 633 634const value3 : Length | BorderRadiuses | LocalizedBorderRadiuses | undefined = item.radius 635``` 636 637
