1# ArkUI子系统变更说明
2
3## cl.arkui.1 Slider设置showTips方法显示效果变更
4
5**访问级别**
6
7公开接口
8
9**变更原因**
10
11该变更为兼容性变更，约束了Silder气泡的使用，优化了slider气泡的样式。
12
13**变更影响**
14
15Slider通过设置showTips方法，显示气泡。该方法有两个参数，参数1:boolean类型，表示是否显示气泡；参数2:ResourceStr类型，表示气泡中的文本内容。
16具体受影响的场景见下文：
17
18a) showTips 第一个参数设置为true显示气泡，气泡样式变化
19
20变更前气泡样式：
21
22![Alt text](figures/oldVertical.png)![Alt text](figures/oldHorizontal.png)
23
24变更后气泡样式：
25
26![Alt text](figures/newVertical.png)![Alt text](figures/newHorizontal.png)
27
28b) showTips 第二个参数设置文本内容时，文本内容可能产生变化
29
30变更前：根据栅格化宽度，可多行显示文本，全量显示文本。
31
32变更后：单行显示文本，文本最大宽度36vp，即最大显示2个中文字符或4个数字。
33
34**API Level**
35
367
37
38**变更发生版本**
39
40从OpenHarmony SDK 4.1.5.5开始。
41
42**变更的接口/组件**
43
44滑动条（Slider）
45
46**适配指导**
47
48默认行为变更，不涉及适配。
49
50## cl.Arkui.2 Progress组件的默认颜色变更
51
52**访问级别**
53
54公开接口
55
56**变更原因**
57
58当前Progress组件的默认进度条前景色、默认进度条底色和默认内描边颜色不符合UX规范，因此依照UX规范对相关默认颜色做出变更。
59
60**变更影响**
61
62该变更为兼容性变更，改变了组件默认情况下的显示颜色，提升了组件的默认显示效果。
63
64**API Level**
65
668
67
68**变更发生版本**
69
70从OpenHarmony SDK 4.1.5.5开始。
71
72**变更的接口/组件**
73
74API 11前，胶囊样式进度条默认前景色是系统资源中的`ohos_id_color_emphasize_contrary`，默认内描边颜色是系统资源中的`ohos_id_color_emphasize_contrary`，环形样式进度条默认进度条底色是系统资源中的`ohos_id_color_component_normal`。
75
76![progress](figures/oldProgress.png)
77
78API 11及以后，胶囊样式进度条默认前景色是系统资源中的`ohos_id_color_emphasize`，前景色不透明度为系统资源中的`ohos_id_alpha_highlight_bg`，默认内描边颜色是系统资源中的`ohos_id_color_emphasize`，内描边颜色不透明度为系统资源中的`ohos_id_alpha_highlight_bg`，环形样式进度条默认进度条底是系统资源中的`ohos_id_color_button_normal`。
79
80![progress](figures/newProgress.png)
81
82**适配指导**
83
84默认颜色变更，不涉及适配。
85
86## cl.Arkui.3 LoadingProgress组件的默认颜色变更
87
88**访问级别**
89
90公开接口
91
92**变更原因**
93
94当前LoadingProgress组件的默认前景色不符合UX规范，因此依照UX规范对相关默认前景色做出变更。
95
96**变更影响**
97
98该变更为兼容性变更，改变了组件默认情况下的显示颜色，提升了组件的默认显示效果。
99
100**API Level**
101
1028
103
104**变更发生版本**
105
106从OpenHarmony SDK 4.1.5.5开始。
107
108**变更的接口/组件**
109
110API 11前，默认前景色不透明度为0.6，默认前景色是“#99666666”。
111
112![loadingProgress](figures/oldLoadingProgress.png)
113
114API 11及以后，默认前景色不透明度为1.0，默认前景色是“#ff666666”。
115
116![loadingProgress](figures/newLoadingProgress.png)
117
118**适配指导**
119
120默认颜色变更，不涉及适配。
121
122## cl.arkui.4 Image组件colorFilter属性默认行为变更
123
124**访问级别**
125
126公开接口
127
128**变更原因**
129
130用户对于Image组件colorFilter属性设置异常值时，使用默认值
131
132**变更影响**
133
134该变更为非兼容性变更。
135
136变更前，当开发者对Image组件的colorFilter属性设置为异常值时，采用不操作处理。
137
138变更后，当开发者对Image组件的colorFilter属性设置为异常值时，采用对角线为 $1$ 其余值为 $0$ 的 $4 \times 5$ 的矩阵来处理。
139
140**API Level**
141
14211
143
144**变更发生版本**
145
146从OpenHarmony SDK 4.1.5.5 开始。
147
148**变更的接口/组件**
149
150受影响的组件有：Image。
151
152**适配指导**
153
154默认行为变更，不涉及适配。
155
156## cl.arkui.5 Image组件fillColor属性默认行为变更
157
158**访问级别**
159
160公开接口
161
162**变更原因**
163
164用户对于Image组件fillColor属性设置异常值时，使用默认值
165
166**变更影响**
167
168该变更为非兼容性变更。
169
170变更前，当开发者对Image组件的fillColor属性设置为异常值时，采用不操作处理。
171
172变更后，当开发者对Image组件的fillColor属性设置为异常值时，采用系统默认颜色来处理。
173
174**API Level**
175
17611
177
178**变更发生版本**
179
180从OpenHarmony SDK 4.1.5.5 开始。
181
182**变更的接口/组件**
183
184受影响的组件有：Image。
185
186**适配指导**
187
188默认行为变更，不涉及适配。
189
190
191## cl.Arkui.6 Datapanel组件的默认阴影模糊半径变更
192
193**访问级别**
194
195公开接口
196
197**变更原因**
198
199当前Datapanel组件的默认阴影模糊半径为5vp、UX检视时发现模糊半径过小，因此依照UX规范增加阴影模糊半径到20vp。
200
201**变更影响**
202
203该变更为兼容性变更，改变了组件默认情况下的阴影模糊半径，提升了组件的默认显示效果。
204
205**API Level**
206
20710
208
209**变更发生版本**
210
211从OpenHarmony SDK 4.1.5.5开始。
212
213**变更的接口/组件**
214
215API 11前，Datapanel组件的默认阴影模糊半径为5vp。
216
217![dataPanel](figures/oldDataPanel.png)
218
219API 11及以后，Datapanel组件的默认阴影模糊半径为20vp。
220
221![dataPanel](figures/newDataPanel.png)
222
223**适配指导**
224
225默认阴影效果变更，不涉及适配。
226
227## cl.Arkui.7 Dialog组件内容的默认对齐方式变更
228
229**访问级别**
230
231公开接口
232
233**变更原因**
234
235当前Dialog组件内容的默认对齐方式不符合UX规范，因此依照UX规范对对齐方式做出变更。
236
237**变更影响**
238
239该变更为兼容性变更，改变了Dialog无标题且内容多行情况下的对齐方式，提升了组件的默认显示效果。
240
241**API Level**
242
2437
244
245**变更发生版本**
246
247从OpenHarmony SDK 4.1.5.5开始。
248
249**变更的接口/组件**
250
251API 11前，默认Dialog的内容区对齐方式在无标题情况下为居中对齐。
252
253API 11及以后，默认Dialog的内容区对齐方式在无标题且内容只有一行的情况下为居中对齐，默认Dialog的内容区对齐方式在无标题且内容有多行的情况下为左对齐。
254
255**适配指导**
256
257默认对齐方式变更，不涉及适配。
258
259## cl.Arkui.8 弹窗类组件背板的默认视觉效果变更为模糊材质
260
261**访问级别**
262
263公开接口
264
265**变更原因**
266
267增强视觉效果。
268
269**变更影响**
270
271该变更为兼容性变更。在统一渲染模式下，弹窗类组件背板的默认视觉效果变更为模糊材质。
272
273如果开发者需要更换模糊材质及背景色，可以通过添加backgroundColor及backgroundBlurStyle参数修改。
274
275**API Level**
276
27711
278
279**变更发生版本**
280
281从OpenHarmony SDK 4.1.5.5开始。
282
283**变更的接口/组件**
284
285涉及到警告弹窗（AlertDialog）、列表选择弹窗（ActionSheet）、日历选择器弹窗（CalendarPickerDialog）、日期滑动选择器弹窗（DatePickerDialog）、时间滑动选择器弹窗（TimePickerDialog）、文本滑动选择器弹窗（TextPickerDialog）、promptAction中showDialog方法
286
287API 11前，弹窗类组件背板显示为主题色。
288
289API 11及以后，弹窗类组件背板显示为模糊材质。
290
291**适配指导**
292
293去除模糊材质示例代码：
294```ts
295@Entry
296@Component
297struct AlertDialogExample {
298  build() {
299    Column({ space: 5 }) {
300      Button('one button dialog')
301        .onClick(() => {
302          AlertDialog.show({
303            message:"alertDialog",
304          })
305        }).backgroundColor(0x317aff)
306    }.width('100%').margin({ top: 5 })
307  }
308}
309```
310将
311```ts
312AlertDialog.show({
313  message:"alertDialog",
314})
315```
316替换为
317```ts
318AlertDialog.show({
319  message:"alertDialog",
320  backgroundColor:Color.White,
321  backgroundBlurStyle:BlurStyle.NONE
322})
323```
324即手动设置背景色与背景模糊材质枚举值。
325
326## cl.Arkui.9 Dialog组件内容区Text默认分词方式变更
327
328**访问级别**
329
330公开接口
331
332**变更原因**
333
334当前Dialog组件内容的默认分词方式不符合UX规范，因此依照UX规范对分词方式做出变更。
335
336**变更影响**
337
338该变更为兼容性变更，改变了Dialog内容区Text默认分词方式，提升了组件的默认显示效果。
339
340**API Level**
341
3427
343
344**变更发生版本**
345
346从OpenHarmony SDK 4.1.5.5开始。
347
348**变更的接口/组件**
349
350API 11前，默认Dialog的内容区分词方式为BREAK_WORD。
351
352API 11及以后，默认Dialog的内容区分词方式为BREAK_ALL。
353
354关于BREAK_WORD和BREAK_ALL的区别，详见[WordBreak](../../../application-dev/reference/arkui-ts/ts-appendix-enums.md#wordbreak11)
355
356**适配指导**
357
358默认分词方式变更，不涉及适配。
359
360## cl.arkui.10  opacity属性非法值设置变更
361
362**访问级别**
363
364公开接口
365
366**变更原因**
367
368opacity属性设置小于0的非法值需要按照完全透明来处理。
369
370**变更影响**
371
372该变更为非兼容性变更。
373
374变更前，opacity属性设置小于0的非法值时效果完全不透明。
375
376变更后，opacity属性设置小于0的非法值时效果完全透明。
377
378**API Level**
379
3807
381
382**变更发生版本**
383
384从OpenHarmony SDK 4.1.5.5 开始。
385
386**变更的接口/组件**
387
388受影响的属性：opacity。
389
390**适配指导**
391
392默认行为变更，不涉及适配。
393
394## cl.Arkui.11 ListItem、GridItem的selectable属性异常值处理逻辑变更
395
396**访问级别**
397
398公开接口
399
400**变更原因**
401
402用户对于ListItem和GridItem组件selectable属性设置异常值时，使用默认值。
403
404**变更影响**
405
406该变更为非兼容性变更。
407
408变更前，当开发者对ListItem和GridItem组件selectable属性设置异常值时，采用false值处理。
409
410变更后，当开发者对ListItem和GridItem组件selectable属性设置异常值时，采用默认值true处理。
411
412**API Level**
413
4148
415
416**变更发生版本**
417
418从OpenHarmony SDK 4.1.5.5开始。
419
420**变更的接口/组件**
421
422涉及到ListItem和GridItem组件的selectable属性。
423
424API 11前，当开发者对ListItem和GridItem组件selectable属性设置异常值时，采用false值处理。
425
426API 11及以后，当开发者对ListItem和GridItem组件selectable属性设置异常值时，采用默认值true处理。
427
428**适配指导**
429
430默认行为变更，不涉及适配。
431
432## cl.arkui.12  Text组件fontSize属性非法值设置变更
433
434**访问级别**
435
436公开接口
437
438**变更原因**
439
440"5abc"这类数字拼接字符串被定义为非法值，不可以解析使用数字部分处理为5fp字号。
441
442**变更影响**
443
444该变更为非兼容性变更。
445
446变更前，fontSize属性设置"5abc"非法值时显示字号为5fp。
447
448变更后，fontSize属性设置"5abc"非法值时显示默认字号16fp。
449
450**API Level**
451
45211
453
454**变更发生版本**
455
456从OpenHarmony SDK 4.1.5.5 开始。
457
458**变更的接口/组件**
459
460受影响的组件和接口：Text组件fontSize属性。
461
462**适配指导**
463
464默认行为变更，不涉及适配。
465
466## cl.arkui.13  点击事件规格变更
467
468**访问级别**
469
470公开接口
471
472**变更原因**
473
474点击手势需响应在手指落下时，组件热区范围内的所有点击事件。去掉之前点击过程中手指移动不能超过20px的临时规格。
475
476**变更影响**
477
478该变更为非兼容性变更。
479
480变更前，点击过程中手指移动不能超过20px，若手指移动超过20px，则点击手势识别失败。
481
482变更后，点击手势识别器在手指落下时收集响应热区并缓存，若手指移动/抬起过程中超出缓存热区，则点击手势识别失败。
483
484**API Level**
485
4867
487
488**变更发生版本**
489
490从OpenHarmony SDK 4.1.5.5 开始。
491
492**变更的接口/组件**
493
494点击手势：TapGesture
495
496**适配指导**
497
498该变更会导致若点击手势和拖动手势放入同一个并行手势组，会出现拖动手势和点击手势同时响应的情况
499
500适配措施：
5011.应用业务审视是否必须将点击手势和拖动手势放入同一个并行手势组内（大部分之前没有冲突的情况，是因为点击事件的20px的移动限制，自动消减了冲突），如果不是必须则可以不挂到同一个手势组
502修改前：
503```ts
504  .parallelGesture(GestureGroup(GestureMode.Parallel,
505    TapGesture({count: 1})
506      .onAction((event?: GestureEvent)=> {
507        if (event) {
508          console.info("Tapgesture")
509        }
510      }),
511    PanGesture({fingers: 1})
512      .onActionStart((event?: GestureEvent)=>{
513        console.info("Pan start")
514      })
515      .onActionUpdate((event?: GestureEvent)=>{
516        console.info("Pan update")
517      })
518      .onActionEnd((event?: GestureEvent)=>{
519        console.info("Pan end")
520      })
521  ))
522```
523修改后：
524```ts
525  .parallelGesture(GestureGroup(GestureMode.Parallel,
526    PanGesture({fingers: 1})
527      .onActionStart((event?: GestureEvent)=>{
528        console.info("Pan start")
529      })
530      .onActionUpdate((event?: GestureEvent)=>{
531        console.info("Pan update")
532      })
533      .onActionEnd((event?: GestureEvent)=>{
534        console.info("Pan end")
535      })
536  ))
537  .gesture(
538    TapGesture({count: 1})
539      .onAction((event?: GestureEvent)=> {
540        if (event) {
541          console.info("Tapgesture")
542        }
543    })
544  )
545```
5462.若点击必须与滑动放到同一个平行手势组下，则可以通过手势自定义判定能力，通过自行设置的手指移动距离判定点击手势失败：
547示例代码：
548```ts
549  .gesture(
550    TapGesture({count: 1})
551      .onAction((event?: GestureEvent)=> {
552        if (event) {
553          console.log("Tapgesture")
554        }
555      })
556  )
557  .onTouch((event?: TouchEvent)=> {
558    if (event) {
559      if (event.type === TouchType.Down) {
560        this.downX = event.touches[0].windowX
561        this.downY = event.touches[0].windowY
562      }
563    }
564  })
565  .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent)=> {
566    if (gestureInfo.type == GestureControl.GestureType.TAP_GESTURE) {
567      let xGap = event.fingerList[0].globalX - this.downX
568      if (xGap > 5) {
569        return GestureJudgeResult.REJECT
570      }
571      let yGap = event.fingerList[0].globalY - this.downY
572      if (yGap > 5) {
573        return GestureJudgeResult.REJECT
574      }
575      return GestureJudgeResult.CONTINUE
576    } else {
577      return GestureJudgeResult.CONTINUE
578    }
579  })
580```
5813.若点击必须与滑动放到同一个平行手势组下，则可以通过手势自定义判定能力，通过设置组件flag进行手势互斥判断：
582```ts
583@Entry
584@Component
585struct Index {
586  @State message: string = '';
587  private hasPanActive = false;
588  build() {
589    Column() {
590      Row({ space: 20 }) {
591        Text(this.message).width(100).height(40).backgroundColor(Color.Pink)
592      }.margin(20)
593    }
594    .width('100%')
595    .height(200)
596    .borderWidth(2)
597    .parallelGesture(GestureGroup(GestureMode.Parallel,
598      TapGesture({count: 1})
599        .onAction((event?: GestureEvent)=> {
600          if (event) {
601            console.info("Tapgesture")
602          }
603        }).tag("Single-Finger-Click"),
604      PanGesture({fingers: 1})
605        .onActionStart((event?: GestureEvent)=>{
606          console.info("Pan start")
607        })
608        .onActionUpdate((event?: GestureEvent)=>{
609          console.info("Pan update")
610        })
611        .onActionEnd((event?: GestureEvent)=>{
612          console.info("Pan end")
613        }).tag("Single-Finger-Pan")
614    ))
615    .onGestureJudgeBegin((gestureInfo: GestureInfo, event: BaseGestureEvent) => {
616      // 若滑动手势被触发，则将flag置为true
617      if (gestureInfo.tag === "Single-Finger-Pan") {
618        this.hasPanActive = true
619      }
620      // 若点击手势被触发，且flag为true，则说明再此之前滑动手势已被触发，组件重置flag并拒绝点击手势。
621      if (gestureInfo.tag === "Single-Finger-Click" && this.hasPanActive) {
622        this.hasPanActive = false;
623        return GestureJudgeResult.REJECT
624      }
625      return GestureJudgeResult.CONTINUE
626    })
627  }
628}
629```
630## cl.arkui.14  menuItem默认高度规格变更
631
632**访问级别**
633
634其他
635
636**变更原因**
637
638UX默认规格变更
639
640**变更影响**
641
642该变更为兼容性变更。
643
644变更前，menuItem只传入图标高度为24vp，menuItem传入为空时高度为0。
645
646变更后，menuItem只传入图标高度为48vp，menuItem传入为空时高度也为48vp。
647
648**API Level**
649
65011
651
652**变更发生版本**
653
654从OpenHarmony SDK 4.1.5.5 开始。
655
656**变更的接口/组件**
657
658受影响的组件：MenuItem、Menu、MenuItemGroup。
659
660**适配指导**
661
662默认高度规格变更，如果与应用UX高度规格不符，可以自定义设置menuItem的height。
663
664## cl.arkui.15  Swiper组件的Indicator属性参数设置逻辑变更
665
666**访问级别**
667
668其他
669
670**变更原因**
671
672Indicator属性的left、top、right、bottom等参数设置为0时不生效，设置成异常值时未按默认值0vp处理。
673
674**变更影响**
675
676该变更为非兼容性变更。
677
678变更前，Indicator属性的left、top、right、bottom等参数设置为0或异常值时，导航点位于Swiper组件底部居中。
679
680变更后，Indicator属性的left、top、right、bottom等参数设置为0或异常值时，导航点位于Swiper组件对应边界的位置，即按默认值0vp处理。
681
682**API Level**
683
68410
685
686**变更发生版本**
687
688从OpenHarmony SDK 4.1.5.5 开始。
689
690**变更的接口/组件**
691
692受影响的组件：Tabs。
693
694**适配指导**
695
696变更后，Indicator属性的left、top、right、bottom等参数设置为正常值（包含0）时按设置的值处理，设置成异常值按默认值0vp处理，不涉及适配。