1/*
2 * Copyright (c) 2020-2023 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @file
18 * @kit ArkUI
19 */
20
21/**
22 * Defines the animator options.
23 * @interface AnimatorOptions
24 * @syscap SystemCapability.ArkUI.ArkUI.Full
25 * @since 6
26 */
27/**
28 * Defines the animator options.
29 * @interface AnimatorOptions
30 * @syscap SystemCapability.ArkUI.ArkUI.Full
31 * @crossplatform
32 * @since 10
33 */
34/**
35 * Defines the animator options.
36 * @interface AnimatorOptions
37 * @syscap SystemCapability.ArkUI.ArkUI.Full
38 * @crossplatform
39 * @atomicservice
40 * @since 11
41 */
42export interface AnimatorOptions {
43  /**
44   * Duration of the animation, in milliseconds.
45   * The default value is 0.
46   * @type {number}
47   * @syscap SystemCapability.ArkUI.ArkUI.Full
48   * @since 6
49   */
50  /**
51   * Duration of the animation, in milliseconds.
52   * The default value is 0.
53   * @type {number}
54   * @syscap SystemCapability.ArkUI.ArkUI.Full
55   * @crossplatform
56   * @since 10
57   */
58  /**
59   * Duration of the animation, in milliseconds.
60   * The default value is 0.
61   * @type {number}
62   * @syscap SystemCapability.ArkUI.ArkUI.Full
63   * @crossplatform
64   * @atomicservice
65   * @since 11
66   */
67  duration: number;
68
69  /**
70   * Time curve of the animation. For details about the supported types.
71   * linear The animation speed keeps unchanged.
72   * ease The animation starts and ends at a low speed, cubic-bezier(0.25, 0.1, 0.25, 1.0).
73   * ease-in The animation starts at a low speed, cubic-bezier(0.42, 0.0, 1.0, 1.0).
74   * ease-out The animation ends at a low speed, cubic-bezier(0.0, 0.0, 0.58, 1.0).
75   * ease-in-out The animation starts and ends at a low speed, cubic-bezier(0.42, 0.0, 0.58, 1.0).
76   * fast-out-slow-in Standard curve, cubic-bezier(0.4, 0.0, 0.2, 1.0).
77   * linear-out-slow-in Deceleration curve, cubic-bezier(0.0, 0.0, 0.2, 1.0).
78   * fast-out-linear-in Acceleration curve, cubic-bezier(0.4, 0.0, 1.0, 1.0).
79   * friction Damping curve, cubic-bezier(0.2, 0.0, 0.2, 1.0).
80   * extreme-deceleration Extreme deceleration curve, cubic-bezier(0.0, 0.0, 0.0, 1.0).
81   * sharp Sharp curve, cubic-bezier(0.33, 0.0, 0.67, 1.0).
82   * rhythm Rhythm curve, cubic-bezier(0.7, 0.0, 0.2, 1.0).
83   * smooth Smooth curve, cubic-bezier(0.4, 0.0, 0.4, 1.0).
84   * cubic-bezier(x1, y1, x2, y2) You can customize an animation speed curve in the cubic-bezier() function. The x and y values of each input parameter must be between 0 and 1.
85   * Step curve. The number must be set and only an integer is supported, step-position is optional. It can be set to start or end. The default value is end.
86   * The default value is ease.
87   * @type {string}
88   * @syscap SystemCapability.ArkUI.ArkUI.Full
89   * @since 6
90   */
91  /**
92   * Time curve of the animation. For details about the supported types.
93   * linear The animation speed keeps unchanged.
94   * ease The animation starts and ends at a low speed, cubic-bezier(0.25, 0.1, 0.25, 1.0).
95   * ease-in The animation starts at a low speed, cubic-bezier(0.42, 0.0, 1.0, 1.0).
96   * ease-out The animation ends at a low speed, cubic-bezier(0.0, 0.0, 0.58, 1.0).
97   * ease-in-out The animation starts and ends at a low speed, cubic-bezier(0.42, 0.0, 0.58, 1.0).
98   * fast-out-slow-in Standard curve, cubic-bezier(0.4, 0.0, 0.2, 1.0).
99   * linear-out-slow-in Deceleration curve, cubic-bezier(0.0, 0.0, 0.2, 1.0).
100   * fast-out-linear-in Acceleration curve, cubic-bezier(0.4, 0.0, 1.0, 1.0).
101   * friction Damping curve, cubic-bezier(0.2, 0.0, 0.2, 1.0).
102   * extreme-deceleration Extreme deceleration curve, cubic-bezier(0.0, 0.0, 0.0, 1.0).
103   * sharp Sharp curve, cubic-bezier(0.33, 0.0, 0.67, 1.0).
104   * rhythm Rhythm curve, cubic-bezier(0.7, 0.0, 0.2, 1.0).
105   * smooth Smooth curve, cubic-bezier(0.4, 0.0, 0.4, 1.0).
106   * cubic-bezier(x1, y1, x2, y2) You can customize an animation speed curve in the cubic-bezier() function. The x and y values of each input parameter must be between 0 and 1.
107   * Step curve. The number must be set and only an integer is supported, step-position is optional. It can be set to start or end. The default value is end.
108   * The default value is ease.
109   * @type {string}
110   * @syscap SystemCapability.ArkUI.ArkUI.Full
111   * @crossplatform
112   * @since 10
113   */
114  /**
115   * Time curve of the animation. For details about the supported types.
116   * linear The animation speed keeps unchanged.
117   * ease The animation starts and ends at a low speed, cubic-bezier(0.25, 0.1, 0.25, 1.0).
118   * ease-in The animation starts at a low speed, cubic-bezier(0.42, 0.0, 1.0, 1.0).
119   * ease-out The animation ends at a low speed, cubic-bezier(0.0, 0.0, 0.58, 1.0).
120   * ease-in-out The animation starts and ends at a low speed, cubic-bezier(0.42, 0.0, 0.58, 1.0).
121   * fast-out-slow-in Standard curve, cubic-bezier(0.4, 0.0, 0.2, 1.0).
122   * linear-out-slow-in Deceleration curve, cubic-bezier(0.0, 0.0, 0.2, 1.0).
123   * fast-out-linear-in Acceleration curve, cubic-bezier(0.4, 0.0, 1.0, 1.0).
124   * friction Damping curve, cubic-bezier(0.2, 0.0, 0.2, 1.0).
125   * extreme-deceleration Extreme deceleration curve, cubic-bezier(0.0, 0.0, 0.0, 1.0).
126   * sharp Sharp curve, cubic-bezier(0.33, 0.0, 0.67, 1.0).
127   * rhythm Rhythm curve, cubic-bezier(0.7, 0.0, 0.2, 1.0).
128   * smooth Smooth curve, cubic-bezier(0.4, 0.0, 0.4, 1.0).
129   * cubic-bezier(x1, y1, x2, y2) You can customize an animation speed curve in the cubic-bezier() function. The x and y values of each input parameter must be between 0 and 1.
130   * Step curve. The number must be set and only an integer is supported, step-position is optional. It can be set to start or end. The default value is end.
131   * interpolating-spring(velocity, mass, stiffness, damping), interpolating spring curve.
132   * The default value is ease.
133   * @type {string}
134   * @syscap SystemCapability.ArkUI.ArkUI.Full
135   * @crossplatform
136   * @atomicservice
137   * @since 11
138   */
139  easing: string;
140
141  /**
142   * Delay for the animation start. The default value indicates no delay.
143   * The default value is 0.
144   * @type {number}
145   * @syscap SystemCapability.ArkUI.ArkUI.Full
146   * @since 6
147   */
148  /**
149   * Delay for the animation start. The default value indicates no delay.
150   * The default value is 0.
151   * @type {number}
152   * @syscap SystemCapability.ArkUI.ArkUI.Full
153   * @crossplatform
154   * @since 10
155   */
156  /**
157   * Delay for the animation start. The default value indicates no delay.
158   * The default value is 0.
159   * @type {number}
160   * @syscap SystemCapability.ArkUI.ArkUI.Full
161   * @crossplatform
162   * @atomicservice
163   * @since 11
164   */
165  delay: number;
166
167  /**
168   * Whether to resume to the initial state after the animation is executed.
169   * none: The initial state is restored after the animation is executed.
170   * forwards: The state at the end of the animation (defined in the last key frame) is retained after the animation is executed.
171   * @type {"none" | "forwards" | "backwards" | "both"}
172   * @syscap SystemCapability.ArkUI.ArkUI.Full
173   * @since 6
174   */
175  /**
176   * Whether to resume to the initial state after the animation is executed.
177   * none: The initial state is restored after the animation is executed.
178   * forwards: The state at the end of the animation (defined in the last key frame) is retained after the animation is executed.
179   * @type {"none" | "forwards" | "backwards" | "both"}
180   * @syscap SystemCapability.ArkUI.ArkUI.Full
181   * @crossplatform
182   * @since 10
183   */
184  /**
185   * Whether to resume to the initial state after the animation is executed.
186   * none: The initial state is restored after the animation is executed.
187   * forwards: The state at the end of the animation (defined in the last key frame) is retained after the animation is executed.
188   * @type {"none" | "forwards" | "backwards" | "both"}
189   * @syscap SystemCapability.ArkUI.ArkUI.Full
190   * @crossplatform
191   * @atomicservice
192   * @since 11
193   */
194  fill: "none" | "forwards" | "backwards" | "both";
195
196  /**
197   * The animation playback mode.
198   * The default value is "normal".
199   * @type {"normal" | "reverse" | "alternate" | "alternate-reverse"}
200   * @syscap SystemCapability.ArkUI.ArkUI.Full
201   * @since 6
202   */
203  /**
204   * The animation playback mode.
205   * The default value is "normal".
206   * @type {"normal" | "reverse" | "alternate" | "alternate-reverse"}
207   * @syscap SystemCapability.ArkUI.ArkUI.Full
208   * @crossplatform
209   * @since 10
210   */
211  /**
212   * The animation playback mode.
213   * The default value is "normal".
214   * @type {"normal" | "reverse" | "alternate" | "alternate-reverse"}
215   * @syscap SystemCapability.ArkUI.ArkUI.Full
216   * @crossplatform
217   * @atomicservice
218   * @since 11
219   */
220  direction: "normal" | "reverse" | "alternate" | "alternate-reverse";
221
222  /**
223   * Number of times the animation will be played. number indicates a fixed number of playback operations, and -1 an unlimited number of playback operations.
224   * The default value is 1.
225   * @type {number}
226   * @syscap SystemCapability.ArkUI.ArkUI.Full
227   * @since 6
228   */
229  /**
230   * Number of times the animation will be played. number indicates a fixed number of playback operations, and -1 an unlimited number of playback operations.
231   * The default value is 1.
232   * @type {number}
233   * @syscap SystemCapability.ArkUI.ArkUI.Full
234   * @crossplatform
235   * @since 10
236   */
237  /**
238   * Number of times the animation will be played. number indicates a fixed number of playback operations, and -1 an unlimited number of playback operations.
239   * The default value is 1.
240   * @type {number}
241   * @syscap SystemCapability.ArkUI.ArkUI.Full
242   * @crossplatform
243   * @atomicservice
244   * @since 11
245   */
246  iterations: number;
247
248  /**
249   * Starting point of animator interpolation.
250   * The default value is 0.
251   * @type {number}
252   * @syscap SystemCapability.ArkUI.ArkUI.Full
253   * @since 6
254   */
255  /**
256   * Starting point of animator interpolation.
257   * The default value is 0.
258   * @type {number}
259   * @syscap SystemCapability.ArkUI.ArkUI.Full
260   * @crossplatform
261   * @since 10
262   */
263  /**
264   * Starting point of animator interpolation.
265   * The default value is 0.
266   * @type {number}
267   * @syscap SystemCapability.ArkUI.ArkUI.Full
268   * @crossplatform
269   * @atomicservice
270   * @since 11
271   */
272  begin: number;
273
274  /**
275   * Ending point of Dynamic Interpolation
276   * The default value is 1.
277   * @type {number}
278   * @syscap SystemCapability.ArkUI.ArkUI.Full
279   * @since 6
280   */
281  /**
282   * Ending point of Dynamic Interpolation
283   * The default value is 1.
284   * @type {number}
285   * @syscap SystemCapability.ArkUI.ArkUI.Full
286   * @crossplatform
287   * @since 10
288   */
289  /**
290   * Ending point of Dynamic Interpolation
291   * The default value is 1.
292   * @type {number}
293   * @syscap SystemCapability.ArkUI.ArkUI.Full
294   * @crossplatform
295   * @atomicservice
296   * @since 11
297   */
298  end: number;
299}
300
301/**
302 * Defines the Animator result interface.
303 * @interface AnimatorResult
304 * @syscap SystemCapability.ArkUI.ArkUI.Full
305 * @since 6
306 */
307/**
308 * Defines the Animator result interface.
309 * @interface AnimatorResult
310 * @syscap SystemCapability.ArkUI.ArkUI.Full
311 * @crossplatform
312 * @since 10
313 */
314/**
315 * Defines the Animator result interface.
316 * @interface AnimatorResult
317 * @syscap SystemCapability.ArkUI.ArkUI.Full
318 * @crossplatform
319 * @atomicservice
320 * @since 11
321 */
322export interface AnimatorResult {
323  /**
324   * Update the options for current animator.
325   * @param { AnimatorOptions } options - Options.
326   * @syscap SystemCapability.ArkUI.ArkUI.Full
327   * @since 6
328   * @deprecated since 9
329   * @useinstead ohos.animator.reset
330   */
331  update(options: AnimatorOptions): void;
332
333  /**
334   * Reset the options for current animator.
335   * @param { AnimatorOptions } options - Options.
336   * @throws { BusinessError } 401 - Parameter error. Possible causes: 
337   * <br> 1. Mandatory parameters are left unspecified.
338   * <br> 2. Incorrect parameters types.
339   * <br> 3. Parameter verification failed.
340   * @throws { BusinessError } 100001 - The specified page is not found or the object property list is not obtained.
341   * @syscap SystemCapability.ArkUI.ArkUI.Full
342   * @since 9
343   */
344  /**
345   * Reset the options for current animator.
346   * @param { AnimatorOptions } options - Options.
347   * @throws { BusinessError } 401 - Parameter error. Possible causes: 
348   * <br> 1. Mandatory parameters are left unspecified.
349   * <br> 2. Incorrect parameters types.
350   * <br> 3. Parameter verification failed.
351   * @throws { BusinessError } 100001 - The specified page is not found or the object property list is not obtained.
352   * @syscap SystemCapability.ArkUI.ArkUI.Full
353   * @crossplatform
354   * @since 10
355   */
356  /**
357   * Reset the options for current animator.
358   * @param { AnimatorOptions } options - Options.
359   * @throws { BusinessError } 401 - Parameter error. Possible causes: 
360   * <br> 1. Mandatory parameters are left unspecified.
361   * <br> 2. Incorrect parameters types.
362   * <br> 3. Parameter verification failed.
363   * @throws { BusinessError } 100001 - The specified page is not found or the object property list is not obtained.
364   * @syscap SystemCapability.ArkUI.ArkUI.Full
365   * @crossplatform
366   * @atomicservice
367   * @since 11
368   */
369  reset(options: AnimatorOptions): void;
370
371  /**
372   * Starts the animation.
373   * @syscap SystemCapability.ArkUI.ArkUI.Full
374   * @since 6
375   */
376  /**
377   * Starts the animation.
378   * @syscap SystemCapability.ArkUI.ArkUI.Full
379   * @crossplatform
380   * @since 10
381   */
382  /**
383   * Starts the animation.
384   * @syscap SystemCapability.ArkUI.ArkUI.Full
385   * @crossplatform
386   * @atomicservice
387   * @since 11
388   */
389  play(): void;
390
391  /**
392   * Ends the animation.
393   * @syscap SystemCapability.ArkUI.ArkUI.Full
394   * @since 6
395   */
396  /**
397   * Ends the animation.
398   * @syscap SystemCapability.ArkUI.ArkUI.Full
399   * @crossplatform
400   * @since 10
401   */
402  /**
403   * Ends the animation.
404   * @syscap SystemCapability.ArkUI.ArkUI.Full
405   * @crossplatform
406   * @atomicservice
407   * @since 11
408   */
409  finish(): void;
410
411  /**
412   * Pauses the animation.
413   * @syscap SystemCapability.ArkUI.ArkUI.Full
414   * @since 6
415   */
416  /**
417   * Pauses the animation.
418   * @syscap SystemCapability.ArkUI.ArkUI.Full
419   * @crossplatform
420   * @since 10
421   */
422  /**
423   * Pauses the animation.
424   * @syscap SystemCapability.ArkUI.ArkUI.Full
425   * @crossplatform
426   * @atomicservice
427   * @since 11
428   */
429  pause(): void;
430
431  /**
432   * Cancels the animation.
433   * @syscap SystemCapability.ArkUI.ArkUI.Full
434   * @since 6
435   */
436  /**
437   * Cancels the animation.
438   * @syscap SystemCapability.ArkUI.ArkUI.Full
439   * @crossplatform
440   * @since 10
441   */
442  /**
443   * Cancels the animation.
444   * @syscap SystemCapability.ArkUI.ArkUI.Full
445   * @crossplatform
446   * @atomicservice
447   * @since 11
448   */
449  cancel(): void;
450
451  /**
452   * Plays the animation in reverse direction.
453   * @syscap SystemCapability.ArkUI.ArkUI.Full
454   * @since 6
455   */
456  /**
457   * Plays the animation in reverse direction.
458   * @syscap SystemCapability.ArkUI.ArkUI.Full
459   * @crossplatform
460   * @since 10
461   */
462  /**
463   * Plays the animation in reverse direction.
464   * Invalid when using interpolating-spring curve.
465   * @syscap SystemCapability.ArkUI.ArkUI.Full
466   * @crossplatform
467   * @atomicservice
468   * @since 11
469   */
470  reverse(): void;
471
472  /**
473   * Trigger when vsync callback.
474   * @syscap SystemCapability.ArkUI.ArkUI.Full
475   * @since 6
476   */
477  /**
478   * Trigger when vsync callback.
479   * @syscap SystemCapability.ArkUI.ArkUI.Full
480   * @crossplatform
481   * @since 10
482   */
483  /**
484   * Trigger when vsync callback.
485   * @syscap SystemCapability.ArkUI.ArkUI.Full
486   * @crossplatform
487   * @atomicservice
488   * @since 11
489   * @deprecated since 12
490   * @useinstead ohos.animator.onFrame
491   */
492  onframe: (progress: number) => void;
493
494  /**
495   * Trigger when vSync callback.
496   *
497   * @type { function }
498   * @syscap SystemCapability.ArkUI.ArkUI.Full
499   * @crossplatform
500   * @atomicservice
501   * @since 12
502   */
503  onFrame: (progress: number) => void;
504
505  /**
506   * The animation is finished.
507   * @syscap SystemCapability.ArkUI.ArkUI.Full
508   * @since 6
509   */
510  /**
511   * The animation is finished.
512   * @syscap SystemCapability.ArkUI.ArkUI.Full
513   * @crossplatform
514   * @since 10
515   */
516  /**
517   * The animation is finished.
518   * @syscap SystemCapability.ArkUI.ArkUI.Full
519   * @crossplatform
520   * @atomicservice
521   * @since 11
522   * @deprecated since 12
523   * @useinstead ohos.animator.onFinish
524   */
525  onfinish: () => void;
526
527  /**
528   * The animation is finished.
529   *
530   * @type { function }
531   * @syscap SystemCapability.ArkUI.ArkUI.Full
532   * @crossplatform
533   * @atomicservice
534   * @since 12
535   */
536  onFinish: () => void;
537
538  /**
539   * The animation is canceled.
540   * @syscap SystemCapability.ArkUI.ArkUI.Full
541   * @since 6
542   */
543  /**
544   * The animation is canceled.
545   * @syscap SystemCapability.ArkUI.ArkUI.Full
546   * @crossplatform
547   * @since 10
548   */
549  /**
550   * The animation is canceled.
551   * @syscap SystemCapability.ArkUI.ArkUI.Full
552   * @crossplatform
553   * @atomicservice
554   * @since 11
555   * @deprecated since 12
556   * @useinstead ohos.animator.onCancel
557   */
558  oncancel: () => void;
559
560  /**
561   * The animation is canceled.
562   *
563   * @type { function }
564   * @syscap SystemCapability.ArkUI.ArkUI.Full
565   * @crossplatform
566   * @atomicservice
567   * @since 12
568   */
569  onCancel: () => void;
570
571  /**
572   * The animation is repeated.
573   * @syscap SystemCapability.ArkUI.ArkUI.Full
574   * @since 6
575   */
576  /**
577   * The animation is repeated.
578   * @syscap SystemCapability.ArkUI.ArkUI.Full
579   * @crossplatform
580   * @since 10
581   */
582  /**
583   * The animation is repeated.
584   * @syscap SystemCapability.ArkUI.ArkUI.Full
585   * @crossplatform
586   * @atomicservice
587   * @since 11
588   * @deprecated since 12
589   * @useinstead ohos.animator.onRepeat
590   */
591  onrepeat: () => void;
592
593  /**
594   * The animation is repeated.
595   *
596   * @type { function }
597   * @syscap SystemCapability.ArkUI.ArkUI.Full
598   * @crossplatform
599   * @atomicservice
600   * @since 12
601   */
602  onRepeat: () => void;
603
604  /**
605   * The expected frame rate of dynamical of rate range.
606   * @param { ExpectedFrameRateRange } rateRange - Indicates ExpectedFrameRateRange.
607   * @syscap SystemCapability.ArkUI.ArkUI.Full
608   * @atomicservice
609   * @since 12
610   */
611  setExpectedFrameRateRange(rateRange: ExpectedFrameRateRange): void;
612}
613
614/**
615 * Defines the Animator class.
616 * @syscap SystemCapability.ArkUI.ArkUI.Full
617 * @since 6
618 */
619/**
620 * Defines the Animator class.
621 * @syscap SystemCapability.ArkUI.ArkUI.Full
622 * @crossplatform
623 * @since 10
624 */
625/**
626 * Defines the Animator class.
627 * @syscap SystemCapability.ArkUI.ArkUI.Full
628 * @crossplatform
629 * @atomicservice
630 * @since 11
631 */
632export default class Animator {
633  /**
634   * Create an animator object for custom animation.
635   * @param { AnimatorOptions } options - Options.
636   * @returns { AnimatorResult } animator result
637   * @syscap SystemCapability.ArkUI.ArkUI.Full
638   * @since 6
639   * @deprecated since 9
640   * @useinstead ohos.animator.create
641   */
642  static createAnimator(options: AnimatorOptions): AnimatorResult;
643
644  /**
645   * Create an animator object for custom animation.
646   * @param { AnimatorOptions } options - Options.
647   * @returns { AnimatorResult } animator result
648   * @throws { BusinessError } 401 - Parameter error. Possible causes: 
649   * <br> 1. Mandatory parameters are left unspecified.
650   * <br> 2. Incorrect parameters types.
651   * <br> 3. Parameter verification failed.
652   * @syscap SystemCapability.ArkUI.ArkUI.Full
653   * @since 9
654   */
655  /**
656   * Create an animator object for custom animation.
657   * @param { AnimatorOptions } options - Options.
658   * @returns { AnimatorResult } animator result
659   * @throws { BusinessError } 401 - Parameter error. Possible causes: 
660   * <br> 1. Mandatory parameters are left unspecified.
661   * <br> 2. Incorrect parameters types.
662   * <br> 3. Parameter verification failed.
663   * @syscap SystemCapability.ArkUI.ArkUI.Full
664   * @crossplatform
665   * @since 10
666   */
667  /**
668   * Create an animator object for custom animation.
669   * @param { AnimatorOptions } options - Options.
670   * @returns { AnimatorResult } animator result
671   * @throws { BusinessError } 401 - Parameter error. Possible causes: 
672   * <br> 1. Mandatory parameters are left unspecified.
673   * <br> 2. Incorrect parameters types.
674   * <br> 3. Parameter verification failed.
675   * @syscap SystemCapability.ArkUI.ArkUI.Full
676   * @crossplatform
677   * @atomicservice
678   * @since 11
679   */
680  static create(options: AnimatorOptions): AnimatorResult;
681}
682