1# ArkUI子系统变更说明 2 3## cl.arkui.1 DatePickerDialog、TimePickerDialog、TextPickerDialog设置alignment参数显示效果变更 4 5**访问级别** 6 7公开接口 8 9**变更原因** 10 11规格优化。 12 13**变更影响** 14 15该变更为兼容性变更。 16 17DatePickerDialog、TimePickerDialog、TextPickerDialog支持通过设置alignment参数调整滑动选择器弹窗相对于窗口的弹出位置。具体受影响的场景见下文： 18 19a) 设置alignment为Top、TopStart、TopEnd 20 21变更前：与窗口顶部默认有40vp的间距 22 23变更后：与窗口顶部的间距为0 24 25b) 设置alignment为Bottom 26 27变更前：与窗口底部默认有16vp的间距 28 29变更后：与窗口底部的间距为0 30 31c) 设置alignment为Center 32 33变更前：相对于窗口正中位置默认有16vp的向上偏移 34 35变更后：处于窗口正中位置 36 37**API Level** 38 3911 40 41**变更发生版本** 42 43从OpenHarmony SDK 4.1.5.3开始。 44 45**变更的接口/组件** 46 47日期滑动选择器弹窗（DatePickerDialog）、时间滑动选择器弹窗（TimePickerDialog）、文本滑动选择器弹窗（TextPickerDialog） 48 49**适配指导** 50 51DatePickerDialog、TimePickerDialog、TextPickerDialog设置alignment时与窗口边缘的间距通过offset设置来调整。 52 53## cl.arkui.2 SegmentButton组件buttonMargin、textMargin接口命名变更 54 55**访问级别** 56 57公开接口 58 59**变更原因** 60 61原接口命名与接口实际功能不符。 62 63**变更影响** 64 65该变更为非兼容性变更。修改SegmentButton用于设置按钮内边距、文本内边距的接口命名： 66 67a) 按钮内边距接口命名变更 68 69变更前：buttonMargin 70 71变更后：buttonPadding 72 73b) 文本内边距接口命名变更 74 75变更前：textMargin 76 77变更后：textPadding 78 79**变更发生版本** 80 81从OpenHarmony SDK 4.1.5.3开始。 82 83**变更的接口/组件** 84 85分段按钮（SegmentButton）。 86 87**适配指导** 88 89变更前： 90 91分段按钮通过buttonMargin、textMargin进行按钮内边距、文本内边距的设置。 92 93变更后： 94 95分段按钮通过buttonPadding、textPadding进行按钮内边距、文本内边距的设置。 96 97## cl.arkui.3 TextInput组件cancelButton接口IconOptions.size参数默认值变更 98 99**访问级别** 100 101公开接口 102 103**变更原因** 104 105cancelButton接口不设置IconOptions.size参数，图片的实际尺寸与开发者获取的尺寸不符。 106 107**变更影响** 108 109该变更为非兼容性变更。cancelButton接口不设置IconOptions.size参数，开发者获取的图片尺寸发生变更，变更如下： 110 111变更前：0.00px 112 113变更后：24.00vp 114 115**变更发生版本** 116 117从OpenHarmony SDK 4.1.5.3开始。 118 119**变更的接口/组件** 120 121单行文本输入框（TextInput） 122 123**适配指导** 124 125TextInput设置cancelButton时不设置IconOptions.size参数可以获取正确的图片尺寸24.00vp。 126 127## cl.arkui.4 变更@Prop和@BuilderParam初始化校验规格 128 129**访问级别** 130 131公开接口。 132 133**变更原因** 134 135@Require和@Prop或者@BuilderParam结合使用能够决定是否需要从父组件构造传参，现@Prop和@BuilderParam的初始化校验变更。 136 137**变更影响** 138 139该变更为非兼容性变更。变更@Prop和@BuilderParam初始化校验规格。增加当@Require装饰器和@Prop装饰器或者@BuilderParam装饰器结合使用时，@Prop装饰器或者 @BuilderParam装饰器修饰的变量值必须由父组件构造传参，如父组件未构造传参，编译报错。如果@Prop、@BuilderParam没有和@Require结合使用，不会进行构造传参初始化校验。 140 141**API Level** 142 14311 144 145**变更发生版本** 146 147从OpenHarmony SDK 4.1.5.3 开始。 148 149**示例：** 150 151``` 152@Entry 153@Component 154struct Index { 155 build() { 156 Row() { 157 Child() 158 } 159 } 160} 161 162@Component 163struct Child { 164 // ERROR: Property buildText must be initialized through the component constructor. 165 @Require @BuilderParam buildText: () => void; 166 // ERROR: Property initBuildText must be initialized through the component constructor. 167 @Require @BuilderParam initBuildText: () => void = buildFuction; 168 // ERROR: Property message must be initialized through the component constructor. 169 @Require @Prop message: string = 'Hello'; 170 // ERROR: Property initMessage must be initialized through the component constructor. 171 @Require @Prop initMessage: string; 172 // 删除ERROR: Property 'chindProp' in the custom component 'Child' is missing assignment or initialization. 173 @Prop chindProp: string; 174 // 删除ERROR: Property 'chindBuildParam' in the custom component 'Child' is missing assignment or initialization. 175 @BuilderParam chindBuildParam: () => void; 176 177 build() { 178 } 179} 180 181@Builder 182function buildFuction() { 183} 184``` 185 186**变更的接口/组件** 187 188不涉及。 189 190**适配指导** 191 192当\@Require装饰器和\@Prop装饰器或者\@BuilderParam装饰器结合使用时，\@Prop和\@BuilderParam必须在构造时传参。 193 194 195 196## cl.arkui.5 变更popup样式与避让逻辑规格 197 198**访问级别** 199 200公开接口。 201 202**变更原因** 203 204UX能力增强。 205 206**变更影响** 207 208该变更为兼容性变更。 209 2101. 未设置气泡背景色，默认背景色加模糊填充效果。如果需要去掉模糊背景效果，可以通过调用backgroundBlurStyle接口，并设置BlurStyle.NONE（backgroundBlurStyle: BlurStyle.NONE）去掉即可。 211 212 ```ts 213 // xxx.ets 214 @Entry 215 @Component 216 struct PopupExample { 217 @State handlePopup: boolean = false 218 219 build() { 220 Column() { 221 // PopupOptions 类型设置弹框内容 222 Button('PopupOptions') 223 .onClick(() => { 224 this.handlePopup = !this.handlePopup; 225 }) 226 .bindPopup(this.handlePopup, { 227 message: 'This is a popup with PopupOptions', 228 backgroundBlurStyle: BlurStyle.NONE, 229 }) 230 .position({ x: 100, y: 150 }) 231 } 232 } 233 } 234 ``` 235 2362. 增加12种对齐方式： 237 238 - 上边：TopLeft/Top/TopRight 239 - 下边：BottomLeft/Bottom/BottomRight 240 - 左边：LeftTop/Left/LeftBottom 241 - 右边：RightTop/Right/RightBottom 242 243  244 245 ```ts 246 // xxx.ets 247 @Entry 248 @Component 249 struct PopupExample { 250 @State handlePopup: boolean = false; 251 252 build() { 253 Column() { 254 // PopupOptions 类型设置弹框内容 255 Button('按钮名称') 256 .onClick(() => { 257 this.handlePopup = !this.handlePopup; 258 }) 259 .bindPopup(this.handlePopup, { 260 message: 'Test', 261 placement: Placement.Bottom 262 }) 263 .position({ x: 100, y: 150 }) 264 } 265 } 266 } 267 ``` 268 2693. PopupOptions类型气泡有按钮时，点击气泡区域外消失。 270 271 - 变更前：PopupOptions类型气泡有按钮时，点击气泡区域外消失。 272 273 - 变更后：PopupOptions类型气泡有按钮时，点击气泡区域外不消失。 274 275 > **说明：** 276 > 277 > PopupOptions类型气泡有按钮时，是指bindPopup传入PopupOptions数据结构时，primaryButton或secondaryButton有一个或多个不为空。 278 2794. PopupOptions类型气泡文本超长时添加scroll可以滑动显示。 280 281 - 变更前：PopupOptions类型气泡文本超长时被截断。 282 283 - 变更后：PopupOptions类型气泡文本超长时添加scroll可以滑动显示。 284 2855. PopupOptions类型气泡文本颜色取分层参数中ohos_id_color_text_primary值。 286 287 - 变更前：PopupOptions类型气泡文本颜色取分层参数中ohos_id_color_text_primary_contrary值。 288 289 - 变更后：PopupOptions类型气泡文本颜色取分层参数中ohos_id_color_text_primary值。 290 2916. PopupOptions类型气泡按钮颜色取分层参数中ohos_id_color_text_primary_activated值。 292 293 - 变更前：PopupOptions类型气泡按钮颜色取分层参数中ohos_id_color_text_primary_contrary值。 294 295 - 变更后：PopupOptions类型气泡按钮颜色取分层参数中ohos_id_color_text_primary_activated值。 296 2977. PopupOptions类型气泡按钮布局使用Flex可超长换行。 298 299 - 变更前：PopupOptions类型气泡按钮布超长时显示截断。 300 301 - 变更后：PopupOptions类型气泡按钮布局使用Flex可超长换行。 302 3038. CustomPopupOptions类型气泡新增可配置获焦能力，需要调用CustomPopupOptions中focusable接口并设置为true。 304 305 ```ts 306 // xxx.ets 307 @Entry 308 @Component 309 struct PopupExample { 310 @State customPopup: boolean = false 311 312 // popup构造器定义弹框内容 313 @Builder 314 popupBuilder() { 315 Row({ space: 2 }) { 316 Button("button1") 317 Button("button2") 318 } 319 } 320 321 build() { 322 Column() { 323 // CustomPopupOptions 类型设置弹框内容 324 Button('CustomPopupOptions') 325 .position({ x: 80, y: 300 }) 326 .onClick(() => { 327 this.customPopup = !this.customPopup 328 }) 329 .bindPopup(this.customPopup, { 330 builder: this.popupBuilder, 331 focusable: true 332 }) 333 } 334 } 335 } 336 ``` 337 3389. `showInSubWindow=true`（可超出窗口显示）时最大高度为设备屏幕高度，`showInSubWindow=false`（不可超出窗口）时最大高度为应用窗口高度。 339 340 - 变更前：没有最大高度限制，文本过长会截断显示。 341 342 - 变更后：有最大高度显示，文本过长会添加滚动条显示文本。 343 344 `showInSubWindow=true`（可超出窗口显示）时最大高度为设备屏幕高度。即状态栏高度（无状态栏时为0）至底部Dock栏高度（无Dock栏时高度为0）。 345 346 `showInSubWindow=false`（不可超出窗口）时最大高度为应用窗口高度。即状态栏高度（无状态栏时为0）至底部Dock栏高度（无Dock栏时高度为0）。 347 348 > **说明：** 349 > 350 > 最大高度距离最上方和最下方分别有40vp的间距。 351 352上述第1、第5和第6条变更前后样式对比如下图所示。 353 354- 变更前： 355  356- 变更后： 357  358 359> **说明：** 360> 361> - PopupOptions类型气泡为，bindPopup传入PopupOptions数据结构时的气泡。 362> 363> - CustomPopupOptions类型气泡为，bindPopup传入CustomPopupOptions数据结构时的气泡。 364 365**API Level** 366 36711 368 369**变更发生版本** 370 371从OpenHarmony SDK 4.1.5.2 开始。 372 373**变更的接口/组件** 374 375bindPopup属性。 376 377**适配指导** 378 3791.根据用户需求自定义气泡背景色，详情参考第1条。 380 3812.根据用户需求自定气泡获焦能力，详情参考第8条。 382 383## cl.Arkui.6 弹窗类组件支持可显示在子窗口 384 385**访问级别** 386 387公开接口 388 389**变更原因** 390 391UX能力增强 392 393**变更影响** 394 395该变更为兼容性变更，为AlterDialog、ActionSheet组件以及promptAction的showDialog和showActionMenu这几种弹窗的接口添加CustomDialog组件已有的showInSubWindow属性，默认值为false。手动设置为true时，该弹窗会创建在子窗口上，可显示在应用窗口外。 396 397**API Level** 398 39911 400 401**变更发生版本** 402 403从OpenHarmony SDK 4.1.5.5开始。 404 405**变更的接口/组件** 406 407API 11前，只有CustomDialog组件的CustomDialogControllerOptions接口有showInSubWindow属性，showInSubWindow默认值为false，手动设置为true时，该弹窗会创建在子窗口上，可显示在应用窗口外，设置为false时，弹窗创建在应用窗口上。 408 409API 11及以后，AlterDialog、CustomDialog、ActionSheet组件以及promptAction的showDialog和showActionMenu接口创建的弹窗都有showInSubWindow属性，showInSubWindow默认值为false，手动设置为true时，该弹窗会创建在子窗口上，可显示在应用窗口外，设置为false时，弹窗创建在应用窗口上。 410 411**适配指导** 412 413新功能实现兼容原有功能，不涉及适配。 414 415## cl.Arkui.7 CustomDialog组件的蒙层范围的更改 416 417**访问级别** 418 419公开接口 420 421**变更原因** 422 423UX一致性需求变更 424 425**变更影响** 426 427该变更为非兼容性变更。 428 429变更前，showInSubWindow为true时，CustomDialog的蒙层范围为子窗口范围，showInSubWindow为false时，CustomDialog的蒙层范围为应用窗口范围。 430 431 432 433变更后，无论showInSubWindow为true还是false，CustomDialog的蒙层范围都为应用窗口的范围。 434 435 436 437**API Level** 438 43911 440 441**变更发生版本** 442 443从OpenHarmony SDK 4.1.5.5开始。 444 445**变更的接口/组件** 446 447API 11前，showInSubWindow为true时，CustomDialog的蒙层范围为子窗口范围，showInSubWindow为false时，CustomDialog的蒙层范围为应用窗口范围。 448 449API 11及以后，无论showInSubWindow为true还是false，CustomDialog的蒙层范围都为应用窗口的范围。 450 451**适配指导** 452 453原有的showInSubWindow为true时自定义弹窗蒙层范围固定为为子窗口范围，现在showInSubWindow为true时自定义弹窗弹窗蒙层范围是应用窗口的范围，可以通过控制应用窗口的范围控制蒙层范围。 454 455## cl.Arkui.8 弹窗类组件组件的蒙层是否显示的可配置 456 457**访问级别** 458 459公开接口 460 461**变更原因** 462 463UX能力增强 464 465**变更影响** 466 467该变更为兼容性变更，为AlterDialog、CustomDialog、ActionSheet组件以及promptAction的showDialog和showActionMenu这几种弹窗的接口添加isModal属性，默认值为true。isModal属性为true时，弹窗有蒙层，isModal属性为false时，弹窗无蒙层。 468 469**API Level** 470 47111 472 473**变更发生版本** 474 475从OpenHarmony SDK 4.1.5.5开始。 476 477**变更的接口/组件** 478 479API 11前，无isModal属性，所有弹窗都有蒙层。 480 481API 11及以后，添加isModal属性，默认值为true。isModal属性为true时，弹窗有蒙层，isModal属性为false时，弹窗无蒙层。 482 483**适配指导** 484 485新功能实现兼容原有功能，不涉及适配。 486 487## cl.Arkui.9 Popup高级组件接口修改 488 489**访问级别** 490 491公开接口 492 493**变更原因** 494 495UX能力增强 496 497**变更影响** 498 499@ohos.arkui.advanced.Popup（气泡组件）的PopupIconOptions数据结构中，image变量不可传入PixelMap与DrawableDescriptor数据类型。 500 501**API Level** 502 50311 504 505**变更发生版本** 506 507从OpenHarmony SDK 4.1.5.2 开始。 508 509**变更的接口/组件** 510 511API 11前，无。 512 513API 11及以后，@ohos.arkui.advanced.Popup（气泡组件）的PopupIconOptions数据结构中，image变量只可传入ResourceStr数据类型。 514 515**适配指导** 516 517@ohos.arkui.advanced.Popup（气泡组件）的PopupIconOptions数据结构中，image变量传入ResourceStr数据类型。
