1# ArkUI子系统变更说明 2 3## cl.arkui.1 TextInput组件默认样式变更 4 5**访问级别** 6 7公开接口 8 9**变更原因** 10 11默认样式变更。 12 13**变更影响** 14 15该变更为非兼容性变更。 16 17变更前：下划线模式输入框设置borderRadius未生效，还是默认样式radius为0。下划线模式输入框左右padding为12vp。非下划线模式输入框默认高度为48vp。 18 19 20 21变更后：下划线模式输入框设置borderRadius正常生效，不设置则显示默认样式radius为0。下划线模式输入框左右padding为0vp。非下划线模式输入框默认高度为40vp。 22 23 24 25示例： 26 27```ts 28@Entry 29@Component 30struct TextInputExample { 31 @State Text: string = '' 32 build() { 33 Column({ space: 20 }) { 34 Text(`下划线模式`) 35 .width('95%') 36 // 下划线模式 37 TextInput({ placeholder: 'underline style' }) 38 .showUnderline(true) 39 .backgroundColor(Color.Pink) 40 .width(360) 41 .borderRadius(10) 42 Text(`非下划线模式`) 43 .width('95%') 44 TextInput({ placeholder: '请输入用户名', text: this.Text }) 45 .showUnderline(false) 46 .width(360) 47 .borderRadius(10) 48 49 }.width('100%') 50 } 51} 52``` 53 54**起始API Level** 55 5610 57 58**变更发生版本** 59 60从OpenHarmony SDK 5.0.0.22开始。 61 62**变更的接口/组件** 63 64TextInput组件默认样式变更。 65 66**适配指导** 67 68默认效果变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则应自定义修改效果控制变量以达到预期。 69 70## cl.arkui.2 Toast弹窗接口更改消息框背景色、字色，以及Toast的最大宽度及高度，界面语超长逐级缩小字号至12fp，超出截断。 71 72**访问级别** 73 74公开接口 75 76**变更原因** 77 78API version 12及之后更改Toast UX的显示样式。 79 80**变更影响** 81 82该变更为非兼容性变更。 83 84- API version 11及之前，Toast弹窗背景色为深黑色、字色为白色，最大高度没有限制，界面语超长没有截断。<br/> 85 86- API version 12及之后，Toast弹窗在常规亮色显示风格下toast透明模糊背景、字色黑色，暗色显示风格下透明模糊背景、字色白色，Toast的最大高度 =（屏幕高度-信号栏-导航条）*0.65，最大宽度：基于屏幕宽度-2侧margin，根据容器自适应，最大到400vp不再变化。界面语超长逐级缩小字号至12fp，超出截断。<br/> 87 88- API version 11及之前对比API version 12及之后属性变更如下 89 90 | 属性名 | 变更前 | 变更后 | 91|---------|---------|---------| 92| 背景色 | bg_color | COMPONENT_ULTRA_THICK | 93| 圆角 | toast_border_radius | corner_radius_level9 | 94| padding-left | toast_padding_horizontal | padding_level8 | 95| padding-top | toast_padding_vertical | padding_level4 | 96| padding-right | toast_padding_horizontal | padding_level8 | 97| padding-bottom | toast_padding_vertical | padding_level4 | 98| 字体大小 | text_font_size | Body_M | 99| 字体颜色 | text_color | font_primary | 100| 字重 | toast_text_font_weight | font_weight_regular | 101 102**示例：** 103如下图所示为变更前后效果对比： 104 105 | 变更前 | 变更后 | 106|---------|---------| 107|  |  | 108 109**API Level** 110 11112 112 113**变更发生版本** 114 115从OpenHarmony SDK 5.0.0.22 版本开始。 116 117**变更的接口/组件** 118 119Toast弹窗接口 120 121**适配指导** 122 123UX默认行为变更，无需适配。 124 125## cl.arkui.3 Text组件clip通用属性默认值变更 126 127**访问级别** 128 129公开接口 130 131**变更原因** 132 133默认值false符合更多应用场景。 134 135**变更影响** 136 137该变更为非兼容性变更。 138 139API version 12 变更前：Text组件clip通用属性默认值为true, 超出组件区域内容会被截断不显示。 140 141 142 143API version 12 变更后：Text组件clip通用属性默认值为false, 超出组件区域内容不会被截断全部显示。 144 145 146 147示例： 148 149```ts 150@Entry 151@Component 152struct TextClipExample { 153 build() { 154 Column({ space: 20 }) { 155 Text('This is set wordBreak to WordBreak text Taumatawhakatangihangakoauauotamateaturipukakapikimaungahoronukupokaiwhenuakitanatahu.') 156 .fontSize(12) 157 .border({ width: 1 }) 158 .wordBreak(WordBreak.NORMAL) 159 .lineHeight(20) 160 .maxLines(2) 161 }.height(300).width(335).padding({ left: 35, right: 35, top: 35 }) 162 } 163} 164``` 165 166**起始API Level** 167 1687 169 170**变更发生版本** 171 172从OpenHarmony SDK 5.0.0.22开始。 173 174**变更的接口/组件** 175 176Text组件clip通用属性默认值变更。 177 178**适配指导** 179 180默认效果变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则应自定义修改效果控制变量以达到预期。 181 182## cl.arkui.4 TextInput,TextArea,Search组件caretPosition接口异常值处理变更 183 184**访问级别** 185 186公开接口 187 188**变更原因** 189 190优化Search、TextInput、TextArea组件设置光标时异常值处理逻辑。 191 192**变更影响** 193 194该变更为非兼容性变更。 195 196API Version 11 以及之前的版本：TextInput.caretPosition()的入参是负数、undefined时，接口不生效。 197TextInputController.caretPosition()、TextAreaController.caretPosition()、SearchController.caretPosition()的入参是负数时， 198接口生效，移动光标到0的位置并记录光标位置是负数。 199 200API Version 12 变更后：TextInput.caretPosition()的入参是负数、undefined时，当作0处理，接口生效。 201TextInputController.caretPosition()、TextAreaController.caretPosition()、SearchController.caretPosition()的入参是负数时， 202当作0处理，接口生效，移动光标到0的位置并记录光标位置是0。 203 204**起始 API Level** 205 2068 207 208**变更发生版本** 209 210从OpenHarmony SDK 5.0.0.22开始。 211 212**适配指导** 213 214光标位置的视觉效果不会发生变化。 215如果此前设置光标位置的参数是负数、undefined，并且需要光标位置不发生变化，需要修改业务代码，输入合法数值。 216 217## cl.arkui.5 ListItem横划UX行为变更。 218 219**访问级别** 220 221公开接口 222 223**变更原因** 224 225API version 12及之后更改ListItem横划UX行为。 226 227**变更影响** 228 229该变更为非兼容性变更。 230 231- API version 11及之前，ListItem横划展开划出菜单以后，点击List组件非划出菜单区域，ListItem划出菜单不会自动收起，点击位置的组件可以响应点击事件。<br/> 232 233- API version 12及之后，ListItem横划展开划出菜单以后，点击List组件非划出菜单区域，ListItem划出菜单会自动收起，点击位置的组件不响应点击事件。<br/> 234 235**示例：** 236如下图所示为变更前后效果对比： 237 238 | 变更前 | 变更后 | 239|---------|---------| 240|  |  | 241 242**API Level** 243 24412 245 246**变更发生版本** 247 248从OpenHarmony SDK 5.0.0.22 版本开始。 249 250**变更的接口/组件** 251 252ListItem组件 253 254**适配指导** 255 256UX默认行为变更，无需适配。 257 258## cl.arkui.6 相对布局对Visibility.None的处理规则变更 259 260**访问级别** 261 262公开接口 263 264**变更原因** 265 266UX规格增强 267 268**变更影响** 269 270该变更为非兼容性变更。 271 272变更前：组件A的任一锚点的Visibility为None，组件A不被Measure。 273 274变更后：组件A的任一锚点的Visibility为None，组件A依旧被Measure，锚点组件的位置不变，宽高均视为0。 275 276**API Level** 277 278该特性版本为API 7,变更版本为API 12。 279 280**变更发生版本** 281 282从OpenHarmony SDK 5.0.0.23开始。 283 284**适配指导** 285 286如果需要组件A在锚点组件的Visibility设置为None之后不被Measure，可将组件A的Visibility设置为Hidden或者None。 287 288## cl.arkui.7 C-API 获取Native模块接口集合的接口变更 289 290**访问级别** 291 292公开接口 293 294**变更原因** 295 296兼容性增强 297 298**变更影响** 299 300该变更为非兼容性变更。 301 302变更前：用户可通过 OH_ArkUI_GetNativeAPI 接口获取Native模块接口集合。 303 304变更后：用户需通过 OH_ArkUI_GetModuleInterface 接口或者 OH_ArkUI_QueryModuleInterfaceByName 接口获取Native模块接口集合。 305 306**起始API level** 307 308该特性版本和变更版本均为API 12。 309 310**变更发生版本** 311 312从OpenHarmony SDK 5.0.0.22开始。 313 314**适配指导** 315 316用户可参考如下方式调用新的API 获取Native模块接口集合 317 318方式1： 319 320``` 321auto nodeAPI = reinterpret_cast<ArkUI_NativeNodeAPI_1*>( 322 OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1")); 323``` 324 325方式2： 326 327``` 328ArkUI_NativeNodeAPI_1* nodeAPI = nullptr; 329OH_ArkUI_GetModuleInterface(ARKUI_NATIVE_NODE, ArkUI_NativeNodeAPI_1, nodeAPI); 330``` 331 332## cl.arkui.8 C-API 事件注册接口变更 333 334**访问级别** 335 336公开接口 337 338**变更原因** 339 340兼容性增强 341 342**变更影响** 343 344该变更为非兼容性变更。 345 346变更前： 347 348* 用户可通过 nodeAPI->registerNodeEvent(nodePtr, eventType, eventId) 方式为指定组件绑定指定事件，入参为三个，依次为待绑定事件的组件节点指针、待绑定的事件类型、待绑定事件的ID； 349 350* 事件响应后，用户可在回调中获取到指向事件回调数据，类型为ArkUI_NodeEvent 的指针，并可以直接访问指针中的结构体和数据，如下所示： 351 352代码示例： 353 354``` 355nodeAPI->registerNodeEvent(button, NODE_ON_CLICK, 1); // 1 为注册的事件ID 356auto onclick = [](ArkUI_NodeEvent *event) { 357 if (event->eventId == 1) { 358 auto offsetX = event->componentEvent.data[0].f32; // 获取点击位置相对于被点击组件左上角的X坐标 359 } 360}; 361nodeAPI->registerNodeEventReceiver(onclick); // 监听事件回调，当触发button组件的点击事件时会执行用户定义的onclick方法 362``` 363 364变更后： 365 366* 用户注册事件的接口新增了一位自定义参数的指针，形如 nodeAPI->registerNodeEvent(nodePtr, eventType, eventId，userData)。 367 368* 事件响应后，用户可在回调中获取到指向事件回调数据，类型为ArkUI_NodeEvent 的指针，但不再暴露指针的具体结构体，用户需通过指定的函数方法获取指定的参数，如下所示： 369 370代码示例： 371 372``` 373nodeAPI->registerNodeEvent(button, NODE_ON_CLICK, 1, nullptr); // 暂无需要传入的自定义数据，可用nullptr代替 374auto onclick = [](ArkUI_NodeEvent *event) { 375 if (OH_ArkUI_NodeEvent_GetTargetId(event) == 1) { // 使用 OH_ArkUI_NodeEvent_GetTargetId 方法获取事件ID 376 auto offsetX = OH_ArkUI_NodeEvent_GetNodeComponentEvent(event)->data[0].f32; // 获取点击位置相对于被点击组件左上角的X坐标 377 } 378}; 379nodeAPI->registerNodeEventReceiver(onclick); 380``` 381 382**起始API level** 383 384该特性版本和变更版本均为API 12。 385 386**变更发生版本** 387 388从OpenHarmony SDK 5.0.0.22开始。 389 390**适配指导** 391 392* 用户全局搜索 registerNodeEvent 函数，将所有使用此函数的入参改为4位入参，第四位可用 nullptr 空指针替代。 393 394* 用户全局搜索 ArkUI_NodeEvent类型，将回调中的 event->eventId 修改为 OH_ArkUI_NodeEvent_GetTargetId(event)。 395 396* 用户全局搜索 ArkUI_NodeEvent类型，将回调中的 event->kind 修改为 OH_ArkUI_NodeEvent_GetEventType(event)。 397 398* 用户全局搜索 ArkUI_NodeEvent类型，将回调中的 event->componentEvent.data 修改为 OH_ArkUI_NodeEvent_GetNodeComponentEvent(event)->data。 399 400* 用户全局搜索 ArkUI_NodeEvent类型，将回调中的 event->stringEvent.pStr 修改为 OH_ArkUI_NodeEvent_GetStringAsyncEvent(event)->pStr。 401 402* 用户全局搜索 ArkUI_NodeEvent类型，将回调中的 event->touchEvent 修改为先使用 OH_ArkUI_NodeEvent_GetInputEvent(event) 方法获取到指向 ArkUI_UIInputEvent 类型的指针，再通过开放的各种获取 ArkUI_UIInputEvent 数据的函数方法获取详细的接口数据。 403 404## cl.arkui.9 visibility异常参数处理规格变更 405 406**访问级别** 407 408公开接口 409 410**变更原因** 411 412接口异常值处理变更。 413 414**变更影响** 415 416变更前：异常值时当作hidden处理。 417 418变更后：异常值时当作visible处理。 419 420**起始API Level** 421 422该特性版本为API 7,变更版本为API 12。 423 424**变更发生版本** 425 426从OpenHarmony SDK 5.0.0.22开始。 427 428**适配指导** 429 430异常值处理逻辑变更，不涉及适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期。 431 432## cl.arkui.10 矩阵变换接口transform行为变更 433 434**访问级别** 435 436公开接口 437 438**变更原因** 439 440接口功能完善。 441 442**变更影响** 443 444变更前：传入矩阵中的透视投影变换不进行处理，即不支持透视投影变换。 445 446变更后：处理传入矩阵中的透视投影变换，即支持透视投影变换。 447 448**示例：** 449示例代码 450``` 451import matrix4 from '@ohos.matrix4' 452const matrixArr: [number, number, number, number, 453 number, number, number, number, 454 number, number, number, number, 455 number, number, number, number] = [ 456 0.25, 0, 0, -0.0015, 457 0, 1, 0, 0, 458 0, 0, 1, 0, 459 0, 0, 0, 1]; 460 461let matrix = matrix4.init(matrixArr); 462 463@Entry 464@Component 465struct Tests { 466 build() { 467 Column() { 468 Rect() 469 .fill(Color.Gray) 470 .scale({ 471 x: 1, 472 centerX: 0, 473 centerY: 0, 474 }) 475 .width('500px') 476 .height('500px') 477 .transform(matrix) 478 }.width('100%').height('100%').alignItems(HorizontalAlign.Center) 479 } 480} 481``` 482如下图所示为变更前后效果对比： 483 484 | 变更前 | 变更后 | 485|---------|---------| 486|  |  | 487 488**起始API Level** 489 490该特性版本为API 7。 491 492**变更发生版本** 493 494从OpenHarmony SDK 5.0.0.22开始。 495 496**适配指导** 497 498若传入的矩阵中涉及到透视投影变换，即矩阵最后一列的前三个参数不为0，则会出现变更前后不一致的现象。 499 500适配方法：传入的矩阵中若是涉及到透视投影变换，处理透视投影相关的变换，因此变换效果会发生变化，若是想保持原样，将Matrix4Transit的最后一列的前三个参数（即第4,8,12个参数）置为0即可。 501``` 502const matrixArr: [number, number, number, number, 503 number, number, number, number, 504 number, number, number, number, 505 number, number, number, number] = [ 506 0.25, 0, 0, -0.0015, 507 0, 1, 0, 0, 508 0, 0, 1, 0, 509 0, 0, 0, 1]; 510 511for (let i = 3;i < 12;i += 4) { 512 matrixArr[i] = 0; 513} 514 515let matrix = matrix4.init(matrixArr); 516``` 517
