1# ArkUI子系统Changelog
2
3## cl.arkui.1 Navigation分割线触摸直接响应
4
5**访问级别**
6
7公开接口
8
9**变更原因**
10
11基于UX人因规格,区隔拖拽和滑动体验,针对分割线的拖拽行为进行时延显示调整。
12
13**变更影响**
14
15该变更为不兼容变更。
16
17变更前:手指需长按500ms,Navigation的分割线才可响应滑动。
18
19变更后:手指触摸Navigation的分割线可立即响应滑动。
20
21**起始API Level**
22
239
24
25**变更发生版本**
26
27从OpenHarmony SDK 5.0.0.33开始。
28
29**适配指导**
30
31默认行为变更,无需适配。
32
33## cl.arkui.2 RichEditor的lineHeight、letterSpacing、lineSpacing属性返回值单位变更
34
35**访问级别**
36
37公开接口
38
39**变更原因**
40
41文本字体相关属性的返回值单位应默认使用fp类型。
42
43**变更影响**
44
45该变更为不兼容变更。
46
47API version 11及以前:lineHeight、letterSpacing、 lineSpacing属性的返回值单位是vp。
48
49API version 12及以后:lineHeight、letterSpacing、 lineSpacing属性的返回值单位从vp变更为fp,若开发者原来将返回值按vp单位处理,变更后该处理逻辑会导致数据错误。
50
51**起始 API Level**
52
5310
54
55**变更发生版本**
56
57从OpenHarmony SDK 5.0.0.33 版本开始。
58
59**变更的接口/组件**
60
61RichEditor组件,lineHeight、letterSpacing、lineSpacing属性。
62
63**适配指导**
64
65默认效果变更,开发者需通过[像素单位转换接口](../../../application-dev/reference/apis-arkui/arkui-ts/ts-pixel-units.md#像素单位转换),对返回值进行正确处理。
66
67## cl.arkui.3 RichEditor的fontSize属性的返回值单位变更
68
69**访问级别**
70
71公开接口
72
73**变更原因**
74
75文本字体相关属性的返回值单位应默认使用fp类型。
76
77**变更影响**
78
79该变更为不兼容变更。
80
81API version 11及以前:fontSize属性的返回值单位是vp。
82
83API version 12及以后:fontSize属性的返回值单位从vp变更为fp,若开发者原来将返回值按vp单位处理,变更后该处理逻辑会导致数据错误。
84
85**起始 API Level**
86
8710
88
89**变更发生版本**
90
91从OpenHarmony SDK 5.0.0.33 版本开始。
92
93**变更的接口/组件**
94
95RichEditor组件,fontSize属性。
96
97**适配指导**
98
99默认效果变更,开发者需通过[像素单位转换接口](../../../application-dev/reference/apis-arkui/arkui-ts/ts-pixel-units.md#像素单位转换),对返回值进行正确处理。
100
101## cl.arkui.4 BindContextMenu上下文菜单内容可滚动时快滑不再关闭菜单
102
103**访问级别**
104
105公开接口
106
107**变更原因**
108
109BindContextMenu上下文菜单选项过多会出现滚动条,此时手指快速滑动菜单选项,该行为不会上下滚动菜单选项,而是自动关闭菜单,影响用户体验。
110
111**变更影响**
112
113该变更为不兼容变更。
114
115变更前:上下文菜单无论是否有滚动条时,手指快速滑动菜单选项均会自动关闭菜单。
116
117变更后:上下文菜单选项没有滚动条时,手指快速滑动菜单选项会自动关闭菜单;上下文菜单选项过多出现滚动条时,手指快速滑动菜单选项只会上下滚动菜单选项,不再主动关闭菜单。
118
119![bindContextMenu_scroll](figures/bindContextMenu_scroll.png)
120
121**起始API Level**
122
1238
124
125**变更发生版本**
126
127从OpenHarmony SDK 5.0.0.33开始。
128
129**变更的接口/组件**
130
131Menu组件的BindContextMenu接口
132
133**适配指导**
134
135默认行为变更,无需适配。
136
137## cl.arkui.5 Repeat接口RepeatItem参数index可选改为必选
138
139**访问级别**
140
141公开接口
142
143**变更原因**
144
145为了提升Repeat使用的易用性,在该组件的实现上,进行了优化处理。对其接口RepeatItem所需要的index参数从非必填优化为了必填,这样开发者在使用index参数的时候,无需对index参数进行判空处理。
146
147**变更影响**
148
149该变更为兼容性变更。兼容应用已写代码,无需应用修改代码。
150
151**起始API Level**
152
15312
154
155**变更发生版本**
156
157从OpenHarmony SDK 5.0.0.33开始。
158
159**变更的接口/组件**
160
161Repeat组件,RepeatItem接口的index参数。
162
163**适配指导**
164
165- 正常使用时,适配已开发的代码,新开发的代码无需对index做判空处理。
166
167变更前:
168
169```ts
170@Entry
171@ComponentV2
172struct RepeatTest {
173  @Local arr: Array<number> = [0, 1, 2, 3]
174
175  build() {
176    List({ space: 3 }) {
177      Repeat(this.arr)
178        .virtualScroll()
179        .key((item) => item.toString())
180        .each((repeatItem) => {
181          ListItem() {
182            Text(`${repeatItem.index! + 1}. Item ${repeatItem.item}`) // repeatItem.index需做判空处理
183              .height(50).backgroundColor(Color.Blue)
184          }.backgroundColor(Color.Green)
185        })
186
187    }.height(200).backgroundColor(Color.Red)
188  }
189}
190```
191
192变更后:
193
194```ts
195@Entry
196@ComponentV2
197struct RepeatTest {
198  @Local arr: Array<number> = [0, 1, 2, 3]
199
200  build() {
201    List({ space: 3 }) {
202      Repeat(this.arr)
203        .virtualScroll()
204        .key((item) => item.toString())
205        .each((repeatItem) => {
206          ListItem() {
207            Text(`${repeatItem.index + 1}. Item ${repeatItem.item}`) // repeatItem.index可不做判空处理
208              .height(50).backgroundColor(Color.Blue)
209          }.backgroundColor(Color.Green)
210        })
211
212    }.height(200).backgroundColor(Color.Red)
213  }
214}
215```
216- 非正常使用时
217
218变更前:
219
220```ts
221class RepeatClass implements RepeatItem<string> {
222    item: string = "hello" //不写index属性不会报错
223}
224```
225
226变更后:
227
228```ts
229class RepeatClass implements RepeatItem<string> {
230    item: string = "hello";
231    index: number = 0 //不写index属性会报错
232}
233```
234
235## cl.arkui.6 Search/TextInput/TextArea onchange回调新增可选参数预上屏文本
236
237**访问级别**
238
239公开接口
240
241**变更原因**
242
243在输入过程中,新增预上屏行为,需要将当前已提交上屏的文本和预上屏信息实时返回给开发者。
244
245**变更影响**
246
247该变更为不兼容变更。
248
249变更前:
250
251  1.onChange回调在用户全部输入完成,提交正式上屏时触发。
252
253  2.onChange唯一参数是已正式提交上屏的文本。
254
255变更后:
256
257  1.onChange回调在用户输入过程中,随预上屏内容变更触发。
258
259  2.onChange首个参数仍是已正式提交上屏的文本。新增可选参数PreviewText,PreviewText包含预上屏内容的起始位置和文本。
260
261**起始API Level**
262
2637
264
265**变更发生版本**
266
267从OpenHarmony SDK 5.0.0.33开始。
268
269**变更的接口/组件**
270
271Search/TextInput/TextArea组件的onChange回调事件参数。
272
273**适配指导**
274
275适配前:
276
277默认开启预上屏功能。回调唯一参数为已正式上屏文本;回调时机为输入过程中,每一次预上屏内容变更时触发。
278
279```ts
280@Entry
281@Component
282struct SearchExample {
283  @State text: string = 'Search支持文本预上屏前...'
284
285  build() {
286    Column() {
287      Search({
288        value: this.text,
289        placeholder: 'input your word...',
290      })
291        .placeholderFont({ size: 16, weight: 400 })
292        .width(336)
293        .height(56)
294        // onChange回调唯一参数为已正式上屏文本;回调时机为输入过程中,每一次预上屏内容变更时触发
295        .onChange((value: string) => {
296          this.text = value
297          console.log("===get onchange ===")
298          console.log("body text value = " + value)
299        })
300    }
301    .width("90%")
302    .margin("5%")
303  }
304}
305```
306
307适配后:
308
309默认开启预上屏功能,需要适配在输入过程中,回调返回的首个参数为空字符串或者多次回调的首个参数为重复内容的场景;需要适配文本框内所有文本长度变更为含预上屏内容的总长度。
310
311示例代码列举了预上屏状态下,用来适配各问题场景所需要的信息。
312
313```ts
314@Entry
315@Component
316struct SearchExample {
317  @State text: string = 'Search回调预上屏信息...'
318
319  build() {
320    Column() {
321      Search({
322        value: this.text,
323        placeholder: 'input your word...',
324      })
325        .placeholderFont({ size: 16, weight: 400 })
326        .width(336)
327        .height(56)
328        // onChange回调首个参数为已经存在的正式上屏文本
329        // 第二个参数为可选参数,返回的是预上屏内容的信息
330        .onChange((value: string, previewText: PreviewText) => {
331          this.text = value
332          console.log("===get onchange and get previewText info===")
333          let bodyTextValue = value
334          console.log("body text value = " + bodyTextValue)
335          let previewTextValue = previewText.value
336          console.log("previewText value = " + previewTextValue)
337          let previewTextStart = previewText.offset
338          let previewTextEnd = previewText.offset + previewTextValue.length
339          console.log("previewText index range in [ " + previewTextStart + ", " + previewTextEnd + " ]")
340          let isPreviewTextWorking = previewTextValue != "";
341          console.log("now is inputing at previewText working= " + isPreviewTextWorking)
342          let wholeTextValue = value + previewTextValue
343          console.log("whole text value = " + wholeTextValue)
344        })
345    }
346    .width("90%")
347    .margin("5%")
348  }
349}
350```
351
352在不需要预上屏功能场景时,可使用enablePreviewText属性关闭预上屏功能。
353
354```ts
355@Entry
356@Component
357struct SearchExample {
358  @State text: string = 'Search支持关闭文本预上屏...'
359
360  build() {
361    Column() {
362      Search({
363        value: this.text,
364        placeholder: 'input your word...',
365      })
366        .placeholderFont({ size: 16, weight: 400 })
367        .width(336)
368        .height(56)
369        .enablePreviewText(false) // 使用该属性,可以关闭预上屏功能,使回调内容与回调时机与变更前保持一致
370        .onChange((value: string) => {
371          this.text = value
372          console.log("===get onchange ===")
373          console.log("body text value = " + value)
374        })
375    }
376    .width("90%")
377    .margin("5%")
378  }
379}
380```
381
382## cl.arkui.7 命令式渲染节点RenderNode属性clipToFrame行为变更
383
384**访问级别**
385
386公开接口
387
388**变更原因**
389
390原先命令式渲染节点RenderNode的clipToFrame设为false不生效,现设置为false,超出节点大小范围的子节点内容不会被剪裁。
391
392**变更影响**
393
394该变更为不兼容变更。
395
396变更前:RenderNode的clipToFrame设为false不生效,超出节点大小范围的子节点内容会被剪裁。开发者在未显式设置clipToFrame属性的情况下,clipToFrame默认值为false。
397
398变更后:RenderNode的clipToFrame设为false时,超出节点大小范围的子节点内容不会被剪裁。为保证变更前后clipToFrame的默认行为一致,开发者在未显式设置clipToFrame属性的情况下,clipToFrame默认值变更为true。
399
400![clipToFrame](./figures/clipToFrame.png)
401
402**起始 API Level**
403
40411
405
406**变更发生版本**
407
408从OpenHarmony SDK 5.0.0.33开始。
409
410**变更的接口/组件**
411
412命令式渲染节点RenderNode的clipToFrame接口
413
414**适配指导**
415
416若开发者在设置clipToFrame为false的情况下,仍想保持之前的“超出节点大小范围的内容会被剪裁”的行为,可通过设置clipToFrame为true来实现。
417
418```ts
419import {  RenderNode, FrameNode, NodeController } from '@kit.ArkUI';
420
421const renderNode = new RenderNode();
422renderNode.frame = { x: 50, y: 50, width: 200, height: 200 };
423renderNode.backgroundColor = 0xffd5d5d5;
424renderNode.clipToFrame = true;  // 设置clipToFrame为true,对超出节点大小的内容进行剪裁。
425
426const childNode = new RenderNode();
427childNode.frame = { x: 10, y: 10, width: 250, height: 100 };
428childNode.backgroundColor = 0xff004aaf;
429renderNode.appendChild(childNode);
430
431class MyNodeController extends NodeController {
432  private rootNode: FrameNode | null = null;
433
434  makeNode(uiContext: UIContext): FrameNode | null {
435    this.rootNode = new FrameNode(uiContext);
436
437    const rootRenderNode = this.rootNode.getRenderNode();
438    if (rootRenderNode !== null) {
439      rootRenderNode.appendChild(renderNode);
440    }
441
442    return this.rootNode;
443  }
444}
445
446@Entry
447@Component
448struct Index {
449  private myNodeController: MyNodeController = new MyNodeController();
450
451  build() {
452    Row() {
453      NodeContainer(this.myNodeController)
454    }
455  }
456}
457```
458