harmony 鸿蒙ArkUI子系统Changelog

  • 2025-06-16
  • 浏览 (42)

ArkUI子系统Changelog

cl.arkui.1 @Component和@ComponentV2修饰的自定义组件使用@Observed或者@ObservedV2修饰的类增加相关校验

访问级别

公开接口

变更原因

该变更为不兼容变更。

1.在@Component修饰的自定义组件中通过@State、@Prop、@Link、@Provide、@Consume、@StorageLink、@StorageProp、LocalStorageLink、@LocalStorageProp修饰并使用@ObservedV2修饰的变量类型时，进行校验并输出错误信息。

简化示例如下：

@ObservedV2
class TmpA{}

@Entry
@Component
struct testTmp {
  @State value_string: TmpA = new TmpA()
  build() {
    Column(){

    }
  }
}

2.在@ComponentV2修饰的自定义组件中通过@Param、@Local、@Event、@Provider()、@Consumer()修饰并使用@Observed修饰的类时，进行校验并输出错误信息。

简化示例如下：

@Observed
class TmpA{}

@Entry
@ComponentV2
struct testTmp {
  @Param value_string: TmpA = new TmpA()
  build() {
    Column(){

    }
  }
}

3.以上的变量类型联合使用时，也会进行校验并输出错误信息。

示例如下：

@ObservedV2
class TmpA{}

@Observed
class TmpB{}

@Entry
@Component
struct testTmp {
  @State value_string: TmpA|TmpB = new TmpA()
  build() {
    Column(){

    }
  }
}

变更影响

变更前无报错。

变更后报错：

1.The type of the @State property can not be a class decorated with @ObservedV2.

2.The type of the @Param property can not be a class decorated with @Observed.

3.The type of the @State property can not be a class decorated with @ObservedV2.

起始API Level

不涉及API变更

变更发生版本

从OpenHarmony SDK 5.0.0.31开始。

适配指导

如果开发者不按规范使用对应范式，则需按日志提示信息进行修改。

cl.arkui.2 bindContentCover动效参数变更

访问级别

公开接口

变更原因

为满足应用述求和UX规格，全模态动效参数改为与半模态一致。

变更影响

该变更为不兼容变更。

变更前，全模态动效参数为interpolatingSpring(velocity:n, mass:1, stiffness:100, damping:20)，动效时长约为1200ms。

变更后，全模态动效参数为interpolatingSpring(velocity:n, mass:1, stiffness:328, damping:36)，动效时长约为800ms。

起始API Level

11

变更发生版本

从OpenHarmony SDK 5.0.0.31开始。

变更的接口/组件

bindContentCover组件

适配指导

默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改效果控制变量以达到预期，可通过transition接口自定义动效。

cl.arkui.3 @ohos.arkui.advanced.SubHeader删除SymbolRenderingStrategy和SymbolEffectStrategy。

访问级别

公开接口

变更原因

SymbolGlyph中已定义SymbolRenderingStrategy和SymbolEffectStrategy，避免重复枚举定义。减少开发者引用工作量。

变更影响

该变更为不兼容变更。

变更前，引用@ohos.arkui.advanced.SubHeader中SymbolRenderingStrategy和SymbolEffectStrategy，运行时报错：

1.Eerror message:the requested module ‘@ohos.arkui.advanced.SubHeader’ does not provide an export name ‘SymbolRenderingStrategy’ and ‘SymbolEffectStrategy’.

变更后，引用@ohos.arkui.advanced.SubHeader中SymbolRenderingStrategy和SymbolEffectStrategy，编译期报错：

1.Module ‘@ohos.arkui.advanced.SubHeader’ has no exported member ‘SymbolRenderingStrategy’ and ‘SymbolEffectStrategy’.

起始API Level

12

变更发生版本

从OpenHarmony SDK 5.0.0.31开始。

适配指导

如果开发者不按规范使用对应范式，则需按编译提示信息进行修改。参考API文档，删除引用SubHeader中SymbolRenderingStrategy和SymbolEffectStrategy，自动引用SymbolGlyph中SymbolRenderingStrategy和SymbolEffectStrategy。 适配示例：

import { promptAction, OperationType, SubHeader } from '@kit.ArkUI'

@Entry
@Component
struct SubHeaderExample {
  build() {
    Column() {
      SubHeader({
        icon: $r('sys.symbol.ohos_wifi'),
        iconSymbolOptions: {
          effectStrategy: SymbolEffectStrategy.HIERARCHICAL,
          renderingStrategy: SymbolRenderingStrategy.MULTIPLE_COLOR,
          fontColor: [Color.Blue, Color.Grey, Color.Green],
        },
        secondaryTitle: '标题',
        operationType: OperationType.BUTTON,
        operationItem: [{ value: '操作',
          action: () => {
            promptAction.showToast({ message: 'demo' })
          }
        }]
      })
    }
  }
}

cl.arkui.4 bindSheet支持嵌套滚动

访问级别

公开接口

变更原因

为满足应用诉求，半模态面板嵌套滚动组件，且在滚动组件上设置嵌套模式时，需要实现联动效果。

变更影响

该变更为不兼容变更。

单挡位模式下半模态仅可设置一档高度。多挡位模式下半模态可以设置三档高度，内容位于半模态面板顶部时，通过上下滑动可以自由切换挡位。

API version 12之前，半模态面板嵌套滚动组件，且在滚动组件上设置嵌套模式时，无法实现联动。内容位于顶部，多档位时上下滑动无法切换挡位，单挡位时下滑无法关闭半模态。

API version 12及以后，半模态面板嵌套滚动组件，且在滚动组件上设置嵌套模式时，可以实现联动。内容位于顶部，多档位时上下滑动可以切换挡位；单挡位时下滑可以关闭半模态。

在滚动组件上设置嵌套的情况下： |多挡位变更前|多挡位变更后| |———|———| |无法通过上下滑动切换挡位，在最低档下滑无法关闭半模态
Alt text|可以通过上下滑动切换挡位，在最低档下滑可以关闭半模态
Alt text|

单挡位变更前 单挡位变更后
无法通过下滑关闭半模态
Alt text		 可以通过下滑关闭半模态
Alt text

起始API Level

11

变更发生版本

从OpenHarmony SDK 5.0.0.31开始。

变更的接口/组件

bindSheet组件

适配指导

需要开发者主动适配。例如，在半模态面板中嵌套List组件场景，@Builder内容可以参考如下示例。

private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
@Builder
myBuilder() {
  Column() {
    List({ space: 20, initialIndex: 0 }) {
        ForEach(this.arr, (item: number) => {
          ListItem() {
            Text('' + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor(0xFFFFFF)
          }
        }, (item: string) => item)
      }
      .listDirection(Axis.Vertical) // 排列方向
      .edgeEffect(EdgeEffect.None)
      .nestedScroll({
        scrollForward: NestedScrollMode.PARENT_FIRST,
        scrollBackward: NestedScrollMode.SELF_FIRST
      }) // 嵌套模式
      .backgroundColor(Color.Gray)
      .width('90%')
      .height('100%')
  }
}

cl.arkui.5 RichEditor长按交互调整

访问级别

公开接口

变更原因

为满足应用述求和UX规格，RichEditor组件长按交互效果需要进行调整。

变更影响

该变更为不兼容性变更。

变更前，长按文本内容，直接触发选词，展示选中背板、手柄以及文本选择菜单。

变更后，长按文本内容不松手，触发选词并展示选中背板，继续拖动变更选中区域，松手后展示手柄及文本选择菜单。如果不继续拖动，则松手时直接展示手柄和文本选择菜单。 |变更前 |变更后 | |————————————–|————————————| |alt text|alt text|

起始API Level

不涉及API变更

变更发生版本

从OpenHarmony SDK 5.0.0.31开始。

变更的接口/组件

RichEditor组件

适配指导

默认行为变更，无需适配，但应注意变更后的默认效果是否符合开发者预期，如不符合则自定义修改事件效果以达到预期。

cl.arkui.6 TextTimer的onTimer回调频率与参数单位调整

访问级别

公开接口

变更原因

调整onTimer回调频率与参数的单位，使其符合文档描述。

变更影响

该变更为不兼容性变更。

TextTimer的format属性用于自定义时间格式。其中，毫秒可使用S、SS和SSS关键字表示，分别代表100ms、10ms和1ms。

变更前，当TextTimer的format属性包含毫秒时，TextTimer的文本发生变化，便会几毫秒触发一次onTimer事件，且回调参数utc和elapsedTime的单位为毫秒。

变更后，TextTimer的文本发生变化时，onTimer事件的触发时间与回调参数utc和elapsedTime的单位随format属性的自定义时间格式变化。format为mm:ss.S时，100ms回调一次onTimer事件，回调参数的单位为100ms。format为mm:ss.SS时，10ms回调一次onTimer事件，回调参数的单位为10ms。format为mm:ss.SSS时，与变更前保持一致。

起始API Level

11

变更发生版本

从OpenHarmony SDK 5.0.0.31开始。

变更的接口/组件

textTimer组件的onTimer接口

适配指导

需要开发者主动适配，调整回调参数的数量级。

@Entry
@Component
struct TextTimerExample {
  textTimerController: TextTimerController = new TextTimerController();
  build() {
    Column(){
      TextTimer({isCountDown: true, count: 30000, controller: this.textTimerController})
        .format('mm:ss.SS')
        .fontSize(50)
        .onTimer((utc: number, elapsedTime: number) => {
          // 如果开发者需改回变更前的效果，可以将utc、elapsedTime乘10
          console.info('textTimer countDown utc is:' + utc * 10 + ',elapsedTime is:' + elapsedTime * 10)
        })

      TextTimer({isCountDown: true, count: 30000, controller: this.textTimerController})
        .format('mm:ss.S')
        .fontSize(50)
        .onTimer((utc: number, elapsedTime: number) => {
          // 如果开发者需改回变更前的效果，可以将utc、elapsedTime乘100
          console.info('textTimer countDown utc is:' + utc * 100 + ',elapsedTime is:' + elapsedTime * 100)
        })
    }
  }
}

cl.arkui.7 滚动类组件（List、Grid、WaterFlow、Scroll）Friction接口默认值变更

访问级别

公开接口

变更原因

为了优化功耗，将滚动类组件（List、Grid、WaterFlow、Scroll）friction接口默认值改为0.75。

变更影响

该变更为不兼容变更。

变更前，滚动类组件（List、Grid、WaterFlow、Scroll）的friction接口默认值为0.7。

变更后，滚动类组件（List、Grid、WaterFlow、Scroll）的friction接口默认值为0.75。相较变更之前，用同样力度抛滑，抛滑时间更短、抛滑距离更近。

起始API Level

10

变更发生版本

从OpenHarmony SDK 5.0.0.31开始。

变更的接口/组件

滚动类组件（List、Grid、WaterFlow、Scroll）的friction接口。

适配指导

开发者如果需要使用变更之前的抛滑效果，可以将friction接口的参数设置为0.7。

@Entry
@Component
struct FrictionExample {
  build() {
    List() {
      ForEach([1, 2, 3, 4, 5], (item: number) => {
        ListItem() {
          Text('' + item)
            .width('100%').height(200).fontSize(16)
            .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
        }
      }, (item: string) => item)
    }
    .height(500)
    .friction(0.7)
  }
}

cl.arkui.8 ListItem卡片样式行为变更

访问级别

公开接口

变更原因

原本ListItem在LazyForEach下使用时，ListItem设置卡片样式不生效，需要整该为能够生效。

变更影响

该变更为不兼容变更。

变更前：ListItem在LazyForEach下使用时，卡片样式设置不生效。
变更后：ListItem在LazyForEach下使用时，卡片样式设置可以生效。

// Basic implementation of IDataSource to handle data listener
abstract class BasicDataSource<T> implements IDataSource {
  private listeners: DataChangeListener[] = []

  public totalCount(): number {
    return 0
  }
  abstract getData(index: number): T;

  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener)
    }
  }
  unregisterDataChangeListener(listener: DataChangeListener): void {
   const pos = this.listeners.indexOf(listener);
   if (pos >= 0) {
     this.listeners.splice(pos, 1)
   }
  }

  notifyDataReload(): void {
    this.listeners.forEach(listener => {
      listener.onDataReloaded()
    })
  }
  notifyDataAdd(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataAdd(index)
    })
  }
  notifyDataChange(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataChange(index)
    })
  }
  notifyDataDelete(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataDelete(index)
    })
  }
  notifyDataMove(from: number, to: number): void {
    this.listeners.forEach(listener => {
      listener.onDataMove(from, to)
    })
  }
}

class MyDataSource<T> extends BasicDataSource<T> {
  public dataArray: T[] = [];

  public totalCount(): number {
    return this.dataArray.length
  }
  public getData(index: number): T {
    return this.dataArray[index]
  }

  public addData(index: number, data: T): void {
    this.dataArray.splice(index, 0, data)
    this.notifyDataAdd(index)
  }
  public popFirstData(): void {
    this.dataArray.shift()
    this.notifyDataDelete(0)
  }
  public pushData(data: T): void {
    this.dataArray.push(data)
    this.notifyDataAdd(this.dataArray.length - 1)
  }
  public popData(): void {
    this.dataArray.pop()
    this.notifyDataDelete(this.dataArray.length)
  }
}

@Entry
@Component
struct Index {
  arr:MyDataSource<number> = new MyDataSource<number>();
  aboutToAppear(): void {
    for (let i = 0; i < 10; i++) {
      this.arr.pushData(i)
    }
  }

  build() {
    List() {
      ListItemGroup({ style: ListItemGroupStyle.CARD }) {
        LazyForEach(this.arr, (item: number) => {
          ListItem({ style: ListItemStyle.CARD }) {
            Text("item" + item.toString())
          }
        })
      }
    }.backgroundColor("#DCDCDC")
    .height("100%")
  }
}
变更前效果 变更后效果

起始API Level

10

变更发生版本

从OpenHarmony SDK 5.0.0.31 版本开始。

变更的接口/组件

涉及的组件：ListItem组件ListItemStyle接口。

适配指导

如果ListItem在LazyForEach下使用，设置了卡片样式没有生效，变更后生效卡片样式导致显示界面变化，可以删除卡片样式的设置。

如下代码变更前设置卡片样式不生效，变更后生效卡片样式导致显示界面变化。

build() {
  List() {
    ListItemGroup({ style: ListItemGroupStyle.CARD }) {
      LazyForEach(this.arr, (item: number) => {
        ListItem({ style: ListItemStyle.CARD }) {
          Text("item" + item.toString())
            .height(64)
        }
      })
    }
  }.backgroundColor("#DCDCDC")
  .height("100%")
}

删除ListItem卡片样式可以恢复变更前效果。

build() {
  List() {
    ListItemGroup({ style: ListItemGroupStyle.CARD }) {
      LazyForEach(this.arr, (item: number) => {
        ListItem() {
          Text("item" + item.toString())
            .height(64)
        }
      })
    }
  }.backgroundColor("#DCDCDC")
  .height("100%")
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ability子系统Changelog

harmony 鸿蒙ArkCompiler子系统变更说明

harmony 鸿蒙ArkData方舟数据管理变更说明

harmony 鸿蒙包管理子系统变更说明

harmony 鸿蒙通知子系统Changelog

harmony 鸿蒙用户IAM子系统Changelog

harmony 鸿蒙窗口子系统变更说明

0  赞
  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/pfQvO6
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录