• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 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 * Defines the ParticleOptions Interface.
18 * @interface ParticleOptions
19 * @syscap SystemCapability.ArkUI.ArkUI.Full
20 * @crossplatform
21 * @since 10
22 */
23interface ParticleOptions<
24  PARTICLE extends ParticleType,
25  COLOR_UPDATER extends ParticleUpdater,
26  OPACITY_UPDATER extends ParticleUpdater,
27  SCALE_UPDATER extends ParticleUpdater,
28  ACC_SPEED_UPDATER extends ParticleUpdater,
29  ACC_ANGLE_UPDATER extends ParticleUpdater,
30  SPIN_UPDATER extends ParticleUpdater
31> {
32  /**
33   * Particle emitter.
34   * @type { EmitterOptions<PARTICLE> }
35   * @syscap SystemCapability.ArkUI.ArkUI.Full
36   * @crossplatform
37   * @since 10
38   */
39  emitter: EmitterOptions<PARTICLE>;
40
41  /**
42   * Particle color.
43   * @type { ?ParticleColorPropertyOptions<COLOR_UPDATER> }
44   * @default {range:['#FFFFFF','#FFFFFF']}
45   * @syscap SystemCapability.ArkUI.ArkUI.Full
46   * @crossplatform
47   * @since 10
48   */
49  color?: ParticleColorPropertyOptions<COLOR_UPDATER>;
50
51  /**
52   * Particle opacity.
53   * @type { ?ParticlePropertyOptions<number, OPACITY_UPDATER> }
54   * @default {range:[1.0,1.0]}
55   * @syscap SystemCapability.ArkUI.ArkUI.Full
56   * @crossplatform
57   * @since 10
58   */
59  opacity?: ParticlePropertyOptions<number, OPACITY_UPDATER>;
60
61  /**
62   * Particle scale.
63   * @type { ?ParticlePropertyOptions<number, SCALE_UPDATER> }
64   * @default {range:[1.0,1.0]}
65   * @syscap SystemCapability.ArkUI.ArkUI.Full
66   * @crossplatform
67   * @since 10
68   */
69  scale?: ParticlePropertyOptions<number, SCALE_UPDATER>;
70
71  /**
72   * Particle velocity.
73   * @type { ?object }
74   * @default {speed:[0,0];angle:[0,0]}
75   * @syscap SystemCapability.ArkUI.ArkUI.Full
76   * @crossplatform
77   * @since 10
78   */
79  velocity?: {
80    speed: [number, number];
81    angle: [number, number];
82  };
83
84  /**
85   * Particle acceleration.
86   * @type { ?object }
87   * @default {speed:{range:[0,0]};angle:{range:[0,0]}}
88   * @syscap SystemCapability.ArkUI.ArkUI.Full
89   * @crossplatform
90   * @since 10
91   */
92  acceleration?: {
93    speed?: ParticlePropertyOptions<number, ACC_SPEED_UPDATER>;
94    angle?: ParticlePropertyOptions<number, ACC_ANGLE_UPDATER>;
95  };
96
97  /**
98   * Particle spin.
99   * @type { ?ParticlePropertyOptions<number, SPIN_UPDATER> }
100   * @default {range:[0,0]}
101   * @syscap SystemCapability.ArkUI.ArkUI.Full
102   * @crossplatform
103   * @since 10
104   */
105  spin?: ParticlePropertyOptions<number, SPIN_UPDATER>;
106}
107
108/**
109 * Defines the parameters for a point-like particle.
110 * @interface PointParticleParameters
111 * @syscap SystemCapability.ArkUI.ArkUI.Full
112 * @crossplatform
113 * @since 10
114 */
115interface PointParticleParameters {
116  /**
117   * Particle radius.
118   * @type { VP }
119   * @syscap SystemCapability.ArkUI.ArkUI.Full
120   * @crossplatform
121   * @since 10
122   */
123  radius: VP;
124}
125
126/**
127 * Defines the parameters for an image-like particle.
128 * @interface ImageParticleParameters
129 * @syscap SystemCapability.ArkUI.ArkUI.Full
130 * @crossplatform
131 * @since 10
132 */
133interface ImageParticleParameters {
134  /**
135   * Particle image pixelMap.
136   * @type { ResourceStr }
137   * @syscap SystemCapability.ArkUI.ArkUI.Full
138   * @crossplatform
139   * @since 10
140   */
141  src: ResourceStr;
142
143  /**
144   * Particle image size.
145   * @type { [Dimension, Dimension] }
146   * @syscap SystemCapability.ArkUI.ArkUI.Full
147   * @crossplatform
148   * @since 10
149   */
150  size: [Dimension, Dimension];
151
152  /**
153   * Image fit.
154   * @type { ?ImageFit }
155   * @default ImageFit.Cover
156   * @syscap SystemCapability.ArkUI.ArkUI.Full
157   * @crossplatform
158   * @since 10
159   */
160  objectFit?: ImageFit;
161}
162
163/**
164 * Defines the particle configs.
165 * @interface ParticleConfigs
166 * @syscap SystemCapability.ArkUI.ArkUI.Full
167 * @crossplatform
168 * @since 10
169 */
170interface ParticleConfigs {
171  /**
172   * Point-like Particle.
173   * @type { PointParticleParameters }
174   * @syscap SystemCapability.ArkUI.ArkUI.Full
175   * @crossplatform
176   * @since 10
177   */
178  [ParticleType.POINT]: PointParticleParameters;
179
180  /**
181   * Image-like Particle.
182   * @type { ImageParticleParameters }
183   * @syscap SystemCapability.ArkUI.ArkUI.Full
184   * @crossplatform
185   * @since 10
186   */
187  [ParticleType.IMAGE]: ImageParticleParameters;
188}
189
190/**
191 * Defines the emitter Options.
192 * @interface EmitterOptions
193 * @syscap SystemCapability.ArkUI.ArkUI.Full
194 * @crossplatform
195 * @since 10
196 */
197interface EmitterOptions<PARTICLE extends ParticleType> {
198  /**
199   * Set particle config.
200   * @type { object }
201   * @syscap SystemCapability.ArkUI.ArkUI.Full
202   * @crossplatform
203   * @since 10
204   */
205  particle: {
206    /**
207     * Particle type.
208     * @type { PARTICLE }
209     * @syscap SystemCapability.ArkUI.ArkUI.Full
210     * @crossplatform
211     * @since 10
212     */
213    type: PARTICLE;
214    /**
215     * Particle config.
216     * @type { ParticleConfigs[PARTICLE] }
217     * @syscap SystemCapability.ArkUI.ArkUI.Full
218     * @crossplatform
219     * @since 10
220     */
221    config: ParticleConfigs[PARTICLE];
222
223    /**
224     * Particle count.
225     * @type { number }
226     * @syscap SystemCapability.ArkUI.ArkUI.Full
227     * @crossplatform
228     * @since 10
229     */
230    count: number;
231
232    /**
233     * Particle lifetime.
234     * @type { ?number }
235     * @default 1000
236     * @syscap SystemCapability.ArkUI.ArkUI.Full
237     * @crossplatform
238     * @since 10
239     */
240    lifetime?: number;
241  };
242
243  /**
244   * Emitting rate, that is, the number of particles produced per second.
245   * @type { ?number }
246   * @default 5
247   * @syscap SystemCapability.ArkUI.ArkUI.Full
248   * @crossplatform
249   * @since 10
250   */
251  emitRate?: number;
252
253  /**
254   * Shape of emitter.
255   * @type { ?ParticleEmitterShape }
256   * @default ParticleEmitterShape.RECTANGLE
257   * @syscap SystemCapability.ArkUI.ArkUI.Full
258   * @crossplatform
259   * @since 10
260   */
261  shape?: ParticleEmitterShape;
262
263  /**
264   * Position of emitter.
265   * The first element means X-axis location.
266   * The second element means the Y-axis location.
267   * @type { ?[Dimension, Dimension] }
268   * @default [0,0]
269   * @syscap SystemCapability.ArkUI.ArkUI.Full
270   * @crossplatform
271   * @since 10
272   */
273  position?: [Dimension, Dimension];
274
275  /**
276   * Size of emitter.
277   * The first element means emitter width.
278   * The second element means emitter height.
279   * @type { ?[Dimension, Dimension] }
280   * @default ['100%','100%']
281   * @syscap SystemCapability.ArkUI.ArkUI.Full
282   * @crossplatform
283   * @since 10
284   */
285  size?: [Dimension, Dimension];
286}
287
288/**
289 * Defines the particle property updater configs.
290 * @interface ParticlePropertyUpdaterConfigs
291 * @syscap SystemCapability.ArkUI.ArkUI.Full
292 * @crossplatform
293 * @since 10
294 */
295interface ParticlePropertyUpdaterConfigs<T> {
296  /**
297   * No effect of particle updater.
298   * @syscap SystemCapability.ArkUI.ArkUI.Full
299   * @crossplatform
300   * @since 10
301   */
302  [ParticleUpdater.NONE]: void;
303
304  /**
305   * Random effect of particle updater.
306   * @type { [T, T] }
307   * @syscap SystemCapability.ArkUI.ArkUI.Full
308   * @crossplatform
309   * @since 10
310   */
311  [ParticleUpdater.RANDOM]: [T, T];
312
313  /**
314   * Curve effect of particle updater.
315   * @type { Array<ParticlePropertyAnimation<T>> }
316   * @syscap SystemCapability.ArkUI.ArkUI.Full
317   * @crossplatform
318   * @since 10
319   */
320  [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<T>>;
321}
322
323/**
324 * Defines the particle property Options.
325 * @interface ParticlePropertyOptions
326 * @syscap SystemCapability.ArkUI.ArkUI.Full
327 * @crossplatform
328 * @since 10
329 */
330interface ParticlePropertyOptions<TYPE, UPDATER extends ParticleUpdater> {
331  /**
332   * Initial range, within which the initial value are randomly generated.
333   * @type { [TYPE, TYPE] }
334   * @syscap SystemCapability.ArkUI.ArkUI.Full
335   * @crossplatform
336   * @since 10
337   */
338  range: [TYPE, TYPE];
339
340  /**
341   * Particle property updater.
342   * @type { ?object }
343   * @default  {type:UPDATER.NONE;config:ParticlePropertyUpdaterConfigs<UPDATER.NONE>[UPDATER.NONE]}
344   * @syscap SystemCapability.ArkUI.ArkUI.Full
345   * @crossplatform
346   * @since 10
347   */
348  updater?: {
349    type: UPDATER;
350    config: ParticlePropertyUpdaterConfigs<TYPE>[UPDATER];
351  };
352}
353
354/**
355 * Defines the particle color property updater configs.
356 * @interface ParticleColorPropertyUpdaterConfigs
357 * @syscap SystemCapability.ArkUI.ArkUI.Full
358 * @crossplatform
359 * @since 10
360 */
361interface ParticleColorPropertyUpdaterConfigs {
362  /**
363   * No effect of particle color property updater.
364   * @syscap SystemCapability.ArkUI.ArkUI.Full
365   * @crossplatform
366   * @since 10
367   */
368  [ParticleUpdater.NONE]: void;
369
370  /**
371   * Random effect of particle color property updater.
372   * @type { object }
373   * @syscap SystemCapability.ArkUI.ArkUI.Full
374   * @crossplatform
375   * @since 10
376   */
377  [ParticleUpdater.RANDOM]: {
378    r: [number, number];
379    g: [number, number];
380    b: [number, number];
381    a: [number, number];
382  };
383
384  /**
385   * Curve effect of particle color property updater.
386   *
387   * @type { Array<ParticlePropertyAnimation<ResourceColor>> }
388   * @syscap SystemCapability.ArkUI.ArkUI.Full
389   * @crossplatform
390   * @since 10
391   */
392  [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<ResourceColor>>;
393}
394
395/**
396 * Defines the particle color property updater configs which can support generics.
397 * @interface ParticleColorPropertyOptions
398 * @syscap SystemCapability.ArkUI.ArkUI.Full
399 * @crossplatform
400 * @since 10
401 */
402interface ParticleColorPropertyOptions<UPDATER extends ParticleUpdater> {
403  /**
404   * Initial color range, within which the initial color is randomly generated.
405   * @type { [ResourceColor, ResourceColor] }
406   * @syscap SystemCapability.ArkUI.ArkUI.Full
407   * @crossplatform
408   * @since 10
409   */
410  range: [ResourceColor, ResourceColor];
411
412  /**
413   * Particle color property updater.
414   * @type { ?object }
415   * @default {type:UPDATER.NONE;config:ParticleColorPropertyUpdaterConfigs[UPDATER.NONE]}
416   * @syscap SystemCapability.ArkUI.ArkUI.Full
417   * @crossplatform
418   * @since 10
419   */
420  updater?: {
421    type: UPDATER;
422    config: ParticleColorPropertyUpdaterConfigs[UPDATER];
423  };
424}
425
426/**
427 * Defines the particle property lifecycle.
428 * @interface ParticlePropertyAnimation
429 * @syscap SystemCapability.ArkUI.ArkUI.Full
430 * @crossplatform
431 * @since 10
432 */
433interface ParticlePropertyAnimation<T> {
434  /**
435   * Start position of the particle animation.
436   * @type { T }
437   * @syscap SystemCapability.ArkUI.ArkUI.Full
438   * @crossplatform
439   * @since 10
440   */
441  from: T;
442
443  /**
444   * End position of the particle animation.
445   * @type { T }
446   * @syscap SystemCapability.ArkUI.ArkUI.Full
447   * @crossplatform
448   * @since 10
449   */
450  to: T;
451
452  /**
453   * Start millis of the particle animation.
454   * @type { number }
455   * @syscap SystemCapability.ArkUI.ArkUI.Full
456   * @crossplatform
457   * @since 10
458   */
459  startMillis: number;
460
461  /**
462   * End millis of the particle animation.
463   * @type { number }
464   * @syscap SystemCapability.ArkUI.ArkUI.Full
465   * @crossplatform
466   * @since 10
467   */
468  endMillis: number;
469
470  /**
471   * Curve of the particle animation.
472   * @type { ?(Curve | ICurve) }
473   * @syscap SystemCapability.ArkUI.ArkUI.Full
474   * @crossplatform
475   * @since 10
476   */
477  curve?: Curve | ICurve;
478}
479
480/**
481 * Defines the particle Interface.
482 * @interface ParticleInterface
483 * @syscap SystemCapability.ArkUI.ArkUI.Full
484 * @crossplatform
485 * @since 10
486 */
487interface ParticleInterface {
488  /**
489   * create a particle array.
490   * @param { object } value - Particle value
491   * particles - list of ParticleOptions.
492   * @returns { ParticleAttribute } Returns the particle attribute.
493   * @syscap SystemCapability.ArkUI.ArkUI.Full
494   * @crossplatform
495   * @since 10
496   */
497  <
498    PARTICLE extends ParticleType,
499    COLOR_UPDATER extends ParticleUpdater,
500    OPACITY_UPDATER extends ParticleUpdater,
501    SCALE_UPDATER extends ParticleUpdater,
502    ACC_SPEED_UPDATER extends ParticleUpdater,
503    ACC_ANGLE_UPDATER extends ParticleUpdater,
504    SPIN_UPDATER extends ParticleUpdater
505  >(value: {
506    particles: Array<
507    ParticleOptions<
508    PARTICLE,
509    COLOR_UPDATER,
510    OPACITY_UPDATER,
511    SCALE_UPDATER,
512    ACC_SPEED_UPDATER,
513    ACC_ANGLE_UPDATER,
514    SPIN_UPDATER
515    >
516    >;
517  }): ParticleAttribute;
518}
519
520/**
521 * Enumerates the particle types.
522 * @enum { string }
523 * @syscap SystemCapability.ArkUI.ArkUI.Full
524 * @crossplatform
525 * @since 10
526 */
527declare enum ParticleType {
528  /**
529   * Point-like particle.
530   * @syscap SystemCapability.ArkUI.ArkUI.Full
531   * @crossplatform
532   * @since 10
533   */
534  POINT = 'point',
535
536  /**
537   * Image-like particle.
538   * @syscap SystemCapability.ArkUI.ArkUI.Full
539   * @crossplatform
540   * @since 10
541   */
542  IMAGE = 'image',
543}
544
545/**
546 * Enumerates the emitter shapes of a particle.
547 * @enum { string }
548 * @syscap SystemCapability.ArkUI.ArkUI.Full
549 * @crossplatform
550 * @since 10
551 */
552declare enum ParticleEmitterShape {
553  /**
554   * Rectangle.
555   * @syscap SystemCapability.ArkUI.ArkUI.Full
556   * @crossplatform
557   * @since 10
558   */
559  RECTANGLE = 'rectangle',
560
561  /**
562   * Circle.
563   * @syscap SystemCapability.ArkUI.ArkUI.Full
564   * @crossplatform
565   * @since 10
566   */
567  CIRCLE = 'circle',
568
569  /**
570   * Ellipse.
571   * @syscap SystemCapability.ArkUI.ArkUI.Full
572   * @crossplatform
573   * @since 10
574   */
575  ELLIPSE = 'ellipse',
576}
577
578/**
579 * Enumerates the updater types of a particle.
580 * @enum { string }
581 * @syscap SystemCapability.ArkUI.ArkUI.Full
582 * @crossplatform
583 * @since 10
584 */
585declare enum ParticleUpdater {
586  /**
587   * No updater is used.
588   * @syscap SystemCapability.ArkUI.ArkUI.Full
589   * @crossplatform
590   * @since 10
591   */
592  NONE = 'none',
593
594  /**
595   * Random updater.
596   * @syscap SystemCapability.ArkUI.ArkUI.Full
597   * @crossplatform
598   * @since 10
599   */
600  RANDOM = 'random',
601
602  /**
603   * Curve updater.
604   * @syscap SystemCapability.ArkUI.ArkUI.Full
605   * @crossplatform
606   * @since 10
607   */
608  CURVE = 'curve',
609}
610
611/**
612 * Defines the Particle component attribute functions.
613 * @extends CommonMethod
614 * @syscap SystemCapability.ArkUI.ArkUI.Full
615 * @crossplatform
616 * @since 10
617 */
618declare class ParticleAttribute extends CommonMethod<ParticleAttribute> {}
619
620/**
621 * Defines Particle Component.
622 * @syscap SystemCapability.ArkUI.ArkUI.Full
623 * @crossplatform
624 * @since 10
625 */
626declare const Particle: ParticleInterface;
627