# 组件内转场 (transition)

> phone 12+ | 2in1 13+ | tablet 12+ | tv 19+ | wearable 18+

组件内转场主要通过transition属性配置转场参数，在容器组件的子组件插入和删除时显示过渡动效，以提升用户体验。组件内转场详细的使用方法请参考[转场动画开发指导](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-enter-exit-transition)。
> 说明
>
> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
>
> 当前有两种方式触发组件的transition：
>
> 1. 当组件插入或删除时（如if条件改变、ForEach新增删除组件），会递归地触发所有新插入/删除的组件的transition效果。
> 2. 当组件[visibility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-visibility#visibility)属性在可见和不可见（Visibility.Hidden或Visibility.None）之间改变时，只触发该组件的transition效果。在Visibility.Visible与Visibility.None之间切换时，若直接设置为Visibility.None，会导致组件布局大小为0，此时无法观察到transition效果。而当在动画中修改visibility属性为Visibility.None时，组件布局为0的变化将带动画效果。此时会呈现transition与布局动画的叠加效果，形成双动画的复合表现。具体效果可参考[示例4](#示例4visibility切换时的双动画复合效果)。

## transition

transition(value: TransitionOptions | TransitionEffect): T

组件插入显示和删除隐藏的过渡效果。可通过组件插入/删除（如if条件改变、ForEach新增删除）或visibility属性在可见与不可见之间切换来触发。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:----|:------------------------------------------------------------------------------------------------------------|:-|:----------------------------------------------------------------------------------------------------------------------------------|
|value|[TransitionOptions](#transitionoptionsdeprecated)^(deprecated)^ | [TransitionEffect](#transitioneffect10对象说明)|是|设置组件插入显示和删除隐藏的过渡效果。 **说明：** 详细描述见[TransitionOptions](#transitionoptionsdeprecated)和[TransitionEffect](#transitioneffect10对象说明)对象说明。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## transition^12+^

transition(effect: TransitionEffect, onFinish: Optional<TransitionFinishCallback>): T

组件插入显示和删除隐藏的过渡效果。同[transition](#transition)相比，增加了转场动画结束的回调。
> 说明
>
> 从API version 20开始，该接口支持在[attributeModifier](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-attribute-modifier#attributemodifier)中调用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。

**参数：**

|参数名|类型|必填|说明|
|:-------|:----------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------|
|effect|[TransitionEffect](#transitioneffect10对象说明)|是|设置组件插入显示和删除隐藏的过渡效果。|
|onFinish|Optional<[TransitionFinishCallback](#transitionfinishcallback12)>|是|转场动画结束回调，具体生效条件见[TransitionFinishCallback](#transitionfinishcallback12)说明。传入undefined时，不注册转场动画结束回调，转场动画结束后不会收到回调通知。|

**返回值：**

|类型|说明|
|:-|:-------------|
|T|返回当前组件，用于链式调用。|

## TransitionEdge^10+^

转场边缘类型。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|值|说明|
|:-----|:-|:-------------------------|
|TOP|0|窗口的上边缘。|
|BOTTOM|1|窗口的下边缘。|
|START|2|窗口的起始边缘，LTR时为左边缘，RTL时为右边缘。|
|END|3|窗口的终止边缘，LTR时为右边缘，RTL时为左边缘。|

## TransitionEffect^10+^对象说明

TransitionEffect以函数的形式指定转场效果。提供了以下接口：

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

### 属性

|名称|类型|只读|可选|说明|
|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|IDENTITY|[TransitionEffect](#transitioneffect10对象说明)<"identity">|是|否|禁用转场效果。如果在动画范围内触发组件的上下树或可见性改变，而该组件未配置transition，会给该组件加上默认的透明度转场效果（即TransitionEffect.OPACITY），如不需要此默认效果，可配置IDENTITY来禁用，使该组件直接出现或消失。|
|OPACITY|[TransitionEffect](#transitioneffect10对象说明)<"opacity">|是|否|为组件添加透明度转场效果，出现时透明度从0到1、消失时透明度从1到0，相当于TransitionEffect.opacity(0)。|
|SLIDE|[TransitionEffect](#transitioneffect10对象说明)<"asymmetric", { appear: [TransitionEffect](#transitioneffect10对象说明)<"move", [TransitionEdge](#transitionedge10)>; disappear: [TransitionEffect](#transitioneffect10对象说明)<"move", [TransitionEdge](#transitionedge10)>; }>|是|否|相当于TransitionEffect.asymmetric(TransitionEffect.move(TransitionEdge.START), TransitionEffect.move(TransitionEdge.END))。从START边滑入，END边滑出。即在LTR模式下，从左侧滑入，右侧滑出；在RTL模式下，从右侧滑入，左侧滑出。|
|SLIDE_SWITCH|[TransitionEffect](#transitioneffect10对象说明)<"slideSwitch">|是|否|指定出现时从右侧先缩小再放大滑入、消失时从左侧先缩小再放大滑出的转场效果。自带动画参数，也可通过.animation()方法指定自定义动画参数来覆盖自带参数，自带的动画参数时长600ms，指定动画曲线cubicBezierCurve(0.24, 0.0, 0.50, 1.0)，最小缩放比例为0.85。|

> 说明
>
> 1. TransitionEffect可通过combine函数实现多个转场效果的组合，可以为每个效果分别指定animation参数，且前一效果的animation的参数也可适用于后一效果。例如，TransitionEffect.OPACITY.animation({duration: 1000}).combine(TransitionEffect.translate({x: 100}))，则时长为1000ms的动画参数对OPACITY和translate均生效。
> 2. 动画参数的生效顺序为：本TransitionEffect指定的animation参数 > 前面的TransitionEffect指定的animation参数 > 触发该组件出现消失的animateTo中的动画参数。
> 3. 如果未使用animateTo触发转场动画且TransitionEffect中也无animation参数，则该组件直接出现或者消失。
> 4. TransitionEffect中指定的属性值如与默认值相同，则该属性不会产生转场动画。如TransitionEffect.opacity(1).animation({duration:1000})，由于opacity默认值也为1，未产生透明度动画，该组件直接出现或者消失。
> 5. 更详细的关于scale、rotate效果的介绍可参考[图形变换](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-transformation)。
> 6. 如果在动画范围（[animateTo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext#animateto)、[animation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-animatorproperty)）内触发组件的上下树或可见性（[visibility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-visibility#visibility)）改变，而该子树的根组件没有配置transition，会给该组件加上默认透明度转场，即TransitionEffect.OPACITY，动画参数跟随所处动画环境的参数。如不需要可通过主动配置TransitionEffect.IDENTITY来禁用，使该组件直接出现或消失。
> 7. 当通过删除整棵子树的方式触发消失转场，如需看到完整的消失转场过程，需要保证被删除子树的根组件有充足的消失转场时间，见示例3。

### translate^10+^

translate(options: TranslateOptions): TransitionEffect<"translate">

设置组件转场时的平移效果。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-------------------------------------------------------------|
|options|[TranslateOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-transformation#translateoptions对象说明)|是|组件转场时的平移效果，为插入时起点和删除时终点的值。 -x：横向的平移距离。 -y：纵向的平移距离。 -z：竖向的平移距离。|

**返回值：**

|类型|说明|
|:-------------------------------------------------------|:--------|
|[TransitionEffect](#transitioneffect10对象说明)<"translate">|当前动画平移效果。|

### rotate^10+^

rotate(options: RotateOptions): TransitionEffect<"rotate">

设置组件转场时的旋转效果。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:------------------------------------------------------------------------------------------------------------------------------------------|:-|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|options|[RotateOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-transformation#rotateoptions对象说明)|是|组件转场时的旋转效果，为插入时起点和删除时终点的值。 -angle：旋转角度，单位为度（°），决定绕旋转轴的旋转幅度。 -x：横向的旋转向量分量。 -y：纵向的旋转向量分量。 -z：竖向的旋转向量分量。 - centerX、centerY指旋转中心点，centerX和centerY默认值是"50%"，数值类型单位为vp，即默认以组件的中心点为旋转中心点。字符串格式支持百分比（如"50%"）。 - 中心点为(0, 0)代表组件的左上角。 - 设置centerX、centerY为非法字符串时（例如，"illegalString"），默认值为"0"。 -centerZ指z轴锚点，即3D旋转中心点的z轴分量，centerZ默认值是0。 -perspective指视距，不支持perspective属性做转场动画。|

**返回值：**

|类型|说明|
|:----------------------------------------------------|:--------|
|[TransitionEffect](#transitioneffect10对象说明)<"rotate">|当前动画旋转效果。|

### scale^10+^

scale(options: ScaleOptions): TransitionEffect<"scale">

设置组件转场时的缩放效果。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:------|:----------------------------------------------------------------------------------------------------------------------------------------|:-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|options|[ScaleOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-transformation#scaleoptions对象说明)|是|组件转场时的缩放效果，为插入时起点和删除时终点的值。设置的缩放值在组件当前的scale属性上进行乘法叠加，如组件当前scale值为0.8，当转场缩放值设置为0.5时，组件入场动画的缩放值将从0.8×0.5=0.4开始执行。 - x：横向放大倍数（或缩小比例）。 - y：纵向放大倍数（或缩小比例）。 - z：当前为二维显示，该参数无效。 - centerX、centerY指缩放中心点，centerX和centerY默认值是"50%"，即默认以组件的中心点为缩放中心点。 - 中心点为(0, 0)代表组件的左上角。 **说明：** 设置centerX、centerY为非法字符串时（例如，"illegalString"），默认值为"0"。|

**返回值：**

|类型|说明|
|:---------------------------------------------------|:--------|
|[TransitionEffect](#transitioneffect10对象说明)<"scale">|当前动画缩放效果。|

### opacity^10+^

opacity(alpha: number): TransitionEffect<"opacity">

设置组件转场时的透明度效果。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----|:-|:------------------------------------------------------------------------------------------------------------------|
|alpha|number|是|组件转场时的透明度效果，为插入时起点和删除时终点的值。 取值范围：[0, 1] **说明：** 设置小于0的非法值按0处理，大于1的非法值按1处理。当alpha取值为1时（与默认值相同），不产生透明度转场动画，组件直接出现或消失。|

**返回值：**

|类型|说明|
|:-----------------------------------------------------|:---------------------------------------------------|
|[TransitionEffect](#transitioneffect10对象说明)<"opacity">|返回表示透明度转场效果的TransitionEffect对象，用于配置组件出现和消失时的透明度过渡动画。|

### move^10+^

move(edge: TransitionEdge): TransitionEffect<"move">

设置组件转场时从窗口边缘滑入和滑出的效果。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:---|:----------------------------------|:-|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|edge|[TransitionEdge](#transitionedge10)|是|组件转场时从窗口边缘滑入和滑出的效果，本质为平移效果，为插入时起点和删除时终点的值。与translate不同的是，move通过TransitionEdge自动根据窗口边缘位置计算偏移量（含RTL/LTR方向适配），无需手动指定具体偏移值，适用于从窗口边缘滑入滑出的场景；translate需手动指定偏移值，适用于需要自定义偏移方向和距离的场景。|

**返回值：**

|类型|说明|
|:--------------------------------------------------|:-----------------|
|[TransitionEffect](#transitioneffect10对象说明)<"move">|当前动画从窗口边缘滑入和滑出的效果。|

### asymmetric^10+^

asymmetric(appear: TransitionEffect, disappear: TransitionEffect): TransitionEffect<"asymmetric">

设置非对称的转场效果，即出现、消失为两套独立不同的动画，效果不互为逆过程。适用于需要出现和消失采用不同动画策略的场景。具体效果可参考[示例2](#示例2使用不同接口实现图片出现消失)。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:--------|:------------------------------------------|:-|:----------------------------------------------------------------|
|appear|[TransitionEffect](#transitioneffect10对象说明)|是|指定出现的转场效果。 如不通过asymmetric函数构造TransitionEffect，则表明该效果在组件出现和消失时均生效。|
|disappear|[TransitionEffect](#transitioneffect10对象说明)|是|指定消失的转场效果。 如不通过asymmetric函数构造TransitionEffect，则表明该效果在组件出现和消失时均生效。|

**返回值：**

|类型|说明|
|:--------------------------------------------------------|:-----------------------------------------------|
|[TransitionEffect](#transitioneffect10对象说明)<"asymmetric">|返回表示非对称转场效果的TransitionEffect对象，出现和消失分别使用不同的转场动画。|

### constructor^10+^

constructor(type: Type, effect: Effect)

构造TransitionEffect对象。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-----|:---------------------------------------------------------------------------------------------------------|:-|:-------------------------------------------------------------------------------|
|type|[Type](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#transitiontype)|是|转场类型，指定该转场效果生效的场景。默认值：TransitionType.All，即插入删除都生效。不指定type时默认为TransitionType.All。|
|effect|[Effect](#transitioneffect10对象说明)|是|转场效果配置，用于指定具体的转场动画效果，包括透明度、平移、旋转、缩放等转场效果的参数设置。|

### combine^10+^

combine(transitionEffect: TransitionEffect): TransitionEffect

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

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:---------------|:------------------------------------------|:-|:--------|
|transitionEffect|[TransitionEffect](#transitioneffect10对象说明)|是|被组合的过渡效果。|

**返回值：**

|类型|说明|
|:------------------------------------------|:------|
|[TransitionEffect](#transitioneffect10对象说明)|组合过渡效果。|

### animation^10+^

animation(value: AnimateParam): TransitionEffect

指定该TransitionEffect的动画参数。

**元服务API：** 从API version 11开始，该接口支持在元服务中使用。

**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:----|:-----------------------------------------------------------------------------------------------------------------------|:-|:--------------------------------------------------------------------------------------------------------------------------------|
|value|[AnimateParam](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-explicit-animation#animateparam对象说明)|是|动画参数。 该参数仅用于指定动画参数，其入参AnimateParam的onFinish回调不生效。 如果通过combine进行TransitionEffect的组合，前一TransitionEffect的动画参数也可用于后一TransitionEffect。|

**返回值：**

|类型|说明|
|:------------------------------------------|:---------------------------------------------|
|[TransitionEffect](#transitioneffect10对象说明)|返回配置了指定动画参数的TransitionEffect对象，该动画参数将在转场效果中生效。|

## TransitionFinishCallback^12+^

type TransitionFinishCallback = (transitionIn: boolean) => void

定义组件转场动画结束回调的类型。

**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。

**元服务API：** 从API version 12开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

**参数：**

|参数名|类型|必填|说明|
|:-----------|:------|:-|:-------------------------------------------|
|transitionIn|boolean|是|转场动画的结束回调类型。 true表示出现动画结束回调，false表示消失动画结束回调。|

> 说明
>
> 1. 当通过触发一棵子树的上下树，进而递归地触发出现消失转场时，只能保证根组件的消失动画结束回调能被调用。如果子组件的消失动画结束回调时间晚于根组件的消失动画结束回调，由于整棵子树已被销毁，子组件的结束回调不会被调用。
> 2. 当同一组件的最后一个同类型（即出现或者消失）的动画结束后，才会调用结束回调。即如果反复触发出现消失动画（例如通过Visibility触发），只有最后一次的出现消失的结束回调才会被调用。

## TransitionOptions^(deprecated)^

TransitionOptions通过指定结构体内的参数来指定转场效果。
> 说明
>
> 从API version 7开始支持，从API version 10开始废弃，建议使用[TransitionEffect](#transitioneffect10对象说明)替代。

**系统能力：** SystemCapability.ArkUI.ArkUI.Full

|名称|类型|只读|可选|说明|
|:--------|:------------------------------------------------------------------------------------------------------------------------------------------------|:-|:-|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|type|[TransitionType](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-appendix-enums#transitiontype)|否|是|指定该转场效果生效的场景。 默认值：TransitionType.All **说明：** 不指定type时默认为TransitionType.All，即插入删除都生效。|
|opacity|number|否|是|设置组件转场时的透明度效果，为插入时起点和删除时终点的值。当需要实现淡入淡出过渡效果时设置此属性；未设置时，若同时未设置其他转场效果，默认产生透明度转场效果（相当于opacity为0），若已设置其他转场效果，则不产生透明度转场效果。 取值范围： [0, 1] **说明：** 设置小于0的非法值时，按0处理；设置大于1的非法值时，按1处理。|
|translate|[TranslateOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-transformation#translateoptions对象说明)|否|是|设置组件转场时的平移效果，为插入时起点和删除时终点的值。 -x：横向的平移距离。 -y：纵向的平移距离。 -z：深度方向的平移距离。|
|scale|[ScaleOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-transformation#scaleoptions对象说明)|否|是|设置组件转场时的缩放效果，为插入时起点和删除时终点的值。设置的缩放值在组件当前的scale属性上进行乘法叠加，如组件当前scale值为0.8，当转场缩放值设置为0.5时，组件入场动画的缩放值将从0.8×0.5=0.4开始执行。 -x：横向放大倍数（或缩小比例）。 -y：纵向放大倍数（或缩小比例）。 -z：当前为二维显示，该参数无效。 - centerX、centerY指缩放中心点，centerX和centerY默认值是"50%"，即默认以组件的中心点为缩放中心点。 - 中心点为(0, 0)代表组件的左上角。 **说明：** 设置centerX、centerY为非法字符串时（例如，"illegalString"），默认值为"0"。|
|rotate|[RotateOptions](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-transformation#rotateoptions对象说明)|否|是|设置组件转场时的旋转效果，为插入时起点和删除时终点的值。 -x：横向的旋转向量分量。 -y：纵向的旋转向量分量。 -z：竖向的旋转向量分量。 - centerX、centerY指旋转中心点，centerX和centerY默认值是"50%"，即默认以组件的中心点为旋转中心点。字符串格式支持百分比（如"50%"）。 - 中心点为(0, 0)代表组件的左上角。 - 设置centerX、centerY为非法字符串时（例如，"illegalString"），默认值为"0"。|

> 说明
>
> 1. 当使用TransitionOptions类型的入参指定转场效果时，**必须** 配合[animateTo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext#animateto)使用才有动画效果，动效时长、曲线、延迟跟随animateTo中的配置。
> 2. 当使用TransitionOptions作为入参，且不指定除type外的任何参数时，此时相当于指定了透明度的转场效果。例如，指定{type: TransitionType.Insert}相当于指定了{type: TransitionType.Insert, opacity: 0}的转场效果。而指定了具体效果时，则不会添加默认的透明度转场效果。

## 示例

### 示例1（使用同一接口实现图片出现消失）

该示例主要演示如何通过同一[TransitionEffect](#transitioneffect10对象说明)来实现图片的出现与消失，出现和消失互为逆过程。

```ts
// xxx.ets
@Entry
@Component
struct TransitionEffectExample1 {
  @State flag: boolean = true;
  @State show: string = 'show';

  build() {
    Column() {
      Button(this.show).width(80).height(30).margin(30)
        .onClick(() => {
          // 点击Button控制Image的显示和消失
          if (this.flag) {
            this.show = 'hide';
          } else {
            this.show = 'show';
          }
          this.flag = !this.flag;
        })
      if (this.flag) {
        // Image的显示和消失配置为相同的过渡效果（出现和消失互为逆过程）
        // 出现时从指定的透明度为0、绕z轴旋转180°的状态，变为默认的透明度为1、旋转角为0的状态，透明度与旋转动画时长都为2000ms
        // 消失时从默认的透明度为1、旋转角为0的状态，变为指定的透明度为0、绕z轴旋转180°的状态，透明度与旋转动画时长都为2000ms
        // $r('app.media.testImg')需要替换为开发者所需的图像资源文件。
        Image($r('app.media.testImg')).width(200).height(200)
          .transition(TransitionEffect.OPACITY.animation({ duration: 2000, curve: Curve.Ease }).combine(
            TransitionEffect.rotate({ z: 1, angle: 180 })
          ))
      }
    }.width('100%')
  }
}
```

示意图：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/87/v3/tKe6yZfETyKFxR_JUFsDOg/zh-cn_image_0000002747292999.gif?HW-CC-KV=V1&HW-CC-Date=20260909T145012Z&HW-CC-Expire=31536000000&HW-CC-Sign=B3232DF6A1C687BAFD1818DEC61612A7A36E5B742F4AAC41997D04A0DBA962DB)

### 示例2（使用不同接口实现图片出现消失）

该示例主要演示使用不同[TransitionEffect](#transitioneffect10对象说明)来实现图片的出现和消失。

```ts
// xxx.ets
@Entry
@Component
struct TransitionEffectExample2 {
  @State flag: boolean = true;
  @State show: string = 'show';

  build() {
    Column() {
      Button(this.show).width(80).height(30).margin(30)
        .onClick(() => {
          // 点击Button控制Image的显示和消失
          if (this.flag) {
            this.show = 'hide';
          } else {
            this.show = 'show';
          }
          this.getUIContext().animateTo({ duration: 2000 }, () => {
            // 第一张图的TransitionEffect包含了animation，transition的动画参数由TransitionEffect指定
            // 第二张图的TransitionEffect不包含animation，transition的动画参数由animateTo指定
            this.flag = !this.flag;
          });
        })
      if (this.flag) {
        // Image的显示和消失配置为不同的过渡效果
        // 出现时做从指定的透明度为0变为默认的透明度1的动画，该动画时长为1000ms，以及做从指定的绕z轴旋转180°变为默认的旋转角为0的动画，该动画1000ms后播放，时长为1000ms
        // 消失时做从默认的透明度为1变为指定的透明度0的动画，该动画1000ms后播放，时长为1000ms，以及做从默认的旋转角0变为指定的绕z轴旋转180°的动画，该动画时长为1000ms
        // $r('app.media.testImg')需要替换为开发者所需的图像资源文件。
        Image($r('app.media.testImg')).width(200).height(200)
          .transition(
            TransitionEffect.asymmetric(
              TransitionEffect.OPACITY.animation({ duration: 1000 }).combine(
              TransitionEffect.rotate({ z: 1, angle: 180 }).animation({ delay: 1000, duration: 1000 }))
              ,
              TransitionEffect.OPACITY.animation({ delay: 1000, duration: 1000 }).combine(
              TransitionEffect.rotate({ z: 1, angle: 180 }).animation({ duration: 1000 }))
            )
          )
        // 出现时做从x方向和y方向scale都为0变为默认的x方向和y方向scale都为1的动画，该动画时长为animateTo中指定的2000ms
        // 消失时无转场效果
        // $r('app.media.testImg')需要替换为开发者所需的图像资源文件。
        Image($r('app.media.testImg')).width(200).height(200).margin({ top: 100 })
          .transition(
            TransitionEffect.asymmetric(
              TransitionEffect.scale({ x: 0, y: 0 }),
              TransitionEffect.IDENTITY
            )
          )
      }
    }.width('100%')
  }
}
```

示意图：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b5/v3/TQ-33H1KQ_OtzHEEGzAryw/zh-cn_image_0000002747212915.gif?HW-CC-KV=V1&HW-CC-Date=20260909T145012Z&HW-CC-Expire=31536000000&HW-CC-Sign=16D429C54E98D86C17402963257203B3111FEA5C6734A4E5EC524FBEF44A2CEC)

### 示例3（设置父子组件为transition）

该示例主要演示通过父子组件都配置[transition](#transition)来实现图片的出现和消失。

```ts
// xxx.ets
@Entry
@Component
struct TransitionEffectExample3 {
  @State flag: boolean = true;
  @State show: string = 'show';

  build() {
    Column() {
      Button(this.show).width(80).height(30).margin(30)
        .onClick(() => {
          // 点击Button控制Image的显示和消失
          if (this.flag) {
            this.show = 'hide';
          } else {
            this.show = 'show';
          }
          this.flag = !this.flag;
        })
      if (this.flag) {
        // 当flag条件改变时，会触发id为"column1"、"image1"、"image2"的transition动画。
        // id为"column1"的组件是这棵新出现/消失的子树的根节点。
        Column() {
          Row() {
            // $r('app.media.testImg')需要替换为开发者所需的图像资源文件。
            Image($r('app.media.testImg')).width(150).height(150).id('image1')
              .transition(TransitionEffect.OPACITY.animation({ duration: 1000 }))
          }

          // $r('app.media.testImg')需要替换为开发者所需的图像资源文件。
          Image($r('app.media.testImg'))
            .width(150)
            .height(150)
            .margin({ top: 50 })
            .id('image2')
            .transition(TransitionEffect.scale({ x: 0, y: 0 }).animation({ duration: 1000 }))
          Text('view').margin({ top: 50 })
        }
        .id('column1')
        // 根组件使用opacity(0.99)而非1，避免属性值等于默认值导致转场动画不触发
        .transition(TransitionEffect.opacity(0.99).animation({ duration: 1000 }),
          // 结束回调设置在消失的第一层节点上，确保能有消失的结束回调
          (transitionIn: boolean) => {
            console.info("transition finish, transitionIn:" + transitionIn);
          }
        )
      }
    }.width('100%')
  }
}
```

示意图：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/fd/v3/mDZ765pSTOqhH0iwEkLoaw/zh-cn_image_0000002717772980.gif?HW-CC-KV=V1&HW-CC-Date=20260909T145012Z&HW-CC-Expire=31536000000&HW-CC-Sign=01DCF5A5B290AB27A4974B835B92CD963753FC2231558D28CF37D69776316763)

### 示例4（visibility切换时的双动画复合效果）

该示例演示当[visibility](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-attributes-visibility#visibility)在Visibility.Visible与Visibility.None之间切换时，[transition](#transition)动画与布局动画叠加形成双动画复合表现的效果。

```ts
// xxx.ets
@Entry
@Component
struct TransitionVisibilityExample {
  @State isVisible: boolean = true;

  build() {
    Column() {
      Button('toggle visibility').width(150).height(30).margin(30)
        .onClick(() => {
          this.getUIContext()?.animateTo({ duration: 1000 }, () => {
            this.isVisible = !this.isVisible;
          });
        })
      Column() {
        Text('Hello World')
          .fontSize(20)
          .fontColor(Color.White)
      }
      .width(200)
      .height(100)
      .backgroundColor('#317AF7')
      .justifyContent(FlexAlign.Center)
      .transition(TransitionEffect.OPACITY.animation({ duration: 1000 }))
      .visibility(this.isVisible ? Visibility.Visible : Visibility.None)
    }.width('100%').height('100%').justifyContent(FlexAlign.Center)
  }
}
```

示意图：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d3/v3/vzq-RfdETDC_18iw73GHaA/zh-cn_image_0000002717613048.gif?HW-CC-KV=V1&HW-CC-Date=20260909T145012Z&HW-CC-Expire=31536000000&HW-CC-Sign=BF7D218FB3D3072FED6D914824E6C7FE0865AA001EAB20E49596F153BD1061C4)