华为仓颉鸿蒙HarmonyOS NEXT原生UI转场动画之组件内转场 (transition)

本文篇幅较长，建议点赞收藏，以免找不到哟(＾Ｕ＾)ノ~ＹＯ

组件内转场主要通过transition属性配置转场参数，在组件插入和删除时显示过渡动效，主要用于容器组件中的子组件插入和删除时，提升用户体验。

说明

transition暂不支持混合页面场景。

函数

transition()

public func transition(): This

设置组件插入显示和删除隐藏的过渡效果。

transition(TransitionEffect)

public func transition(effect: TransitionEffect): This

设置组件插入显示和删除隐藏的过渡效果。

说明

详细描述见TransitionEffect对象说明。

参数名	参数类型	必填	默认值	描述
animation	AnimateParam	是	-	组件插入显示和删除隐藏的过渡效果。

自定义类型说明

TransitionEffect

public class TransitionEffect {
        public static func opacity(number: Float64): TransitionEffect
        public static func translate(options: TranslateOptions): TransitionEffect
        public static func scale(options: ScaleOptions): TransitionEffect
        public static func rotate(options: RotateOptions): TransitionEffect
        public static func move(edge: TransitionEdge): TransitionEffect
        public static func asymmetric(appear: TransitionEffect, disappear: TransitionEffect): TransitionEffect
        public func combine(transitionEffect: TransitionEffect): TransitionEffect
        public func animation(param: AnimateParam): TransitionEffect
    }

转场效果类型。

opacity(Float64)

public static func opacity(number: Float64): TransitionEffect

设置组件转场时的透明度效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
number	Float64	是	-	透明度效果。取值范围： [0, 1]。

translate(TranslateOptions)

public static func translate(options: TranslateOptions): TransitionEffect

设置组件转场时的平移效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
options	TranslateOptions	是	-	平移效果。

scale(ScaleOptions)

public static func scale(options: ScaleOptions): TransitionEffect

设置组件转场时的缩放效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
options	ScaleOptions	是	-	缩放效果。

rotate(Float32)

public func rotate(rotateZ: Float32): This

设置组件转场时的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
rotateZ	Float32	是	-	旋转效果。

rotate(Int32)

public func rotate(rotateZ: Int32): This

设置组件转场时的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
rotateZ	Int32	是	-	旋转效果。

rotate(Float32,Float32,Float32,Float32,CJResource,CJResource)

public func rotate(
            x!: Float32,
            y!: Float32,
            z!: Float32,
            angle!: Float32,
            centerX!: CJResource,
            centerY!: CJResource
        ): This

设置组件转场时的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
x	Float32	是	-	x坐标。
y	Float32	是	-	y坐标。
z	Float32	是	-	z坐标 。
angle	Float32	是	-	角度。
centerX	CJResource	是	-	中心x坐标。
centerY	CJResource	是	-	中心y坐标。

rotate(Float32,Float32,Float32,Float32,Length,Length)

public func rotate(
            x!: Float32 = 0.0,
            y!: Float32 = 0.0,
            z!: Float32 = 0.0,
            angle!: Float32 = 0.0,
            centerX!: Length = 50.percent,
            centerY!: Length = 50.percent
        ): This

设置组件转场时的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
x	Float32	是	-	x坐标。
y	Float32	是	-	y坐标。
z	Float32	是	-	z坐标。
angle	Float32	是	-	角度。
centerX	Length	是	-	中心x坐标。
centerY	Length	是	-	中心y坐标。

rotate(RotateOptions)

public static func rotate(options: RotateOptions): TransitionEffect

设置组件转场时的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
options	RotateOptions	是	-	旋转效果。

rotateX(Float32)

public func rotateX(rotateVal: Float32): This

设置组件绕X坐标的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
rotateVal	Float32	是	-	旋转效果。

rotateX(Int32)

public func rotateX(rotateVal: Int32): This

设置组件绕X坐标的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
rotateVal	Int32	是	-	旋转效果。

rotateY(Int32)

public func rotateY(rotateVal: Int32): This

设置组件绕Y坐标的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
rotateVal	Int32	是	-	旋转效果。

rotateY(Float32)

public func rotateY(rotateVal: Float32): This

设置组件绕Y坐标的旋转效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
rotateVal	Float32	是	-	旋转效果。

move(TransitionEdge)

public static func move(edge: TransitionEdge): TransitionEffect

指定组件转场时从屏幕边缘滑入和滑出的效果，本质为平移效果，为插入时起点和删除时终点的值。

参数名	参数类型	必填	默认值	描述
options	TransitionEdge	是	-	转场时从屏幕边缘滑入和滑出的效。

asymmetric(TransitionEdge)

public static func asymmetric(appear: TransitionEffect, disappear: TransitionEffect): TransitionEffect

指定非对称的转场效果。

参数名	参数类型	必填	默认值	描述
appear	TransitionEffect	是	-	指定出现的转场效果。
disappear	TransitionEffect	是	-	指定消失的转场效果。

combine(TransitionEffect)

public func combine(transitionEffect: TransitionEffect): TransitionEffect

对TransitionEffect进行链式组合，以形成包含多种转场效果的TransitionEffect。

参数名	参数类型	必填	默认值	描述
transitionEffect	TransitionEffect	是	-	TransitionEffect 对象。

animation(AnimateParam)

public func animation(param: AnimateParam): TransitionEffect

指定该TransitionEffect的动画参数。

参数名	参数类型	必填	默认值	描述
transitionEffect	TransitionEffect	是	-	动画参数。

上述提供的静态函数用于构造TransitionEffect对象，而非静态函数作用于构造好的TransitionEffect对象，以指定多种转场效果的组合效果和动画参数。

此外TransitionEffect提供了一些转场效果的静态成员变量：

静态成员名称	参数描述
IDENTITY	禁用转场效果。
OPACITY	指定透明度为0的转场效果。即相当于TransitionEffect.opacity(0)
SLIDE	指定出现时从左侧滑入、消失时从右侧滑出的转场效果。即相当于TransitionEffect.asymmetric(TransitionEffect.move(TransitionEdge.START), TransitionEffect.move(TransitionEdge.END))
SLIDE_SWITCH	指定出现时从右先缩小再放大侧滑入、消失时从左侧先缩小再放大滑出的转场效果。动画时长600ms,指定动画曲线曲线cubicBezierCurve(0.24, 0.0, 0.50, 1.0)，最小缩放比例为0.8。

说明

TransitionEffect可通过combine函数实现多个转场效果的组合，可以为每个效果分别指定animation参数，且前一效果的animation的参数也可适用于后一效果。例如，TransitionEffect.OPACITY.animation(AnimateParam(duration: 1000)).combine(TransitionEffect.translate(TranslateOptions(x: Length(100.0))))，则时长为1000ms的动画参数对OPACITY和translate均生效。
    动画参数的生效顺序为：本TransitionEffect指定的animation参数 > 前面的TransitionEffect指定的animation参数 > 触发该组件出现消失的animateTo中的动画参数。
    如果未使用animateTo触发转场动画且TransitionEffect中也无animation参数，则该组件直接出现或者消失。
    TransitionEffect中指定的属性值如与默认值相同，则该属性不会产生转场动画。如TransitionEffect.opacity(1.0).animation(AnimateParam(duration: 1000))，由于opacity默认值也为1，未产生透明度动画，该组件直接出现或者消失。

TranslateOptions

init(Length, Length, Length)
    public TranslateOptions(
        x!: Length = 0.0.vp,
        y!: Length = 0.0.vp,
        z!: Length = 0.0.vp
    )

参数名	参数类型	必填	默认值	描述
x	Length	否	0.0.vp	x轴的平移距离。
y	Length	否	0.0.vp	y轴的平移距离。
z	Length	否	0.0.vp	z轴的平移距离。

创建一个TranslateOptions类型的对象。

ScaleOptions

init(Float32, Float32, Float32, Length, Length)
    public init(
        x!: Float32 = 0.0,
        y!: Float32 = 0.0,
        z!: Float32 = 0.0,
        centerX!: Length = 50.percent,
        centerY!: Length = 50.percent
    )

参数名	参数类型	必填	默认值	描述
x	Float32	否	0.0	x轴的缩放倍数。x>1时以x轴方向放大，0<x<1时以x轴方向缩小，x<0时沿x轴反向并缩放。
y	Float32	否	0.0	y轴的缩放倍数。y>1时以y轴方向放大，0<y<1时以y轴方向缩小，y<0时沿y轴反向并缩放。
z	Float32	否	0.0	z轴的缩放倍数。z>1时以z轴方向放大，0<z<1时以z轴方向缩小，z<0时沿z轴反向并缩放。
centerX	Length	否	50.percent	变换中心点x轴坐标。
centerY	Length	否	50.percent	变换中心点y轴坐标。

创建一个ScaleOptions类型的对象。

RotateOptions

init(Float32，Float32, Float32, Float32, Length, Length，Float32)

public init(
        angle: Float32,
        x!: Float32 = 0.0,
        y!: Float32 = 0.0,
        z!: Float32 = 0.0,
        centerX!: Length = 50.percent,
        centerY!: Length = 50.percent,
        centerZ!: Length = Length(0),
        perspective!: Float32 = 0.0
    )

参数名	参数类型	必填	默认值	描述
angle	Float32	是	-	旋转角度。取值为正时相对于旋转轴方向顺时针转动，取值为负时相对于旋转轴方向逆时针转动。取值可为String类型，如'90deg'。
x	Float32	否	0.0	旋转轴向量x坐标。
y	Float32	否	0.0	旋转轴向量y坐标。
z	Float32	否	0.0	旋转轴向量z坐标。
centerX	Length	否	50.percent	变换中心点x轴坐标。
centerY	Length	否	50.percent	变换中心点y轴坐标。
centerZ	Length	否	0.vp	z轴锚点，即3D旋转中心点的z轴分量。
perspective	Float32	否	0.0	视距，即视点到z=0平面的距离。旋转轴和旋转中心点都基于坐标系设定，组件发生位移时，坐标系不会随之移动。

创建一个ScaleOptions类型的对象。

枚举类型说明

TransitionEdge

枚举值	描述
TOP	窗口的上边缘
BOTTOM	窗口的下边缘
START	窗口的左边缘
END	窗口的右边缘

示例

下面是一个出现消失使用同一TransitionEffect（出现和消失互为逆过程）的示例。

@Entry
    @Component
    class MyView {
        @State var flag = true
        @State var show = "show"
        func build() {
            Column {
                Button(this.show).onClick {
                    evt => AppLog.info("Hello Cangjie")
                    if (this.flag) {
                        this.show = "hide"
                    } else {
                        this.show = "show"
                    }
                    this.flag = !this.flag
                }.width(800.px).height(400.px)
    
                if (this.flag) {
                    // Button的显示和消失配置为相同的过渡效果（出现和消失互为逆过程）
                    // 出现时从指定的透明度为0、绕z轴旋转180°的状态，变为默认的透明度为1、旋转角为0的状态，透明度与旋转动画时长都为2000ms
                    // 消失时从默认的透明度为1、旋转角为0的状态，变为指定的透明度为0、绕z轴旋转180°的状态，透明度与旋转动画时长都为2000ms
                    Button("abc").width(800.px).height(400.px)
                    .transition(TransitionEffect.OPACITY.animation(AnimateParam(duration: 2000, curve: Curve.Ease)).combine(
                        TransitionEffect.rotate(component.RotateOptions(180.0, z: 1.0))
                    ))
                }
            }
        }
    }

下面是一个出现和消失使用不同TransitionEffect的示例。

@Entry
    @Component
    class MyView {
        @State var flag = true
        @State var show = "show"
        func build() {
            Column {
                Button(this.show).onClick {
                    evt => AppLog.info("Hello Cangjie")
                    if (this.flag) {
                        this.show = "hide"
                    } else {
                        this.show = "show"
                    }
                    this.flag = !this.flag
                }.width(800.px).height(400.px)
    
                if (this.flag) {
                    // 出现时做从x方向和y方向scale都为0变为默认的x方向和y方向scale都为1的动画，该动画时长为animateTo中指定的2000ms
                    // 消失时无转场效果
                    Button("abc").width(800.px).height(400.px).transition(
                        TransitionEffect.asymmetric(
                            TransitionEffect.scale(ScaleOptions()),
                            TransitionEffect.IDENTITY
                        ).animation(AnimateParam(duration: 2000, curve: Curve.Ease))
                    )
                }
            }
        }
    }

如对您有帮助，帮忙点个“在看 、关注” 让更多的人受益~！

技术交流群可加wx“LB-9191”备注cangjie