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 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 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