1# Component Transition (transition) 2 3You can configure the component transition animations through the **transition** attribute for when a component is inserted or deleted. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Attributes 11 12 13| Name| Type| Description| 14| -------- | -------- | -------- | 15| transition | [TransitionOptions](#transitionoptionsdeprecated)<sup>(deprecated)</sup> \| [TransitionEffect](#transitioneffect10)<sup>10+</sup> | Transition effects when the component is inserted, displayed, deleted, or hidden.<br>Since API version 10, this API is supported in ArkTS widgets.<br>**NOTE**<br>For details, see [TransitionOptions](#transitionoptionsdeprecated) and [TransitionEffect](#transitioneffect10).| 16 17 18## TransitionEffect<sup>10+</sup> 19Defines the transition effect by using the provided APIs, as listed below. 20| API| Type| Static Function| Description| 21| -------- | ---------- | -------- | -------- | 22| opacity | number | Yes| Opacity of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>Value range: [0, 1]<br>Since API version 10, this API is supported in ArkTS widgets.<br>**NOTE**<br>A value less than 0 or greater than 1 evaluates to the value **1**.| 23| translate | {<br>x? : number \| string,<br>y? : number \| string,<br>z? : number \| string<br>} | Yes| Translation of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>-**x**: distance to translate along the x-axis.<br>-**y**: distance to translate along the y-axis.<br>-**z**: distance to translate along the z-axis.<br>Since API version 10, this API is supported in ArkTS widgets.| 24| scale | [ScaleOptions](ts-universal-attributes-transformation.md#scaleoptions)| Yes| Scaling of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>- **x**: scale factor along the x-axis.<br>- **y**: scale factor along the y-axis.<br>- **z**: scale factor along the z-axis (not effective for the current 2D graphics).<br>- **centerX** and **centerY**: scale center point. The default values are both **"50%"**, indicating that the center point of the page.<br>- If the center point is (0, 0), it refers to the upper left corner of the component.<br>Since API version 10, this API is supported in ArkTS widgets.| 25| rotate | [RotateOptions](ts-universal-attributes-transformation.md#rotateoptions) | Yes| Rotation of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>- **x**: X-component of the rotation vector.<br>- **y**: Y-component of the rotation vector.<br>- **z**: Z-component of the rotation vector.<br>- **centerX** and **centerY**: rotation center point. The default values are both **"50%"**, indicating that the center point of the page.<br>- If the center point is (0, 0), it refers to the upper left corner of the component.<br>- **centerZ**: z-axis anchor point, that is, the z-component of the 3D rotation center point. The default value is **0**.<br>- **perspective**: distance from the user to the z=0 plane. The default value is **0**.<br>Since API version 10, this API is supported in ArkTS widgets.| 26| move | [TransitionEdge](ts-appendix-enums.md#transitionedge10) | Yes| Slide-in and slide-out of the component from the screen edge during transition. It is essentially a translation effect, which is the value of the start point of insertion and the end point of deletion.<br>Since API version 10, this API is supported in ArkTS widgets.| 27| asymmetric | appear: [TransitionEffect](#transitioneffect10),<br>disappear: [TransitionEffect](#transitioneffect10)<br>| Yes| Asymmetric transition effect.<br>The first parameter indicates the transition effect for appearance, and the second parameter indicates the transition effect for disappearance.<br>If the **asymmetric** function is not used for **TransitionEffect**, the transition effect takes effect for both appearance and disappearance of the component.<br>Since API version 10, this API is supported in ArkTS widgets.| 28| combine | [TransitionEffect](#transitioneffect10) | No| Combination of transition effects.<br>Since API version 10, this API is supported in ArkTS widgets.| 29| animation | [AnimateParam](../arkui-ts/ts-explicit-animation.md#animateparam) | No| Animation settings.<br>The **onFinish** callback in **AnimateParam** does not work here.<br>If **combine** is used for combining transition effects, the animation settings of a transition effect are applicable to the one following it.<br>Since API version 10, this API is supported in ArkTS widgets.| 30 31The static functions listed in the preceding table are used to create a **TransitionEffect** object, while the non-static functions apply to the created **TransitionEffect** object. 32**TransitionEffect** also provides some static member variables for transition effects: 33| Static Member Variable| Description| 34| -------- | -------- | 35| IDENTITY | Disables the transition effect.| 36| OPACITY | Applies a transition effect with the opacity of 0. It is equivalent to **TransitionEffect.opacity(0)**.| 37| SLIDE | Applies a transition effect of sliding in from the left when the component appears and sliding out from the right when the component disappears. It is equivalent to **TransitionEffect.asymmetric(TransitionEffect.move(TransitionEdge.START), TransitionEffect.move(TransitionEdge.END))**.| 38| SLIDE_SWITCH | Applies a transition effect of sliding in from the right with first scaling down and then scaling up when the component appears and sliding out from the right with first scaling down and then scaling up when the component disappears. The animation duration is 600 ms. The animation curve cubicBezierCurve(0.24f, 0.0f, 0.50f, 1.0f) is used. The minimum scale factor is 0.8.| 39 40> **NOTE** 41> 42> 1. For transition effects combined through the **combine** function, animation settings can be configured through the **animation** parameter on a one-on-one basis. In addition, the animation settings of a transition effect are applicable to the one following it. For example, with **TransitionEffect.OPACITY.animation({duration: 1000}).combine(TransitionEffect.translate({x: 100}))**, the **duration** settings (1000 ms) apply to both the OPACITY and translate effects. 43> 2. The animation settings take effect in the following sequence: animation settings specified in the current **TransitionEffect** > animation settings specified in the previous **TransitionEffect** > animation settings specified in **animateTo** that triggers the component to appear and disappear. 44> 3. If **animateTo** is not used and **TransitionEffect** does not have the **animation** parameter specified, the component will appear or disappear without any transition animation. 45> 4. If the value of an attribute specified in **TransitionEffect** is the same as the default value, no transition animation will be applied to the attribute. For example, with **TransitionEffect.opacity(1).animation({duration:1000})**, because the default value of **opacity** is also **1**, no opacity animation will be applied, and the component appears or disappears without any transition animation. 46> 5. For details about the scale and rotate effects, see [Transformation](ts-universal-attributes-transformation.md). 47 48## TransitionOptions<sup>(deprecated)</sup> 49Defines the transition effect by setting parameters in the struct. 50 51This API is deprecated since API version 10. You are advised to use [TransitionEffect](#transitioneffect10) instead. 52| Name| Type| Mandatory| Description| 53| -------- | -------- | -------- | -------- | 54| type | [TransitionType](ts-appendix-enums.md#transitiontype) | No| Transition type.<br>Default value: **TransitionType.All**<br>**NOTE**<br>If **type** is not specified, the default value **TransitionType.All** is used, which means that the transition effect works for both component addition and deletion.| 55| opacity | number | No| Opacity of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 or greater than 1 evaluates to the value **1**.| 56| translate | [TranslateOptions](ts-universal-attributes-transformation.md#translateoptions) |No | Translation of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>-**x**: distance to translate along the x-axis.<br>-**y**: distance to translate along the y-axis.<br>-**z**: distance to translate along the z-axis.| 57| scale | [ScaleOptions](ts-universal-attributes-transformation.md#scaleoptions) | No| Scaling of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>- **x**: scale factor along the x-axis.<br>- **y**: scale factor along the y-axis.<br>- **z**: scale factor along the z-axis (not effective for the current 2D graphics).<br>- **centerX** and **centerY**: scale center point. The default values are both **"50%"**, indicating that the center point of the page.<br>- If the center point is (0, 0), it refers to the upper left corner of the component.| 58| rotate | [RotateOptions](ts-universal-attributes-transformation.md#rotateoptions)| No| Rotation of the component during transition, which is the value of the start point of insertion and the end point of deletion.<br>- **x**: X-component of the rotation vector.<br>- **y**: Y-component of the rotation vector.<br>- **z**: Z-component of the rotation vector.<br>- **centerX** and **centerY**: rotation center point. The default values are both **"50%"**, indicating that the center point of the page.<br>- If the center point is (0, 0), it refers to the upper left corner of the component.| 59 60> **NOTE** 61> 62> 1. When set to a value of the **TransitionOptions** type, the **transition** attribute must work with [animateTo](ts-explicit-animation.md). The animation duration, curve, and delay follow the settings in **animateTo**. 63> 2. If the value of the **TransitionOptions** type has only **type** specified, the transition effect will take on the default opacity. For example, **{type: TransitionType.Insert}** produces the same effect as **{type: TransitionType.Insert, opacity: 0}**. If a specific style is specified, the transition effect will not take on the default opacity. 64 65## Example 66 67The following is an example of using the same transition effect for the appearance and disappearance (which are inverse processes) of the component. 68```ts 69// xxx.ets 70@Entry 71@Component 72struct TransitionEffectExample1 { 73 @State flag: boolean = true; 74 @State show: string = 'show'; 75 76 build() { 77 Column() { 78 Button(this.show).width(80).height(30).margin(30) 79 .onClick(() => { 80 // Click the button to show or hide the image. 81 if (this.flag) { 82 this.show = 'hide'; 83 } else { 84 this.show = 'show'; 85 } 86 this.flag = !this.flag; 87 }) 88 if (this.flag) { 89 // Apply the same transition effect to the appearance and disappearance of the image. 90 // When the image appears, it changes from the state where the opacity is 0 and the rotation angle is 180° around the z-axis to the state where the opacity is 1 and the rotation angle is 0°. The durations of the opacity and rotation animations are both 2000 ms. 91 // When the image disappears, it changes from the state where the opacity is 1 and the rotation angle is 0° to the state where the opacity is 0 and the rotation angle is 180° around the z-axis. The durations of the opacity and rotation animations are both 2000 ms. 92 Image($r('app.media.testImg')).width(200).height(200) 93 .transition(TransitionEffect.OPACITY.animation({ duration: 2000, curve: Curve.Ease }).combine( 94 TransitionEffect.rotate({ z: 1, angle: 180 }) 95 )) 96 } 97 }.width('100%') 98 } 99} 100``` 101Below you can see the example in action.<br> 102 103 104The following is an example of using different transition effects for the appearance and disappearance of the component. 105```ts 106// xxx.ets 107@Entry 108@Component 109struct TransitionEffectExample2 { 110 @State flag: boolean = true; 111 @State show: string = 'show'; 112 113 build() { 114 Column() { 115 Button(this.show).width(80).height(30).margin(30) 116 .onClick(() => { 117 // Click the button to show or hide the image. 118 if (this.flag) { 119 this.show = 'hide'; 120 } else { 121 this.show = 'show'; 122 } 123 animateTo({ duration: 2000 }, () => { 124 // In the first image, **TransitionEffect** contains **animation**, and therefore the animation settings are those configured in **TransitionEffect**. 125 // In the second image, **TransitionEffect** does not contain **animation**, and therefore the animation settings are those configured in **animateTo**. 126 this.flag = !this.flag; 127 }); 128 }) 129 if (this.flag) { 130 // Apply different transition effects to the appearance and disappearance of the image. 131 // When the image appears, its opacity changes 0 to 1 (default value) over the duration of 1000 ms, and after 1000 ms has elapsed, its rotation angle changes from 180° around the z-axis to 0° (default value) over the duration of 1000 ms. 132 // When the image disappears, after 1000 ms has elapsed, its opacity changes 1 (default value) to 0 over the duration of 1000 ms, and its rotation angle changes from 0° (default value) to 180° around the z-axis over the duration of 1000 ms. 133 Image($r('app.media.testImg')).width(200).height(200) 134 .transition( 135 TransitionEffect.asymmetric( 136 TransitionEffect.OPACITY.animation({ duration: 1000 }).combine( 137 TransitionEffect.rotate({ z: 1, angle: 180 }).animation({ delay: 1000, duration: 1000 })) 138 , 139 TransitionEffect.OPACITY.animation({ delay: 1000, duration: 1000 }).combine( 140 TransitionEffect.rotate({ z: 1, angle: 180 }).animation({ duration: 1000 })) 141 ) 142 ) 143 // When the image appears, the scale along the x- and y- axes is changed from 0 to 1 (default value). The animation duration is 2000 ms specified in **animateTo**. 144 // When the image disappears, no transition effect is applied. 145 Image($r('app.media.testImg')).width(200).height(200).margin({ top: 100 }) 146 .transition( 147 TransitionEffect.asymmetric( 148 TransitionEffect.scale({ x: 0, y: 0 }), 149 TransitionEffect.IDENTITY 150 ) 151 ) 152 } 153 }.width('100%') 154 } 155} 156``` 157Below you can see the example in action.<br> 158 159
