1# Component 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<sup>(deprecated)</sup> \| TransitionEffect<sup>10+</sup> | Transition effects when the component is inserted, displayed, deleted, or hidden.<br>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>For details, see the descriptions of **TransitionOptions** and **TransitionEffect**.| 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>**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.| 24| scale | {<br>x? : number,<br>y? : number,<br>z? : number,<br>centerX? : number \| string,<br>centerY? : number \| string<br>} | 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.<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.| 25| rotate | {<br>x?: number,<br>y?: number,<br>z?: number,<br>angle: number \| string,<br>centerX?: number \| string,<br>centerY?: number \| string,<br>centerZ?: number,<br>perspective?: number<br>} | 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**.| 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.| 27| asymmetric | appear: TransitionEffect,<br>disappear: TransitionEffect<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.| 28| combine | TransitionEffect | No| Combination of transition effects.| 29| animation | [AnimateParam](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.| 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 39> **NOTE** 40> 41> 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. 42> 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. 43> 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. 44> 4. If the value of an attribute specified in **TransitionEffect** is the same as the default value, no transition animation is applied for 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. 45> 5. For details about the scale and rotate effects, see [Transformation](ts-universal-attributes-transformation.md). 46 47## TransitionOptions<sup>(deprecated)</sup> 48Defines the transition effect by setting parameters in the struct. 49 50This API is deprecated since API version 10. You are advised to use [TransitionEffect](#transitioneffect10) instead. 51| Name| Type| Mandatory| Description| 52| -------- | -------- | -------- | -------- | 53| type | [TransitionType](ts-appendix-enums.md#transitiontype) | No| Transition type.<br>Default value: **TransitionType.All**<br>Since API version 9, this API is supported in ArkTS widgets.<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.| 54| 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>Since API version 9, this API is supported in ArkTS widgets.<br>**NOTE**<br>A value less than 0 or greater than 1 evaluates to the value **1**.| 55| translate | {<br>x? : number \| string,<br>y? : number \| string,<br>z? : number \| string<br>} | 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.<br>Since API version 9, this API is supported in ArkTS widgets.| 56| scale | {<br>x? : number,<br>y? : number,<br>z? : number,<br>centerX? : number \| string,<br>centerY? : number \| string<br>} | 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.<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 9, this API is supported in ArkTS widgets.| 57| rotate | {<br>x?: number,<br>y?: number,<br>z?: number,<br>angle: number \| string,<br>centerX?: number \| string,<br>centerY?: number \| string<br>} | 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.<br>Since API version 9, this API is supported in ArkTS widgets.| 58 59> **NOTE** 60> 61> 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**. 62> 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. 63 64## Example 65 66The following is an example of using the same transition effect for the appearance and disappearance (which are inverse processes) of the component. 67```ts 68// xxx.ets 69@Entry 70@Component 71struct TransitionEffectExample1 { 72 @State flag: boolean = true; 73 @State show: string = 'show'; 74 75 build() { 76 Column() { 77 Button(this.show).width(80).height(30).margin(30) 78 .onClick(() => { 79 // Click the button to show or hide the image. 80 if (this.flag) { 81 this.show = 'hide'; 82 } else { 83 this.show = 'show'; 84 } 85 this.flag = !this.flag; 86 }) 87 if (this.flag) { 88 // Apply the same transition effect to the appearance and disappearance of the image. 89 // 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. 90 // 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. 91 Image($r('app.media.testImg')).width(200).height(200) 92 .transition(TransitionEffect.OPACITY.animation({ duration: 2000, curve: Curve.Ease }).combine( 93 TransitionEffect.rotate({ z: 1, angle: 180 }) 94 )) 95 } 96 }.width('100%') 97 } 98} 99``` 100Below you can see the example in action.<br> 101 102 103The following is an example of using different transition effects for the appearance and disappearance of the component. 104```ts 105// xxx.ets 106@Entry 107@Component 108struct TransitionEffectExample2 { 109 @State flag: boolean = true; 110 @State show: string = 'show'; 111 112 build() { 113 Column() { 114 Button(this.show).width(80).height(30).margin(30) 115 .onClick(() => { 116 // Click the button to show or hide the image. 117 if (this.flag) { 118 this.show = 'hide'; 119 } else { 120 this.show = 'show'; 121 } 122 animateTo({ duration: 2000 }, () => { 123 // In the first image, **TransitionEffect** contains **animation**, and therefore the animation settings are those configured in **TransitionEffect**. 124 // In the second image, **TransitionEffect** does not contain **animation**, and therefore the animation settings are those configured in **animateTo**. 125 this.flag = !this.flag; 126 }); 127 }) 128 if (this.flag) { 129 // Apply different transition effects to the appearance and disappearance of the image. 130 // 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. 131 // 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. 132 Image($r('app.media.testImg')).width(200).height(200) 133 .transition( 134 TransitionEffect.asymmetric( 135 TransitionEffect.OPACITY.animation({ duration: 1000 }).combine( 136 TransitionEffect.rotate({ z: 1, angle: 180 }).animation({ delay: 1000, duration: 1000 })) 137 , 138 TransitionEffect.OPACITY.animation({ delay: 1000, duration: 1000 }).combine( 139 TransitionEffect.rotate({ z: 1, angle: 180 }).animation({ duration: 1000 })) 140 ) 141 ) 142 // 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**. 143 // When the image disappears, no transition effect is applied. 144 Image($r('app.media.testImg')).width(200).height(200).margin({ top: 100 }) 145 .transition( 146 TransitionEffect.asymmetric( 147 TransitionEffect.scale({ x: 0, y: 0 }), 148 TransitionEffect.IDENTITY 149 ) 150 ) 151 } 152 }.width('100%') 153 } 154} 155``` 156Below you can see the example in action.<br> 157 158
