1# @ohos.curves (Interpolation Calculation) 2 3The **Curves** module provides APIs for interpolation calculation to create step, cubic Bezier, and spring curves. 4 5> **NOTE** 6> 7> The initial 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## Modules to Import 11 12```ts 13import Curves from '@ohos.curves' 14``` 15 16 17## Curves.initCurve<sup>9+</sup> 18 19initCurve(curve?: Curve): ICurve 20 21 22Implements initialization for the interpolation curve, which is used to create an interpolation curve based on the input parameter. 23 24**System capability**: SystemCapability.ArkUI.ArkUI.Full 25 26**Parameters** 27 28| Name| Type | Mandatory| Description | 29| ------ | --------------- | ---- | ----------------------------------- | 30| curve | [Curve](#curve) | No | Curve type.<br>Default value: **Curve.Linear**| 31 32**Return value** 33 34| Type | Description | 35| ---------------------------------- | ---------------- | 36| [ICurve](#icurve) | Interpolation curve.| 37 38## Curve 39 40Since API version 9, this API is supported in ArkTS widgets. 41 42**System capability**: SystemCapability.ArkUI.ArkUI.Full 43 44| Name | Description | 45| ------------------- | ------------------------------------------------------------ | 46| Linear | The animation speed keeps unchanged. | 47| Ease | The animation starts slowly, accelerates, and then slows down towards the end. The cubic-bezier curve (0.25, 0.1, 0.25, 1.0) is used.| 48| EaseIn | The animation starts at a low speed and then picks up speed until the end. The cubic-bezier curve (0.42, 0.0, 1.0, 1.0) is used. | 49| EaseOut | The animation ends at a low speed. The cubic-bezier curve (0.0, 0.0, 0.58, 1.0) is used. | 50| EaseInOut | The animation starts and ends at a low speed. The cubic-bezier curve (0.42, 0.0, 0.58, 1.0) is used.| 51| FastOutSlowIn | The animation uses the standard cubic-bezier curve (0.4, 0.0, 0.2, 1.0). | 52| LinearOutSlowIn | The animation uses the deceleration cubic-bezier curve (0.0, 0.0, 0.2, 1.0). | 53| FastOutLinearIn | The animation uses the acceleration cubic-bezier curve (0.4, 0.0, 1.0, 1.0). | 54| ExtremeDeceleration | The animation uses the extreme deceleration cubic-bezier curve (0.0, 0.0, 0.0, 1.0). | 55| Sharp | The animation uses the sharp cubic-bezier curve (0.33, 0.0, 0.67, 1.0). | 56| Rhythm | The animation uses the rhythm cubic-bezier curve (0.7, 0.0, 0.2, 1.0). | 57| Smooth | The animation uses the smooth cubic-bezier curve (0.4, 0.0, 0.4, 1.0). | 58| Friction | The animation uses the friction cubic-bezier curve (0.2, 0.0, 0.2, 1.0). | 59 60**Example** 61 62```ts 63import Curves from '@ohos.curves' 64Curves.initCurve(Curve.EaseIn) // Create a default ease-in curve, where the interpolation starts slowly and then picks up speed. 65``` 66 67 68## Curves.stepsCurve<sup>9+</sup> 69 70stepsCurve(count: number, end: boolean): ICurve 71 72 73Creates a step curve. 74 75**System capability**: SystemCapability.ArkUI.ArkUI.Full 76 77**Parameters** 78 79| Name| Type | Mandatory| Description | 80| ------ | ------- | ----| ------------------------------------------------------------ | 81| count | number | Yes | Number of steps. The value must be a positive integer.<br>Value range: [1, +∞)<br>**NOTE**<br>A value less than 1 evaluates to the value **1**.| 82| end | boolean | Yes | Whether jumping occurs when the interpolation ends.<br>- **true**: Jumping occurs when the interpolation ends.<br>- **false**: Jumping occurs when the interpolation starts.| 83 84**Return value** 85 86| Type | Description | 87| ---------------------------------- | ---------------- | 88| [ICurve](#icurve) | Interpolation curve.| 89 90**Example** 91 92```ts 93import Curves from '@ohos.curves' 94Curves.stepsCurve(9, true) // Create a step curve. 95``` 96 97 98## Curves.cubicBezierCurve<sup>9+</sup> 99 100cubicBezierCurve(x1: number, y1: number, x2: number, y2: number): ICurve 101 102 103Creates a cubic Bezier curve. The curve values must be between 0 and 1. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107**Parameters** 108 109| Name| Type | Mandatory| Description | 110| ------ | ------ | ---- | ------------------------------------------------------------ | 111| x1 | number | Yes | X coordinate of the first point on the Bezier curve.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.| 112| y1 | number | Yes | Y coordinate of the first point on the Bezier curve.<br>Value range: (-∞, +∞) | 113| x2 | number | Yes | X coordinate of the second point on the Bezier curve.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.| 114| y2 | number | Yes | Y coordinate of the second point on the Bezier curve.<br>Value range: (-∞, +∞) | 115 116**Return value** 117 118| Type | Description | 119| ---------------------------------- | ---------------- | 120| [ICurve](#icurve) | Interpolation curve.| 121 122 123**Example** 124 125```ts 126import Curves from '@ohos.curves' 127Curves.cubicBezierCurve(0.1, 0.0, 0.1, 1.0) // Create a cubic Bezier curve. 128``` 129 130 131## Curves.springCurve<sup>9+</sup> 132 133springCurve(velocity: number, mass: number, stiffness: number, damping: number): ICurve 134 135 136Creates a spring curve. The curve shape is subject to the spring parameters, and the animation duration is subject to the **duration** parameter in **animation** and **animateTo**. 137 138**System capability**: SystemCapability.ArkUI.ArkUI.Full 139 140**Parameters** 141| Name | Type | Mandatory| Description | 142| --------- | ------ | ---- | ------------------------------------------------------------ | 143| velocity | number | Yes | Initial velocity. It is applied by external factors to the spring animation, designed to help ensure the smooth transition from the previous motion state. The velocity is the normalized velocity, and its value is equal to the actual velocity at the beginning of the animation divided by the animation attribute change value.<br>Value range: (-∞, +∞)| 144| mass | number | Yes | Mass, which influences the inertia in the spring system. The greater the mass, the greater the amplitude of the oscillation, and the slower the speed of restoring to the equilibrium position.<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the value **1** is used.| 145| stiffness | number | Yes | Stiffness. It is the degree to which an object deforms by resisting the force applied. In an elastic system, the greater the stiffness, the stronger the ability to resist deformation, and the faster the speed of restoring to the equilibrium position.<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the value **1** is used.| 146| damping | number | Yes | Damping. It is used to describe the oscillation and attenuation of the system after being disturbed. The larger the damping, the smaller the number of oscillations of elastic motion, and the smaller the oscillation amplitude.<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the value **1** is used.| 147 148 149**Return value** 150 151| Type | Description | 152| ---------------------------------- | ---------------- | 153| [ICurve](#icurve)| Interpolation curve.| 154 155 156**Example** 157 158```ts 159import Curves from '@ohos.curves' 160Curves.springCurve(10, 1, 228, 30) // Create a spring curve. 161``` 162 163 164## Curves.springMotion<sup>9+</sup> 165 166springMotion(response?: number, dampingFraction?: number, overlapDuration?: number): ICurve 167 168Creates a spring animation curve. If multiple spring animations are applied to the same attribute of an object, each animation replaces their predecessor and inherits the velocity. 169 170**System capability**: SystemCapability.ArkUI.ArkUI.Full 171 172**Parameters** 173 174| Name | Type | Mandatory | Description | 175| --------- | ------ | ---- | ----- | 176| response | number | No | Duration of one complete oscillation.<br>Default value: **0.55**<br>Unit: second<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the default value **0.55** is used.| 177| dampingFraction | number | No | Damping coefficient.<br>**0**: undamped. In this case, the spring oscillates forever.<br>> 0 and < 1: underdamped. In this case, the spring overshoots the equilibrium position.<br>**1**: critically damped.<br>> 1: overdamped. In this case, the spring approaches equilibrium gradually.<br>Default value: **0.825**<br>Unit: second<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the default value **0.825**.| 178| overlapDuration | number | No | Duration for animations to overlap, in seconds. When animations overlap, the **response** values of these animations will transit smoothly over this duration if they are different.<br>Default value: **0**<br>Unit: second<br>Value range: [0, +∞)<br> **NOTE**<br>A value less than 0 evaluates to the default value **0**.<br>The spring animation curve is physics-based. Its duration depends on the **springMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md), [animateTo](../arkui-ts/ts-explicit-animation.md), or [pageTransition](../arkui-ts/ts-page-transition-animation.md). The time cannot be normalized. Therefore, the interpolation cannot be obtained using the **interpolate** function of the curve.| 179 180 181**Return value** 182 183| Type | Description | 184| ---------------------------------- | ---------------- | 185| [ICurve](#icurve)| Curve.<br>**NOTE**<br>The spring animation curve is physics-based. Its duration depends on the **springMotion** parameters and the previous velocity, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md), [animateTo](../arkui-ts/ts-explicit-animation.md), or [pageTransition](../arkui-ts/ts-page-transition-animation.md). The time cannot be normalized. Therefore, the interpolation cannot be obtained using the [interpolate](#interpolate9) function of the curve.| 186 187**Example** 188 189```ts 190import Curves from '@ohos.curves' 191Curves.springMotion() // Create a spring animation curve with default settings. 192Curves.springMotion(0.5) // Create a spring animation curve with the specified response value. 193Curves.springMotion (0.5, 0.6) // Create a spring animation curve with the specified response and dampingFraction values. 194Curves.springMotion(0.5, 0.6, 0) // Create a spring animation curve with the specified parameter values. 195``` 196 197 198## Curves.responsiveSpringMotion<sup>9+</sup> 199 200responsiveSpringMotion(response?: number, dampingFraction?: number, overlapDuration?: number): ICurve 201 202Creates a responsive spring animation curve. It is a special case of [springMotion](#curvesspringmotion9), with the only difference in the default values. It can be used together with **springMotion**. 203 204**System capability**: SystemCapability.ArkUI.ArkUI.Full 205 206**Parameters** 207 208| Name | Type | Mandatory | Description | 209| --------- | ------ | ---- | ----- | 210| response | number | No | See **response** in **springMotion**.<br>Default value: **0.15**<br>Unit: second<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the default value **0.15** is used.| 211| dampingFraction | number | No | See **dampingFraction** in **springMotion**.<br>Default value: **0.86**<br>Unit: second<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the default value **0.86**.| 212| overlapDuration | number | No | See **overlapDuration** in **springMotion**.<br>Default value: **0.25**<br>Unit: second<br>Value range: [0, +∞)<br>**NOTE**<br>A value less than 0 evaluates to the default value **0.25**.<br> To apply custom settings for a spring animation, you are advised to use **springMotion**. When using **responsiveSpringMotion**, you are advised to retain the default settings.<br>The duration of the responsive spring animation depends on the **responsiveSpringMotion** parameters and the previous velocity, rather than the duration parameter in [animation](../arkui-ts/ts-animatorproperty.md), [animateTo](../arkui-ts/ts-explicit-animation.md), or [pageTransition](../arkui-ts/ts-page-transition-animation.md). In addition, the interpolation cannot be obtained using the **interpolate** function of the curve.| 213 214**Return value** 215 216| Type | Description | 217| ---------------------------------- | ---------------- | 218| [ICurve](#icurve)| Curve.<br>**NOTE**<br>1. To apply custom settings for a spring animation, you are advised to use **springMotion**. When using **responsiveSpringMotion**, you are advised to retain the default settings.<br>2. The duration of the responsive spring animation depends on the **responsiveSpringMotion** parameters and the previous velocity, rather than the duration parameter in [animation](../arkui-ts/ts-animatorproperty.md), [animateTo](../arkui-ts/ts-explicit-animation.md), or [pageTransition](../arkui-ts/ts-page-transition-animation.md). In addition, the interpolation cannot be obtained using the [interpolate](#interpolate9) function of the curve.| 219 220**Example** 221 222```ts 223import Curves from '@ohos.curves' 224Curves.responsiveSpringMotion() // Create a responsive spring animation curve with default settings. 225``` 226 227 228## Curves.interpolatingSpring<sup>10+</sup> 229 230interpolatingSpring(velocity: number, mass: number, stiffness: number, damping: number): ICurve 231 232 233Creates an interpolating spring curve animated from 0 to 1. The actual animation value is calculated based on the curve. The animation duration is subject to the curve parameters, rather than the **duration** parameter in **animation** or **animateTo**. 234 235**System capability**: SystemCapability.ArkUI.ArkUI.Full 236 237**Parameters** 238| Name | Type | Mandatory | Description | 239| --------- | ------ | ---- | ----- | 240| velocity | number | Yes | Initial velocity. It is applied by external factors to the spring animation, designed to help ensure the smooth transition from the previous motion state. The velocity is the normalized velocity, and its value is equal to the actual velocity at the beginning of the animation divided by the animation attribute change value.<br>Value range: (-∞, +∞)| 241| mass | number | Yes | Mass, which influences the inertia in the spring system. The greater the mass, the greater the amplitude of the oscillation, and the slower the speed of restoring to the equilibrium position.<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the value **1** is used.| 242| stiffness | number | Yes | Stiffness. It is the degree to which an object deforms by resisting the force applied. In an elastic system, the greater the stiffness, the stronger the ability to resist deformation, and the faster the speed of restoring to the equilibrium position.<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the value **1** is used.| 243| damping | number | Yes | Damping. It is used to describe the oscillation and attenuation of the system after being disturbed. The larger the damping, the smaller the number of oscillations of elastic motion, and the smaller the oscillation amplitude.<br>Value range: (0, +∞)<br>**NOTE**<br>If this parameter is set to a value less than or equal to 0, the value **1** is used.| 244 245**Return value** 246 247| Type | Description | 248| ---------------------------------- | ---------------- | 249| [ICurve](#icurve)| Curve.<br>**NOTE**<br>The spring animation curve is physics-based. Its duration depends on the **interpolatingSpring** parameters, rather than the **duration** parameter in [animation](../arkui-ts/ts-animatorproperty.md), [animateTo](../arkui-ts/ts-explicit-animation.md), or [pageTransition](../arkui-ts/ts-page-transition-animation.md). The time cannot be normalized. Therefore, the interpolation cannot be obtained using the [interpolate](#interpolate9) function of the curve.| 250 251**Example** 252 253```ts 254import Curves from '@ohos.curves' 255Curves.interpolatingSpring(10, 1, 228, 30) // Create an interpolating spring curve whose duration is subject to spring parameters. 256``` 257 258## Curves.customCurve<sup>10+</sup> 259 260customCurve(interpolate: (fraction: number) => number): ICurve 261 262Creates a custom curve. 263 264**System capability**: SystemCapability.ArkUI.ArkUI.Full 265 266**Parameters** 267 268| Name | Type | Mandatory| Description | 269| ----------- | ---------------------------- | ---- | ------------------------------------------------------------ | 270| interpolate | (fraction: number) => number | Yes | Custom interpolation callback.<br>**fraction**: input x value for interpolation when the animation starts. Value range: [0, 1]<br>The return value is the y value of the curve. Value range: [0, 1]<br>**NOTE**<br>If **fraction** is **0**, the return value **0** corresponds to the animation start point; any other return value means that the animation jumps at the start point.<br>If **fraction** is **1**, the return value **1** corresponds to the animation end point; any other return value means that the end value of the animation is not the value of the state variable, which will result in an effect of transition from that end value to the value of the state variable.| 271 272**Return value** 273 274| Type | Description | 275| ----------------- | ---------------- | 276| [ICurve](#icurve) | Interpolation curve.| 277 278**Example** 279 280```ts 281import Curves from '@ohos.curves' 282let interpolate = (fraction:number):number => { 283 return Math.sqrt(fraction) 284} 285let curve = Curves.customCurve(interpolate) // Create a custom interpolation curve. 286``` 287 288 289 290## ICurve 291 292 293### interpolate<sup>9+</sup> 294 295interpolate(fraction: number): number 296 297Implements calculation. 298 299Since API version 9, this API is supported in ArkTS widgets. 300 301**System capability**: SystemCapability.ArkUI.ArkUI.Full 302 303**Parameters** 304 305| Name | Type | Mandatory| Description | 306| -------- | ------ | ---- | ------------------------------------------------------------ | 307| fraction | number | Yes | Current normalized time.<br>Value range: [0, 1]<br>**NOTE**<br>A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.| 308 309**Return value** 310 311| Type | Description | 312| ------ | ------------------------------------ | 313| number | Curve interpolation corresponding to the normalized time point.| 314 315**Example** 316 317```ts 318import Curves from '@ohos.curves' 319let curveValue = Curves.initCurve(Curve.EaseIn) // Create an ease-in curve. 320let value: number = curveValue.interpolate(0.5) // Calculate the interpolation for half of the time. 321``` 322 323 324## Curves.init<sup>(deprecated)</sup> 325 326init(curve?: Curve): string 327 328 329Implements initialization to create a curve. This API is deprecated since API version 9. You are advised to use [Curves.initCurve](#curvesinitcurve9) instead. 330 331**System capability**: SystemCapability.ArkUI.ArkUI.Full 332 333**Parameters** 334 335| Name| Type | Mandatory| Description | 336| ------ | --------------- | ---- | ----------------------------------- | 337| curve | [Curve](#curve) | No | Curve type.<br>Default value: **Curve.Linear**| 338 339 340## Curves.steps<sup>(deprecated)</sup> 341 342steps(count: number, end: boolean): string 343 344 345Creates a step curve. This API is deprecated since API version 9. You are advised to use [Curves.stepsCurve](#curvesstepscurve9) instead. 346 347**System capability**: SystemCapability.ArkUI.ArkUI.Full 348 349**Parameters** 350 351| Name| Type | Mandatory| Description | 352| ------ | ------- | ----| ------------------------------------------------------------ | 353| count | number | Yes | Number of steps. The value must be a positive integer. | 354| end | boolean | Yes | Whether jumping occurs when the interpolation ends.<br>- **true**: Jumping occurs when the interpolation ends.<br>- **false**: Jumping occurs when the interpolation starts.| 355 356 357## Curves.cubicBezier<sup>(deprecated)</sup> 358 359cubicBezier(x1: number, y1: number, x2: number, y2: number): string 360 361 362Creates a cubic Bezier curve. The curve value must range from 0 to 1. This API is deprecated since API version 9. You are advised to use [Curves.cubicBezierCurve](#curvescubicbeziercurve9) instead. 363 364**System capability**: SystemCapability.ArkUI.ArkUI.Full 365 366**Parameters** 367| Name | Type | Mandatory | Description | 368| ---- | ------ | ---- | -------------- | 369| x1 | number | Yes | X coordinate of the first point on the Bezier curve.| 370| y1 | number | Yes | Y coordinate of the first point on the Bezier curve.| 371| x2 | number | Yes | X coordinate of the second point on the Bezier curve.| 372| y2 | number | Yes | Y coordinate of the second point on the Bezier curve.| 373 374 375## Curves.spring<sup>(deprecated)</sup> 376 377spring(velocity: number, mass: number, stiffness: number, damping: number): string 378 379 380Creates a spring curve. This API is deprecated since API version 9. You are advised to use [Curves.springCurve](#curvesspringcurve9) instead. 381 382**System capability**: SystemCapability.ArkUI.ArkUI.Full 383 384**Parameters** 385 386| Name | Type | Mandatory | Description | 387| --------- | ------ | ---- | ----- | 388| velocity | number | Yes | Initial velocity. It is applied by external factors to the spring animation, designed to help ensure the smooth transition from the previous motion state.| 389| mass | number | Yes | Mass, which influences the inertia in the spring system. The greater the mass, the greater the amplitude of the oscillation, and the slower the speed of restoring to the equilibrium position.| 390| stiffness | number | Yes | Stiffness. It is the degree to which an object deforms by resisting the force applied. In an elastic system, the greater the stiffness, the stronger the ability to resist deformation, and the faster the speed of restoring to the equilibrium position.| 391| damping | number | Yes | Damping. It is a pure number and has no real physical meaning. It is used to describe the oscillation and attenuation of the system after being disturbed. The larger the damping, the smaller the number of oscillations of elastic motion, and the smaller the oscillation amplitude.| 392 393## Example 394 395```ts 396// xxx.ets 397import Curves from '@ohos.curves' 398 399@Entry 400@Component 401struct ImageComponent { 402 @State widthSize: number = 200 403 @State heightSize: number = 200 404 405 build() { 406 Column() { 407 Text() 408 .margin({ top: 100 }) 409 .width(this.widthSize) 410 .height(this.heightSize) 411 .backgroundColor(Color.Red) 412 .onClick(() => { 413 let curve = Curves.cubicBezierCurve(0.25, 0.1, 0.25, 1.0); 414 this.widthSize = curve.interpolate(0.5) * this.widthSize; 415 this.heightSize = curve.interpolate(0.5) * this.heightSize; 416 }) 417 .animation({ duration: 2000, curve: Curves.stepsCurve(9, true) }) 418 }.width("100%").height("100%") 419 } 420} 421``` 422 423 424
