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 '@kit.ArkUI';
14```
15
16
17## Curves.initCurve<sup>9+</sup>
18
19initCurve(curve?: Curve): ICurve
20
21Implements initialization for the interpolation curve, which is used to create an interpolation curve based on the input parameter.
22
23**Atomic service API**: This API can be used in atomic services since API version 11.
24
25**System capability**: SystemCapability.ArkUI.ArkUI.Full
26
27**Parameters**
28
29| Name | Type           | Mandatory | Description                               |
30| ------ | --------------- | ---- | ----------------------------------- |
31| curve  | [Curve](#curve) | No  | Curve type.<br>Default value: **Curve.Linear** |
32
33**Return value**
34
35| Type                          | Description            |
36| ---------------------------------- | ---------------- |
37| [ICurve](#icurve9) | Interpolation curve. |
38
39## Curve
40
41Defines an interpolation curve. For details about the animation, see <!--RP1-->[Bezier Curve](../../../design/ux-design/animation-attributes.md)<!--RP1End-->.
42
43**Atomic service API**: This API can be used in atomic services since API version 11.
44
45**System capability**: SystemCapability.ArkUI.ArkUI.Full
46
47| Name               | Description                                                        |
48| ------------------- | ------------------------------------------------------------ |
49| Linear              | The animation speed keeps unchanged.                          |
50| Ease                | The animation starts at a low speed and then accelerates. It slows down before the animation ends. **cubic-bezier(0.25, 0.1, 0.25, 1.0)** |
51| 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.      |
52| EaseOut             | The animation ends at a low speed. The cubic-bezier curve (0.0, 0.0, 0.58, 1.0) is used.      |
53| EaseInOut           | The animation starts and ends at a low speed. The cubic-bezier curve (0.42, 0.0, 0.58, 1.0) is used. |
54| FastOutSlowIn       | The animation uses the standard cubic-bezier curve (0.4, 0.0, 0.2, 1.0).                |
55| LinearOutSlowIn     | The animation uses the deceleration cubic-bezier curve (0.0, 0.0, 0.2, 1.0).                |
56| FastOutLinearIn     | The animation uses the acceleration cubic-bezier curve (0.4, 0.0, 1.0, 1.0).                |
57| ExtremeDeceleration | The animation uses the extreme deceleration cubic-bezier curve (0.0, 0.0, 0.0, 1.0).                |
58| Sharp               | The animation uses the sharp cubic-bezier curve (0.33, 0.0, 0.67, 1.0).              |
59| Rhythm              | The animation uses the rhythm cubic-bezier curve (0.7, 0.0, 0.2, 1.0).                |
60| Smooth              | The animation uses the smooth cubic-bezier curve (0.4, 0.0, 0.4, 1.0).                |
61| Friction            | The animation uses the damping cubic-bezier curve (0.2, 0.0, 0.2, 1.0).                 |
62
63**Example**
64
65```ts
66import { curves } from '@kit.ArkUI';
67curves.initCurve(Curve.EaseIn) // Create a default ease-in curve, where the interpolation starts slowly and then picks up speed.
68```
69
70
71##  Curves.stepsCurve<sup>9+</sup>
72
73stepsCurve(count: number, end: boolean): ICurve
74
75Creates a step curve.
76
77**Atomic service API**: This API can be used in atomic services since API version 11.
78
79**System capability**: SystemCapability.ArkUI.ArkUI.Full
80
81**Parameters**
82
83| Name | Type   | Mandatory | Description                                                        |
84| ------ | ------- | ----| ------------------------------------------------------------ |
85| 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**. |
86| 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. |
87
88**Return value**
89
90| Type                          | Description            |
91| ---------------------------------- | ---------------- |
92| [ICurve](#icurve9) | Interpolation curve. |
93
94**Example**
95
96```ts
97import { curves } from '@kit.ArkUI';
98curves.stepsCurve(9, true)  // Create a step curve.
99```
100
101
102## Curves.cubicBezierCurve<sup>9+</sup>
103
104cubicBezierCurve(x1: number, y1: number, x2: number, y2: number): ICurve
105
106Creates a cubic Bezier curve. The curve values must be between 0 and 1.
107
108**Atomic service API**: This API can be used in atomic services since API version 11.
109
110**System capability**: SystemCapability.ArkUI.ArkUI.Full
111
112**Parameters**
113
114| Name | Type  | Mandatory | Description                                                        |
115| ------ | ------ | ---- | ------------------------------------------------------------ |
116| 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**. |
117| y1     | number | Yes  | Y coordinate of the first point on the Bezier curve.<br>Value range: (-∞, +∞)         |
118| 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**. |
119| y2     | number | Yes  | Y coordinate of the second point on the Bezier curve.<br>Value range: (-∞, +∞)         |
120
121**Return value**
122
123| Type                          | Description            |
124| ---------------------------------- | ---------------- |
125| [ICurve](#icurve9) | Interpolation curve. |
126
127
128**Example**
129
130```ts
131import { curves } from '@kit.ArkUI';
132curves.cubicBezierCurve(0.1, 0.0, 0.1, 1.0) // Create a cubic Bezier curve.
133```
134
135
136##  Curves.springCurve<sup>9+</sup>
137
138springCurve(velocity: number, mass: number, stiffness: number, damping: number): ICurve
139
140Creates 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**.
141
142**Atomic service API**: This API can be used in atomic services since API version 11.
143
144**System capability**: SystemCapability.ArkUI.ArkUI.Full
145
146**Parameters**
147| Name   | Type  | Mandatory | Description                                                        |
148| --------- | ------ | ---- | ------------------------------------------------------------ |
149| 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: (-∞, +∞) |
150| 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. |
151| 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. |
152| 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. |
153
154
155**Return value**
156
157| Type                          | Description            |
158| ---------------------------------- | ---------------- |
159| [ICurve](#icurve9) | Interpolation curve. |
160
161
162**Example**
163
164```ts
165import { curves } from '@kit.ArkUI';
166curves.springCurve(10, 1, 228, 30) // Create a spring curve.
167```
168
169
170##  Curves.springMotion<sup>9+</sup>
171
172springMotion(response?: number, dampingFraction?: number, overlapDuration?: number): ICurve
173
174Creates 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.
175
176**Atomic service API**: This API can be used in atomic services since API version 11.
177
178**System capability**: SystemCapability.ArkUI.ArkUI.Full
179
180**Parameters**
181
182| Name      | Type    | Mandatory  | Description   |
183| --------- | ------ | ---- | ----- |
184| 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. |
185| 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**. |
186| 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. |
187
188
189**Return value**
190
191| Type                          | Description            |
192| ---------------------------------- | ---------------- |
193| [ICurve](#icurve9) | 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. |
194
195**Example**
196
197```ts
198import { curves } from '@kit.ArkUI'
199curves.springMotion() // Create a spring animation curve with default settings.
200curves.springMotion(0.5) // Create a spring animation curve with the specified response value.
201curves.springMotion(0.5, 0.6) // Create a spring animation curve with the specified response and dampingFraction values.
202curves.springMotion(0.5, 0.6, 0) // Create a spring animation curve with the specified parameter values.
203```
204
205
206##  Curves.responsiveSpringMotion<sup>9+</sup>
207
208responsiveSpringMotion(response?: number, dampingFraction?: number, overlapDuration?: number): ICurve
209
210Creates 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**.
211
212**Atomic service API**: This API can be used in atomic services since API version 11.
213
214**System capability**: SystemCapability.ArkUI.ArkUI.Full
215
216**Parameters**
217
218| Name      | Type    | Mandatory  | Description   |
219| --------- | ------ | ---- | ----- |
220| 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. |
221| 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**. |
222| 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. |
223
224**Return value**
225
226| Type                          | Description            |
227| ---------------------------------- | ---------------- |
228| [ICurve](#icurve9) | 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. |
229
230**Example**
231
232```ts
233import { curves } from '@kit.ArkUI'
234curves.responsiveSpringMotion() // Create a responsive spring animation curve with default settings.
235```
236
237
238##  Curves.interpolatingSpring<sup>10+</sup>
239
240interpolatingSpring(velocity: number, mass: number, stiffness: number, damping: number): ICurve
241
242Creates 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**.
243
244**Atomic service API**: This API can be used in atomic services since API version 11.
245
246**System capability**: SystemCapability.ArkUI.ArkUI.Full
247
248**Parameters**
249| Name      | Type    | Mandatory  | Description   |
250| --------- | ------ | ---- | ----- |
251| 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: (-∞, +∞) |
252| 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. |
253| 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. |
254| 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. |
255
256**Return value**
257
258| Type                          | Description            |
259| ---------------------------------- | ---------------- |
260| [ICurve](#icurve9) | 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. |
261
262**Example**
263
264```ts
265import { curves } from '@kit.ArkUI'
266curves.interpolatingSpring(10, 1, 228, 30) // Create an interpolating spring curve whose duration is subject to spring parameters.
267```
268
269## Curves.customCurve<sup>10+</sup>
270
271customCurve(interpolate: (fraction: number) => number): ICurve
272
273Creates a custom curve.
274
275**Atomic service API**: This API can be used in atomic services since API version 11.
276
277**System capability**: SystemCapability.ArkUI.ArkUI.Full
278
279**Parameters**
280
281| Name     | Type                        | Mandatory | Description                                                        |
282| ----------- | ---------------------------- | ---- | ------------------------------------------------------------ |
283| 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. |
284
285**Return value**
286
287| Type              | Description            |
288| ------------------ | ---------------- |
289| [ICurve](#icurve9) | Interpolation curve. |
290
291**Example**
292
293```ts
294import { curves } from '@kit.ArkUI'
295let interpolate = (fraction:number):number => {
296  return Math.sqrt(fraction)
297}
298let curve = curves.customCurve(interpolate) // Create a custom interpolation curve.
299```
300
301## ICurve<sup>9+</sup>
302
303Curve.
304
305
306### interpolate<sup>9+</sup>
307
308interpolate(fraction: number): number
309
310Implements calculation.
311
312**Atomic service API**: This API can be used in atomic services since API version 11.
313
314**System capability**: SystemCapability.ArkUI.ArkUI.Full
315
316**Parameters**
317
318| Name  | Type  | Mandatory | Description                                                        |
319| -------- | ------ | ---- | ------------------------------------------------------------ |
320| 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**. |
321
322**Return value**
323
324| Type  | Description                                |
325| ------ | ------------------------------------ |
326| number | Curve interpolation corresponding to the normalized time point. |
327
328**Example**
329
330```ts
331import { curves } from '@kit.ArkUI'
332let curveValue = curves.initCurve(Curve.EaseIn) // Create an ease-in curve.
333let value: number = curveValue.interpolate(0.5) // Calculate the interpolation for half of the time.
334```
335
336
337## Curves.init<sup>(deprecated)</sup>
338
339init(curve?: Curve): string
340
341
342Implements initialization to create a curve. This API is deprecated since API version 9. You are advised to use [Curves.initCurve](#curvesinitcurve9) instead.
343
344**System capability**: SystemCapability.ArkUI.ArkUI.Full
345
346**Parameters**
347
348| Name | Type           | Mandatory | Description                               |
349| ------ | --------------- | ---- | ----------------------------------- |
350| curve  | [Curve](#curve) | No  | Curve type.<br>Default value: **Curve.Linear** |
351
352
353## Curves.steps<sup>(deprecated)</sup>
354
355steps(count: number, end: boolean): string
356
357
358Creates a step curve. This API is deprecated since API version 9. You are advised to use [Curves.stepsCurve](#curvesstepscurve9) instead.
359
360**System capability**: SystemCapability.ArkUI.ArkUI.Full
361
362**Parameters**
363
364| Name | Type   | Mandatory | Description                                                        |
365| ------ | ------- | ----| ------------------------------------------------------------ |
366| count  | number  | Yes  | Number of steps. The value must be a positive integer.                                  |
367| 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. |
368
369
370## Curves.cubicBezier<sup>(deprecated)</sup>
371
372cubicBezier(x1: number, y1: number, x2: number, y2: number): string
373
374
375Creates 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.
376
377**System capability**: SystemCapability.ArkUI.ArkUI.Full
378
379**Parameters**
380| Name | Type    | Mandatory  | Description            |
381| ---- | ------ | ---- | -------------- |
382| x1   | number | Yes   | X coordinate of the first point on the Bezier curve. |
383| y1   | number | Yes   | Y coordinate of the first point on the Bezier curve. |
384| x2   | number | Yes   | X coordinate of the second point on the Bezier curve. |
385| y2   | number | Yes   | Y coordinate of the second point on the Bezier curve. |
386
387
388## Curves.spring<sup>(deprecated)</sup>
389
390spring(velocity: number, mass: number, stiffness: number, damping: number): string
391
392
393Creates a spring curve. This API is deprecated since API version 9. You are advised to use [Curves.springCurve](#curvesspringcurve9) instead.
394
395**System capability**: SystemCapability.ArkUI.ArkUI.Full
396
397**Parameters**
398
399| Name      | Type    | Mandatory  | Description   |
400| --------- | ------ | ---- | ----- |
401| 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. |
402| 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. |
403| 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. |
404| 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. |
405
406## Example
407
408```ts
409// xxx.ets
410import { curves } from '@kit.ArkUI'
411
412@Entry
413@Component
414struct ImageComponent {
415  @State widthSize: number = 200
416  @State heightSize: number = 200
417
418  build() {
419    Column() {
420      Text()
421        .margin({ top: 100 })
422        .width(this.widthSize)
423        .height(this.heightSize)
424        .backgroundColor(Color.Red)
425        .onClick(() => {
426          let curve = curves.cubicBezierCurve(0.25, 0.1, 0.25, 1.0);
427          this.widthSize = curve.interpolate(0.5) * this.widthSize;
428          this.heightSize = curve.interpolate(0.5) * this.heightSize;
429        })
430        .animation({ duration: 2000, curve: curves.stepsCurve(9, true) })
431    }.width("100%").height("100%")
432  }
433}
434```
435
436![en-us_image_0000001174104410](figures/en-us_image_0000001174104410.gif)
437