openharmony 鸿蒙 changelogs-arkui

2025-06-16 浏览 (1)

ArkUI子系统Changelog

cl.arkui.1 TextClock组件构造参数timeZoneOffset支持设置特定浮点数

访问级别

公开接口

变更原因

某些国家和地区时区偏移量为浮点数，因此需要支持设置浮点数。

变更影响

该变更为兼容性变更，变更后timeZoneOffset支持设置特定浮点数。

API Level

8

变更发生版本

从OpenHarmony SDK 4.1.6.5 版本开始。

变更的接口/组件

API 11之前，TextClock组件构造参数timeZoneOffset设置浮点数会取对应的整数值。

API 11及之后，TextClock组件构造参数timeZoneOffset设置{ 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 }里的值会取对应的浮点数。

适配指导

请查阅TextClock组件文档进行适配。

cl.arkui.2 Gauge组件的默认阴影模糊半径变更

访问级别

公开接口

变更原因

当前Gauge组件的默认阴影模糊半径为5vp、UX检视时发现模糊半径过小，因此依照UX规范增加阴影模糊半径到20vp。

变更影响

该变更为兼容性变更，改变了组件默认情况下的阴影模糊半径，提升了组件的默认显示效果。

API Level

11

变更发生版本

从OpenHarmony SDK 4.1.6.5开始。

变更的接口/组件

OpenHarmony SDK 4.1.6.5前，Gauge组件的默认阴影模糊半径为5vp。

gauge

OpenHarmony SDK 4.1.6.5及以后，Gauge组件的默认阴影模糊半径为20vp。

gauge

适配指导

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

cl.arkui.3 getItemRect, getItemRectInGroup接口返回值单位变更

访问级别

公开接口

变更原因

返回值类型为RectResult，位置和宽高以px为单位不合理，故变更返回值单位为vp。

变更影响

该变更为非兼容性变更。滚动组件getItemRect接口和List组件getItemRectInGroup接口的返回值单位从px变更为vp。具体受影响的场景如下：

a) 滚动组件通过getItemRect接口获取子组件大小位置

API version 11变更前：大小位置返回值都以px为单位。

API version 11变更后：大小位置返回值都以vp为单位。

b) List组件通过getItemRectInGroup接口获取子组件ListItemGroup内子组件ListItem的大小位置

API version 11变更前：大小位置返回值都以px为单位。

API version 11变更后：大小位置返回值都以vp为单位。

API Level

11

变更发生版本

从OpenHarmony SDK 4.1.6.5开始。

变更的接口/组件

滚动组件（List、Grid、WaterFlow、Scroll）getItemRect接口、List组件getItemRectInGroup接口

适配指导

滚动组件（List、Grid、WaterFlow、Scroll）getItemRect接口、List组件getItemRectInGroup接口的返回值单位由原来的px变更为vp。如果需要使用px单位类型，可用vp2px接口做单位转换。

cl.arkui.4 自定义组件构造传参赋值中装饰器变量@Link/@ObjectLink校验日志级别变更

访问级别

公开接口

变更原因

装饰器@Link/@ObjectLink父组件校验由WARN 变成ERROR。

变更影响

该变更为非兼容性变更，变更后@Link/@ObjectLink父组件校验报错。

API Level

11

变更发生版本

从OpenHarmony SDK 4.1.6.5 版本开始。

示例：

let NextID: number = 1;

@Observed
class ClassA {
  public id: number;
  public c: number;

  constructor(c: number) {
    this.id = NextID++;
    this.c = c;
  }
}

@Entry
@Component
struct Parent {
  @State message: string = 'Hello';

  build() {
    Column() {
      // ERROR: Property 'message' in the custom component 'Child' is missing (mandatory to specify).
      // ERROR: Property 'message1' in the custom component 'Child' is missing (mandatory to specify).
      Child();
    }
  }
}

@Component
struct Child {
  @Link message: string;
  @ObjectLink message1: ClassA;

  build() {
    Row() {
    }
  }
}

变更的接口/组件

不涉及

适配指导

子组件使用了装饰器@Link/@ObjectLink，父组件使用带有装饰器@Link/@ObjectLink的自定义组件时，父组件必须给@Link/@ObjectLink修饰的变量传值。

cl.arkui.5 bindmenu使用isShow时点击事件变更

访问级别

公开接口

变更原因

在bindMenu使用isShow时，只允许isShow控制menu的开启。

变更影响

该变更为非兼容性变更，变更后在bindMenu使用isShow的情况下，点击父组件不会弹出menu。

API Level

11

变更发生版本

从OpenHarmony SDK 4.1.6.5 版本开始。 示例：

@Entry
@Component
struct MenuExample {
  @State listData: number[] = [0, 0, 0]
  @State isShow: boolean = false

  @Builder MenuBuilder() {
    Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
      ForEach(this.listData, (item:number, index) => {
        Column() {
          Row() {
            Image($r("app.media.icon")).width(20).height(20).margin({ right: 5 })
            Text(`Menu${index as number + 1}`).fontSize(20)
          }
          .width('100%')
          .height(30)
          .justifyContent(FlexAlign.Center)
          .align(Alignment.Center)
          .onClick(() => {
            console.info(`Menu${index as number + 1} Clicked!`)
          })

          if (index != this.listData.length - 1) {
            Divider().height(10).width('80%').color('#ccc')
          }
        }.padding(5).height(40)
      })
    }.width(100)
  }

  build() {
    Column() {
      Text('click for menu')
        .fontSize(20)
        .margin({ top: 20 })
        .onClick(()=>{
          this.isShow = true
        })
        .bindMenu(this.isShow, this.MenuBuilder,
          {
            onDisappear: ()=>{
              this.isShow = false
            }
          }
        )
    }
    .height('100%')
    .width('100%')
    .backgroundColor('#f0f0f0')
  }
}

变更的接口/组件

bindMenu

适配指导

使用isShow后，需要在其他事件中将isShow从false改成true，menu才会弹出，例如点击事件、手势事件以及hover等，如果出现修改isShow的值后，菜单无法弹出，可以在isShow修改前后加上日志打印该值，判断isShow是否有变化, 如果没有变化，需要检查是不是在menu消失的时候没有在onDisappear里更新isShow的值为false，或者初始情况下将isShow设置为了true。

cl.arkui.6 OffscreenCanvas类声明式继承错误删除

访问级别

公开接口

变更原因

OffscreenCanvas类声明时父类关系继承错误会导致DevEco Studio错误联想出非OffscreenCanvas本身的方法和属性。

变更影响

该变更为兼容性变更，变更后OffscreenCanvas类的方法和属性在DevEco studio中可正确联想，先前因OffscreenCanvas类声明时父类继承错误导致的非OffscreenCanvas本身的方法和属性不再被联想出来。

API Level

11

变更发生版本

从OpenHarmony SDK 4.1.6.5 版本开始。

变更的接口/组件

OffscreenCanvas

适配指导

DevEco Studio中OffscreenCanvas代码编辑联想功能，不涉及适配。

cl.arkui.7 layoutWeight支持float类型变更

访问级别

公开接口

变更原因

layoutWeight需要更精细的设置。

变更影响

该变更为兼容性变更，变更后layoutWeight参数支持float类型。

API Level

9

变更发生版本

从OpenHarmony SDK 4.1.6.5开始。

变更的接口/组件

涉及到layoutWeight接口

API 12前，参数为float类型，小数点后不生效。

API 12及以后，参数为float类型，小数点后生效。

适配指导

接口参数类型变更，不涉及适配。

cl.arkui.8 GridRow组件高度自适应变更

访问级别

公开接口

变更原因

原规格遗留问题，变更前用户设置了GridRow组件的height属性，而实际上GridRow组件的高度并不会按设置的height进行绘制，而是会自适应子组件高度。 现将规格确定为：若用户设置了GridRow组件的height属性，则GridRow组件的高度按设置的height进行绘制，若用户没有设置GridRow组件的height属性，则自适应子组件高度。

变更影响

该变更为非兼容性变更。改变了GridRow组件的高度设置，可按照用户设置的高度进行绘制。

API Level

9

变更发生版本

从OpenHarmony SDK 4.1.6.5开始。

变更的接口/组件

涉及到GridRow组件

API 11前，GridRow组件无论是否设置height属性，其高度都会自适应子组件高度。

API 11及以后，GridRow组件设置了height属性后不再自适应子组件高度，而是按用户设置高度进行绘制；如果没有设置height属性，则仍会自适应子组件高度。

适配指导

组件高度自适应变更，不涉及适配。

cl.arkui.9 surface类型XComponent组件backgroundColor属性行为变更

访问级别

公开接口

变更原因

surface类型的XComponent组件需支持设置背景色。

变更影响

该变更为非兼容性变更，场景为给surface类型的XComponent组件设置backgroundColor属性，具体行为如下：

API version 11变更前：无论设置何种属性，背景色均为默认黑色背景色。

API version 11变更后：组件背景色会生效所设置的颜色。

API Level

9

变更发生版本

从OpenHarmony SDK 4.1.6.5 版本开始。

示例：

@Entry
@Component
struct XComponentBKColor {
  private surfaceId: string = ''
  private xComponentContext: Record<string, () => void> = {}
  xComponentController: XComponentController = new XComponentController()

  build() {
    Row() {
      XComponent({
        id: 'xcomponentid',
        type: XComponentType.SURFACE,
        controller: this.xComponentController
      })
        .onLoad(() => {
          this.xComponentController.setXComponentSurfaceSize({ surfaceWidth: 1920, surfaceHeight: 1080 })
          this.surfaceId = this.xComponentController.getXComponentSurfaceId()
          this.xComponentContext = this.xComponentController.getXComponentContext() as Record<string, () => void>
        })
        .width('640px')
        .height('480px')
        .backgroundColor(Color.White)
    }
  }
}

变更的接口/组件

XComponent

适配指导

给surface类型的XComponent组件设置backgroundColor属性后，确认是应用的场景所需要的背景色。

cl.arkui.10 TextInput/TextArea组件光标超出圆角部分截断显示效果变更

访问级别

公开接口

变更原因

该变更为非兼容性变更，当设置TextInput组件padding为0时，光标会显示在输入框默认圆角外，不符合应用诉求。

变更影响

API version 11变更前：输入框使用默认圆角， 设置padding为0，光标超出输入框组件圆角的部分未被截断。

Alt text

API version 11变更后：输入框使用默认圆角， 设置padding为0，光标超出输入框组件圆角的部分会被截断。

Alt text

API Level

9

变更发生版本

从OpenHarmony SDK 4.1.6.5开始。

变更的接口/组件

TextInput/TextArea

适配指导

默认行为变更，不涉及适配。

cl.arkui.11 全局接口作用的UI实例跟踪匹配规则变更

访问级别

公开接口

变更原因

规范全局接口UI实例匹配行为，避免因实例不明确造成的非预期行为。

变更影响

多实例场景下，在未绑定UI实例的上下文中调用全局接口（如在异步回调中使用路由接口），接口的作用实例可能发生变化。

全局接口需要明确的UI实例上下文以确定作用的UI实例，建议通过绑定实例的接口进行调用。

API Level

8

变更发生版本

从OpenHarmony SDK 4.1.6.5开始。

变更的接口/组件

不推荐开发者在多实例场景下使用如下接口，建议开发者使用适配指导中的替代接口。

API说明
@ohos.animator自定义动画控制器
@ohos.arkui.componentSnapshot组件截图
@ohos.arkui.componentUtils组件工具类
@ohos.arkui.dragController拖拽控制器
@ohos.arkui.inspector组件布局回调
@ohos.arkui.observer无感监听
@ohos.font自定义字体
@ohos.measure文本计算
@ohos.mediaquery媒体查询
@ohos.promptAction弹窗
@ohos.router页面路由
AlertDialog警告弹窗
ActionSheet列表选择弹窗
CalendarPickerDialog日历选择器弹窗
DatePickerDialog日期滑动选择弹窗
TimePickerDialog时间滑动选择器弹窗
TextPickerDialog文本滑动选择器弹窗
ContextMenu菜单控制
vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx像素单位转换
focusControl焦点控制
cursorControl光标控制
getContext获取当前的Ability的Context
LocalStorage.getShared获取Ability传递的Storage
animateTo显式动画
animateToImmediately显式立即动画

适配指导

使用组件内置方法getUIContext，可直接获取当前组件所在的UIContext，并使用如下UIContext中的API获取与实例绑定的对象。

UIContext接口说明
getRouter页面路由
getComponentUtils组件工具类
getUIInspector组件布局回调
getUIObserver无感监听
getMediaQuery媒体查询
getFont字体
getPrompAction弹窗
animateTo显示动画
showAlerDialog警告弹窗
showActionSheet列表选择弹窗
showDatePickerDialog日期滑动选择弹窗
showTimePickerDialog时间滑动选择器弹窗
showTextPcikerDialog文本滑动选择器弹窗
createAnimator自定义动画控制器
KeyboardAvoidMode键盘避让
getAtomicServiceBar云服务
getDragController/getDragPreview拖拽
runScopedTask执行绑定实例的闭包

对于以下UIContext中尚不具备的API，可使用runScopedTask进行适配：

接口说明
measure文本计算
getContext获取当前的Ability的Context
LocalStorage.getShared获取Ability传递的Storage
animateToImmediately显式立即动画
ContextMenu菜单控制
vp2px/px2vp/fp2px/px2fp/lpx2px/px2lpx像素单位转换
focusControl焦点控制
cursorControl光标控制
@ohos.arkui.componentSnapshot组件截图

示例1

// 使用绑定实例的路由对象进行页面路由
@Entry
@Component
struct Index {
  build() {
    Row() {
      Button()
        .onClick(() => {
          let uiContext = this.getUIContext();
          let uiRouter = uiContext.getRouter();
          uiRouter.pushUrl({
            url: 'pages/Page'
          })
        })
    }
  }
}

示例2

// 执行绑定实例的闭包
@Entry
@Component
struct Index {
  build() {
    Row() {
      Button()
        .onClick(() => {
          let uiContext = this.getUIContext();
          uiContext.runScopedTask(() => {
            let context = getContext();
            console.log('Get context: ' + JSON.stringify(context))
          })
        })
    }
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙元能力子系统变更说明

harmony 鸿蒙arkcompiler子系统变更说明

harmony 鸿蒙ArkWeb子系统Changelog

harmony 鸿蒙分布式数据管理子系统ChangeLog

harmony 鸿蒙媒体子系统音频接口变更说明

harmony 鸿蒙窗口子系统ChangeLog

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/dOt36M