OpenHarmony应用开发-属性动画/显式动画/转场动画/路径动画
版本:v3.2 Release
属性动画
组件的某些通用属性变化时,可以通过属性动画实现渐变过渡效果,提升用户体验。支持的属性包括width、height、backgroundColor、opacity、scale、rotate、translate等。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
animation(value: {duration?: number, tempo?: number, curve?: string | Curve | ICurve, delay?:number, iterations: number, playMode?: PlayMode, onFinish?: () => void})
从API version 9开始,该接口支持在ArkTS卡片中使用。
参数:
名称 | 参数类型 | 必填 | 描述 |
duration | number | 否 | 设置动画时长。 默认值:1000 单位:毫秒 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: - 在ArkTS卡片上最大动画持续时间为1000毫秒。 - 设置小于1的值时按0处理。 - 设置浮点型类型的值时,向下取整;设置值为1.2,按照1处理。 |
tempo | number | 否 | 动画播放速度。数值越大,动画播放速度越快,数值越小,播放速度越慢。 值为0时,表示不存在动画。 默认值:1 说明: 当设置小于1的值时按值为1处理。 |
curve | string | Curve | ICurve9+ | 否 | 设置动画曲线。默认曲线为线性。 默认值:Curve.Linear 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
delay | number | 否 | 设置动画延迟执行的时长。单位为毫秒,默认不延时播放。 默认值:0 取值范围:[0, +∞) 说明: 当设置的值小于1时按0处理。设置浮点型类型的值时,向下取整。例如,设置值为1.2,按照1处理。 |
iterations | number | 否 | 设置播放次数。 默认值:1 取值范围:[-1, +∞) 说明: 设置为-1时表示无限次播放。设置为0时表示无动画效果。 |
playMode | 否 | 设置动画播放模式,默认播放完成后重头开始播放。 默认值:PlayMode.Normal 从API version 9开始,该接口支持在ArkTS卡片中使用。 | |
onFinish | () => void | 否 | 状态回调,动画播放完成时触发。 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 当iterations设置为-1时,动画效果无限循环不会停止,所以不会触发此回调。 |
示例
// xxx.ets
@Entry
@Component
struct AttrAnimationExample {
@State widthSize: number = 250
@State heightSize: number = 100
@State rotateAngle: number = 0
@State flag: boolean = true
build() {
Column() {
Button('change size')
.onClick(() => {
if (this.flag) {
this.widthSize = 150
this.heightSize = 60
} else {
this.widthSize = 250
this.heightSize = 100
}
this.flag = !this.flag
})
.margin(30)
.width(this.widthSize)
.height(this.heightSize)
.animation({
duration: 2000,
curve: Curve.EaseOut,
iterations: 3,
playMode: PlayMode.Normal
})
Button('change rotate angle')
.onClick(() => {
this.rotateAngle = 90
})
.margin(50)
.rotate({ angle: this.rotateAngle })
.animation({
duration: 1200,
curve: Curve.Friction,
delay: 500,
iterations: -1, // 设置-1表示动画无限循环
playMode: PlayMode.Alternate
})
}.width('100%').margin({ top: 20 })
}
}
显式动画
提供全局animateTo显式动画接口来指定由于闭包代码导致的状态变化插入过渡动效。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
animateTo(value: AnimateParam, event: () => void): void
从API version 9开始,该接口支持在ArkTS卡片中使用。
参数 | 类型 | 是否必填 | 描述 |
value | 是 | 设置动画效果相关参数。 | |
event | () => void | 是 | 指定显示动效的闭包函数,在闭包函数中导致的状态变化系统会自动插入过渡动画。 |
AnimateParam对象说明
名称 | 类型 | 描述 |
duration | number | 动画持续时间,单位为毫秒。 默认值:1000 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: - 在ArkTS卡片上最大动画持续时间为1000毫秒,若超出则固定为1000毫秒。 |
tempo | number | 动画的播放速度,值越大动画播放越快,值越小播放越慢,为0时无动画效果。 默认值:1.0 |
curve | 动画曲线。 默认值:Curve.Linear 从API version 9开始,该接口支持在ArkTS卡片中使用。 | |
delay | number | 单位为ms(毫秒),默认不延时播放。 默认值:0 |
iterations | number | 默认播放一次,设置为-1时表示无限次播放。 默认值:1 |
playMode | 设置动画播放模式,默认播放完成后重头开始播放。 默认值:PlayMode.Normal 从API version 9开始,该接口支持在ArkTS卡片中使用。 | |
onFinish | () => void | 动效播放完成回调。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
示例
// xxx.ets
@Entry
@Component
struct AnimateToExample {
@State widthSize: number = 250
@State heightSize: number = 100
@State rotateAngle: number = 0
private flag: boolean = true
build() {
Column() {
Button('change size')
.width(this.widthSize)
.height(this.heightSize)
.margin(30)
.onClick(() => {
if (this.flag) {
animateTo({
duration: 2000,
curve: Curve.EaseOut,
iterations: 3,
playMode: PlayMode.Normal,
onFinish: () => {
console.info('play end')
}
}, () => {
this.widthSize = 150
this.heightSize = 60
})
} else {
animateTo({}, () => {
this.widthSize = 250
this.heightSize = 100
})
}
this.flag = !this.flag
})
Button('change rotate angle')
.margin(50)
.rotate({ x: 0, y: 0, z: 1, angle: this.rotateAngle })
.onClick(() => {
animateTo({
duration: 1200,
curve: Curve.Friction,
delay: 500,
iterations: -1, // 设置-1表示动画无限循环
playMode: PlayMode.Alternate,
onFinish: () => {
console.info('play end')
}
}, () => {
this.rotateAngle = 90
})
})
}.width('100%').margin({ top: 5 })
}
}
转场动画
页面间转场
当路由进行切换时,可以通过 在pageTransition中自定义页面入场和页面退场的转场动效。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
名称 | 参数 | 必填 | 参数描述 |
PageTransitionEnter | { type?: RouteType, duration?: number, curve?: Curve | string, delay?: number } | 否 | 设置当前页面的自定义入场动效。 - type:页面转场效果生效的路由类型。 默认值:RouteType.None。 说明: 没有匹配时使用系统默认的页面转场效果(根据设备可能会有差异),如需禁用系统默认页面转场效果,可以指定duration为0。 - duration:动画的时长 单位:毫秒 - curve:动画曲线。string类型的取值支持"ease"、“ease-in”、“ease-out”、“ease-in-out”、“extreme-deceleration”、“fast-out-linear-in”、“fast-out-slow-in”、“friction”、“linear”、“linear-out-slow-in”、“rhythm”、“sharp”、“smooth”。 默认值:Curve.Linear - delay:动画延迟时长。 默认值:0 单位:毫秒 |
PageTransitionExit | { type?: RouteType, duration?: number, curve?: Curve | string, delay?: number } | 否 | 设置当前页面的自定义退场动效。 - type:页面转场效果生效的路由类型。 默认值:RouteType.None。 说明: 没有匹配时使用系统默认的页面转场效果(根据设备可能会有差异),如需禁用系统默认页面转场效果,可以指定duration为0。 - duration:动画的时长,单位为毫秒。 - curve:动画曲线,string类型取值与PageTransitionEnter相同。 默认值:Curve.Linear - delay:动画延迟时长。 默认值:0 单位:毫秒 |
RouteType枚举说明
名称 | 描述 |
Pop | 重定向指定页面。从PageB回退到之前的页面PageA。对于PageB,指定RouteType为None或者Pop的PageTransitionExit组件样式生效,对于PageA,指定RouteType为None或者Pop的PageTransitionEnter组件样式生效。 |
Push | 跳转到下一页面。PageA跳转到下一个新的界面PageB。对于PageA,指定RouteType为None或者Push的PageTransitionExit组件样式生效,对于PageB,指定RouteType为None或者Push的PageTransitionEnter组件样式生效。 |
None | 页面未重定向。如Push和Pop描述中RouteType为None的情形,即页面进场时PageTransitionEnter的转场效果生效;退场时PageTransitionExit的转场效果生效。 |
属性
参数名称 | 参数类型 | 必填 | 参数描述 |
slide | 否 | 设置页面转场时的滑入滑出效果。 默认值:SlideEffect.Right | |
translate | { x? : number | string, y? : number | string, z? : number | string } | 否 | 设置页面转场时的平移效果,为入场时起点和退场时终点的值,和slide同时设置时默认生效slide。 - x:横向的平移距离。 - y:纵向的平移距离。 - z:竖向的平移距离。 |
scale | { x? : number, y? : number, z? : number, centerX? : number | string, centerY? : number | string } | 否 | 设置页面转场时的缩放效果,为入场时起点和退场时终点的值。 - x:横向放大倍数(或缩小比例)。 - y:纵向放大倍数(或缩小比例)。 - z:竖向放大倍数(或缩小比例)。 - centerX、centerY缩放中心点。 - 中心点为0时,默认的是组件的左上角。 |
opacity | number | 否 | 设置入场的起点透明度值或者退场的终点透明度值。 默认值:1 |
SlideEffect枚举说明
名称 | 描述 |
Left | 设置到入场时表示从左边滑入,出场时表示滑出到左边。 |
Right | 设置到入场时表示从右边滑入,出场时表示滑出到右边。 |
Top | 设置到入场时表示从上边滑入,出场时表示滑出到上边。 |
Bottom | 设置到入场时表示从下边滑入,出场时表示滑出到下边。 |
事件
事件 | 功能描述 |
onEnter(event: (type?: RouteType, progress?: number) => void) | 回调入参为当前入场动画的归一化进度[0 - 1]。 - type:跳转方法。 - progress:当前进度。 触发该事件的条件: 逐帧回调,直到入场动画结束,progress从0变化到1。 |
onExit(event: (type?: RouteType, progress?: number) => void) | 回调入参为当前退场动画的归一化进度[0 - 1]。 - type:跳转方法。 - progress:当前进度。 触发该事件的条件: 逐帧回调,直到退场动画结束,progress从0变化到1。 |
示例
自定义方式1:配置了当前页面的入场动画为淡入,退场动画为缩小。
// index.ets
@Entry
@Component
struct PageTransitionExample1 {
@State scale1: number = 1
@State opacity1: number = 1
build() {
Column() {
Navigator({ target: 'pages/page1', type: NavigationType.Push }) {
Image($r('app.media.bg1')).width('100%').height('100%') // 图片存放在media文件夹下
}
}.scale({ x: this.scale1 }).opacity(this.opacity1)
}
// 自定义方式1:完全自定义转场过程的效果
pageTransition() {
PageTransitionEnter({ duration: 1200, curve: Curve.Linear })
.onEnter((type: RouteType, progress: number) => {
this.scale1 = 1
this.opacity1 = progress
}) // 进场过程中会逐帧触发onEnter回调,入参为动效的归一化进度(0% -- 100%)
PageTransitionExit({ duration: 1500, curve: Curve.Ease })
.onExit((type: RouteType, progress: number) => {
this.scale1 = 1 - progress
this.opacity1 = 1
}) // 退场过程中会逐帧触发onExit回调,入参为动效的归一化进度(0% -- 100%)
}
}
// page1.ets
@Entry
@Component
struct AExample {
@State scale2: number = 1
@State opacity2: number = 1
build() {
Column() {
Navigator({ target: 'pages/index', type: NavigationType.Push }) {
Image($r('app.media.bg2')).width('100%').height('100%') // 图片存放在media文件夹下
}
}.width('100%').height('100%').scale({ x: this.scale2 }).opacity(this.opacity2)
}
// 自定义方式1:完全自定义转场过程的效果
pageTransition() {
PageTransitionEnter({ duration: 1200, curve: Curve.Linear })
.onEnter((type: RouteType, progress: number) => {
this.scale2 = 1
this.opacity2 = progress
}) // 进场过程中会逐帧触发onEnter回调,入参为动效的归一化进度(0% -- 100%)
PageTransitionExit({ duration: 1500, curve: Curve.Ease })
.onExit((type: RouteType, progress: number) => {
this.scale2 = 1 - progress
this.opacity2 = 1
}) // 退场过程中会逐帧触发onExit回调,入参为动效的归一化进度(0% -- 100%)
}
}
组件内转场
组件内转场主要通过transition属性配置转场参数,在组件插入和删除时显示过渡动效,主要用于容器组件中的子组件插入和删除时,提升用户体验(需要配合animateTo才能生效,动效时长、曲线、延时跟随animateTo中的配置)。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 参数描述 |
transition | TransitionOptions | 设置组件插入显示和删除隐藏的过渡效果。 默认值:不设置任何过渡效果时,默认有透明度从0到1的过渡效果。若设置了其他过渡效果,以设置的过渡效果为准。 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 所有参数均为可选参数,详细描述见TransitionOptions参数说明。 |
TransitionOptions参数说明
参数名称 | 参数类型 | 必填 | 参数描述 |
type | 否 | 默认包括组件新增和删除。 默认值:TransitionType.All 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 不指定Type时说明插入删除使用同一种效果。 | |
opacity | number | 否 | 设置组件转场时的透明度效果,为插入时起点和删除时终点的值。 默认值:1 取值范围: [0, 1] 从API version 9开始,该接口支持在ArkTS卡片中使用。 说明: 设置小于0的值时,按值为0处理;设置大于1的值时,按值为1处理。 |
translate | { x? : number | string, y? : number | string, z? : number | string } | 否 | 设置组件转场时的平移效果,为插入时起点和删除时终点的值。 -x:横向的平移距离。 -y:纵向的平移距离。 -z:竖向的平移距离。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
scale | { x? : number, y? : number, z? : number, centerX? : number | string, centerY? : number | string } | 否 | 设置组件转场时的缩放效果,为插入时起点和删除时终点的值。 -x:横向放大倍数(或缩小比例)。 -y:纵向放大倍数(或缩小比例)。 -z:竖向放大倍数(或缩小比例)。 - centerX、centerY指缩放中心点,centerX和centerY默认值是"50%"。 - 中心点为0时,默认的是组件的左上角。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
rotate | { x?: number, y?: number, z?: number, angle?: number | string, centerX?: number | string, centerY?: number | string } | 否 | 设置组件转场时的旋转效果,为插入时起点和删除时终点的值。 -x:横向的旋转向量。 -y:纵向的旋转向量。 -z:竖向的旋转向量。 - centerX,centerY指旋转中心点,centerX和centerY默认值是"50%"。 - 中心点为(0,0)时,默认的是组件的左上角。 从API version 9开始,该接口支持在ArkTS卡片中使用。 |
示例
// xxx.ets
@Entry
@Component
struct TransitionExample {
@State flag: boolean = true
@State show: string = 'show'
build() {
Column() {
Button(this.show).width(80).height(30).margin(30)
.onClick(() => {
// 点击Button控制Image的显示和消失
animateTo({ duration: 1000 }, () => {
if (this.flag) {
this.show = 'hide'
} else {
this.show = 'show'
}
this.flag = !this.flag
})
})
if (this.flag) {
// Image的显示和消失配置为不同的过渡效果
Image($r('app.media.testImg')).width(300).height(300)
.transition({ type: TransitionType.Insert, scale: { x: 0, y: 1.0 } })
.transition({ type: TransitionType.Delete, rotate: { angle: 180 } })
}
}.width('100%')
}
}
示意图:
图片完全显示时
图片消失时配置顺时针旋转180°的过渡效果:
图片完全消失时:
图片显示时配置横向放大一倍的过渡效果:
共享元素转场
当路由进行切换时,可以通过设置组件的 sharedTransition 属性将该元素标记为共享元素并设置对应的共享元素转场动效。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数 | 参数描述 |
sharedTransition | id: string, { duration?: number, curve?: Curve | string, delay?: number, motionPath?: { path: string, form?: number, to?: number, rotatable?: boolean }, zIndex?: number, type?: SharedTransitionEffectType} | 两个页面中id值相同且不为空字符串的组件即为共享元素,在页面转场时可显示共享元素转场动效。 - id:设置组件的id。 - duration:描述共享元素转场动效播放时长。 默认值:1000 单位:毫秒 取值范围:[0, +∞) 值为0时表示无动画。设置小于0的值时,按值为0处理。 - curve:默认曲线为Linear,有效值参见Curve说明。 - delay:用来描述共享元素转场动效延迟播放的时长。 默认值:0 单位:毫秒 取值范围:[0, +∞) 设置小于0的值时,按值为0处理。 - motionPath:运动路径信息,详细说明请参考路径动画。 - path:设置路径。 - from:设置起始值。 - to:设置终止值。 - rotatable:是否旋转。 - zIndex:设置Z轴。 - type:动画类型。 |
示例
示例代码为点击图片跳转页面时,显示共享元素图片的自定义转场动效。
// xxx.ets
@Entry
@Component
struct SharedTransitionExample {
@State active: boolean = false
build() {
Column() {
Navigator({ target: 'pages/PageB', type: NavigationType.Push }) {
Image($r('app.media.ic_health_heart')).width(50).height(50)
.sharedTransition('sharedImage', { duration: 800, curve: Curve.Linear, delay: 100 })
}.padding({ left: 20, top: 20 })
.onClick(() => {
this.active = true
})
}
}
}
// PageB.ets
@Entry
@Component
struct pageBExample {
build() {
Stack() {
Image($r('app.media.ic_health_heart')).width(150).height(150)
.sharedTransition('sharedImage', { duration: 800, curve: Curve.Linear, delay: 100 })
}.width('100%').height('100%')
}
}
路径动画
设置组件进行位移动画时的运动路径。
说明:
从API Version 7开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
属性
名称 | 参数类型 | 默认值 | 描述 |
motionPath | { path: string, from?: number, to?: number, rotatable?: boolean } 说明: path中支持使用start和end进行起点和终点的替代,如: ‘Mstart.x start.y L50 50 Lend.x end.y Z’,更多说明请参考绘制路径。 | { ‘’, 0.0, 1.0, false } | 设置组件的运动路径,入参说明如下: - path:位移动画的运动路径,使用svg路径字符串。 - from:运动路径的起点。 默认值:0.0 取值范围:[0, 1] 设置小于0的值时,按值为0处理。设置大于1的值时,按值为1处理。 - to:运动路径的终点。 默认值:1.0 取值范围:[0, 1] 设置小于0的值时,按值为0处理。设置大于1的值时,按值为1处理。 - rotatable:是否跟随路径进行旋转。 |
示例
// xxx.ets
@Entry
@Component
struct MotionPathExample {
@State toggle: boolean = true
build() {
Column() {
Button('click me').margin(50)
// 执行动画:从起点移动到(300,200),再到(300,500),再到终点
.motionPath({ path: 'Mstart.x start.y L300 200 L300 500 Lend.x end.y', from: 0.0, to: 1.0, rotatable: true })
.onClick(() => {
animateTo({ duration: 4000, curve: Curve.Linear }, () => {
this.toggle = !this.toggle // 通过this.toggle变化组件的位置
})
})
}.width('100%').height('100%').alignItems(this.toggle ? HorizontalAlign.Start : HorizontalAlign.Center)
}
}