1# Particle Animation (Particle) 2 3Particle animation is an animation composed of a multitude of particles randomly generated within a certain range. The particles can be points or images. By animating different aspects of the particles, such as color, opacity, scale, velocity, acceleration, and spin angle, you can create engaging and dynamic aesthetics. For example, you can create an impressive snowfall animation by animating the particles – snowflakes. 4 5The component used for producing particle animations is **Particle**. 6 7 8> **NOTE** 9> 10> This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 11 12 13## Child Components 14 15Not supported 16 17 18## APIs 19 20```typescript 21interface ParticleInterface { 22 < 23 PARTICLE extends ParticleType, 24 COLOR_UPDATER extends ParticleUpdater, 25 OPACITY_UPDATER extends ParticleUpdater, 26 SCALE_UPDATER extends ParticleUpdater, 27 ACC_SPEED_UPDATER extends ParticleUpdater, 28 ACC_ANGLE_UPDATER extends ParticleUpdater, 29 SPIN_UPDATER extends ParticleUpdater 30 >(value: { 31 particles: Array< 32 ParticleOptions< 33 PARTICLE, 34 COLOR_UPDATER, 35 OPACITY_UPDATER, 36 SCALE_UPDATER, 37 ACC_SPEED_UPDATER, 38 ACC_ANGLE_UPDATER, 39 SPIN_UPDATER 40 > 41 >; 42 }): ParticleAttribute; 43} 44``` 45 46**Atomic service API**: This API can be used in atomic services since API version 11. 47 48**Parameters** 49 50| Name| Type| Mandatory| Description| 51| -------- | -------- | -------- | -------- | 52| value | {<br>particles:Array<[ParticleOptions](#particleoptions)<<br>[PARTICLE](#particletype), <br>[COLOR_UPDATER](#particleupdater),<br>[OPACITY_UPDATER](#particleupdater),<br>[SCALE_UPDATER](#particleupdater),<br>[ACC_SPEED_UPDATER](#particleupdater),<br> [ACC_ANGLE_UPDATER](#particleupdater),<br>[SPIN_UPDATER](#particleupdater)<br>>><br>} | Yes| An array of particle options, each of which covers the emitter, color, opacity, scale, velocity, acceleration, and spin speed of particles. For details, see [ParticleOptions](#particleoptions). 53 54## Attributes 55 56In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 57 58### disturbanceFields<sup>12+</sup> 59 60disturbanceFields(fields: Array<DisturbanceFieldOptions>) 61 62Sets the disturbance fields. 63 64**Atomic service API**: This API can be used in atomic services since API version 12. 65 66**System capability**: SystemCapability.ArkUI.ArkUI.Full 67 68**Parameters** 69 70| Name| Type | Mandatory| Description | 71| ------ | ------- | ---- | ---------------------------- | 72| fields | Array<[DisturbanceFieldOptions](#disturbancefieldoptions12)> | Yes | Array of disturbance fields.| 73 74### emitter<sup>12+</sup> 75emitter(value: Array<EmitterProperty>) 76 77Sets the emitter parameters. 78 79**Atomic service API**: This API can be used in atomic services since API version 12. 80 81**System capability**: SystemCapability.ArkUI.ArkUI.Full 82 83**Parameters** 84 85| Name| Type | Mandatory| Description | 86| ------ | ------- | ---- | ---------------------------- | 87| value | Array<[EmitterProperty](#emitterproperty12)> | Yes | Array of emitter parameters to set.| 88 89## Events 90The [universal events](ts-universal-events-click.md) are supported. 91 92## ParticleOptions 93 94```typescript 95interface ParticleOptions< 96 PARTICLE extends ParticleType, 97 COLOR_UPDATER extends ParticleUpdater, 98 OPACITY_UPDATER extends ParticleUpdater, 99 SCALE_UPDATER extends ParticleUpdater, 100 ACC_SPEED_UPDATER extends ParticleUpdater, 101 ACC_ANGLE_UPDATER extends ParticleUpdater, 102 SPIN_UPDATER extends ParticleUpdater 103> { 104 emitter: EmitterOptions<PARTICLE>; 105 color?: ParticleColorPropertyOptions<COLOR_UPDATER>; 106 opacity?: ParticlePropertyOptions<number, OPACITY_UPDATER>; 107 scale?: ParticlePropertyOptions<number, SCALE_UPDATER>; 108 velocity?: { 109 speed: [number, number]; 110 angle: [number, number]; 111 }; 112 acceleration?: { 113 speed?: ParticlePropertyOptions<number, ACC_SPEED_UPDATER>; 114 angle?: ParticlePropertyOptions<number, ACC_ANGLE_UPDATER>; 115 }; 116 spin?: ParticlePropertyOptions<number, SPIN_UPDATER>; 117} 118``` 119 120**Atomic service API**: This API can be used in atomic services since API version 11. 121 122**System capability**: SystemCapability.ArkUI.ArkUI.Full 123 124| Name| Type| Mandatory| Description| 125| -------- | -------- | -------- | -------- | 126| emitter | [EmitterOptions](#emitteroptions)<[PARTICLE](#particletype)> | Yes| Particle emitter.| 127| color | [ParticleColorPropertyOptions](#particlecolorpropertyoptions)<[COLOR_UPDATER](#particleupdater)> | No| Particle color.<br>**NOTE**<br>Default value: **{ range:[Color.White,Color.White] }.** Colors cannot be set for image particles.| 128| opacity | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [OPACITY_UPDATER](#particleupdater)> | No| Particle opacity.<br>Default value: **{ range:[1.0,1.0] }**| 129| scale | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [SCALE_UPDATER](#particleupdater)> | No| Particle scale.<br>Default value: **{ range:[1.0,1.0] }**| 130| velocity | {<br>speed: [number, number];<br>angle: [number, number];<br>} |No| Particle velocity.<br>**NOTE**<br>**speed** indicates the time rate at which the particle moves. **angle** indicates the direction (in angles) in which the particle moves, with the geometric center of the element as the coordinate origin and the horizontal direction as the x-axis. A positive number indicates clockwise rotation.<br>Default value: **{speed: [0.0,0.0],angle: [0.0,0.0] }**| 131| acceleration | {<br>speed?: [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_SPEED_UPDATER](#particleupdater)>;<br>angle?: [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_ANGLE_UPDATER](#particleupdater)>;<br>} | No| Particle acceleration.<br>**NOTE**<br>**speed** indicates the acceleration speed, and **angle** indicates the acceleration direction (in angles).<br>Default value: **{ speed:{range:[0.0,0.0]},angle:{range:[0.0,0.0]} }**| 132| spin | [ParticlePropertyOptions](#particlepropertyoptions)<number, [SPIN_UPDATER](#particleupdater)> | No| Particle spin angle.<br>Default value: **{range:[0.0,0.0]}**<br>Direction: A positive number indicates clockwise spinning, and a negative number indicates anticlockwise spinning.| 133 134 135## EmitterOptions 136Provides particle emitter configuration. 137 138```typescript 139interface EmitterOptions<PARTICLE extends ParticleType> { 140 particle: { 141 type: PARTICLE; 142 config: ParticleConfigs[PARTICLE]; 143 count: number; 144 lifetime?: number; 145 lifetimeRange?: number; 146 }; 147 emitRate?: number; 148 shape?: ParticleEmitterShape; 149 position?: [Dimension, Dimension]; 150 size?: [Dimension, Dimension]; 151} 152``` 153 154**Atomic service API**: This API can be used in atomic services since API version 11. 155 156**System capability**: SystemCapability.ArkUI.ArkUI.Full 157 158| Name| Type| Mandatory| Description| 159| -------- | -------- | -------- | -------- | 160| particle | {<br>type: [PARTICLE](#particletype),<br>config: [ParticleConfigs](#particleconfigs),<br>count: number,<br>lifetime?: number<br>lifeTimeRange?:number<sup>12+<sup><br>} | Yes| Particle configuration.<br>- **type**: particle type, which can be **IMAGE** or **POINT**.<br><br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>- **config**: configuration of the particle type.<br>- The value type of **config** is subject to the value of **type**.<br>1. If **type** is **ParticleType.POINT**, the **config** type is [PointParticleParameters](#pointparticleparameters).<br>2. If **type** is **ParticleType.IMAGE**, the **config** type is [ImageParticleParameters](#imageparticleparameters).<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>- **count**: number of particles. The value is greater than or equal to -1. The value **-1** indicates that the number of particles is infinite.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>- **lifetime**: lifetime of a single particle. The default value is **1000** (that is, 1000 ms, 1s). The value is greater than or equal to -1. The value **-1** indicates that the lifetime of the particle is infinite. If the value specified is less than **-1**, the default value is used.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>- **lifeTimeRange**: range of particle lifetime values. After **lifeTimeRange** is set, the lifetime of a particle is a random integer between [lifetime – lifeTimeRange, lifetime + lifeTimeRange]. **lifeTimeRange** has a default value of 0, and its value range is from 0 to positive infinity. If it is set to a negative value, the default value is used.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 161| emitRate | number | No| Emit rate (that is, the number of particles emitted per second).<br> Default value: **5**. If the value specified is less than 0, the default value is used.<br> The **emitRate** value can significantly impact performance when it exceeds 5000; you are advised to set it to be less than 5000.| 162| shape | [ParticleEmitterShape](#particleemittershape) | No| Emitter shape.<br> Default value: **ParticleEmitterShape.RECTANGLE**| 163| position | \[[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)\] | No| Emitter position (distance from the upper left corner of the component). The first parameter indicates the relative offset along the x-axis, and the second parameter indicates the relative offset along the y-axis.<br>Default value: **[0.0, 0.0]**| 164| size | \[[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)\] |No| Size of the emit window. The first parameter indicates the emitter width, and the second parameter indicates the emitter height.<br>Default value: **['100%', '100%']** (that is, the emit window fully occupies the component).| 165 166## ParticleConfigs 167 168```typescript 169interface ParticleConfigs { 170 [ParticleType.POINT]: PointParticleParameters; 171 [ParticleType.IMAGE]: ImageParticleParameters; 172} 173``` 174 175**Atomic service API**: This API can be used in atomic services since API version 11. 176 177**System capability**: SystemCapability.ArkUI.ArkUI.Full 178 179| Name | Type | Mandatory| Description| 180| -------- | -------------- | -------- | -------- | 181| [ParticleType.POINT] | [PointParticleParameters](#pointparticleparameters) | Yes | Point particle configuration.| 182| [ParticleType.IMAGE] | [ImageParticleParameters](#imageparticleparameters) | Yes | Image particle configuration.| 183 184## PointParticleParameters 185```typescript 186interface PointParticleParameters { 187 radius: VP; 188} 189``` 190 191**Atomic service API**: This API can be used in atomic services since API version 11. 192 193**System capability**: SystemCapability.ArkUI.ArkUI.Full 194 195| Name | Type | Mandatory| Description| 196| -------- | -------------- | -------- | -------- | 197| radius | [VP](ts-types.md#vp10)| Yes | Particle radius.| 198 199## ImageParticleParameters 200```typescript 201interface ImageParticleParameters { 202 src: ResourceStr; 203 size: [Dimension, Dimension]; 204 objectFit?: ImageFit; 205} 206``` 207 208**Atomic service API**: This API can be used in atomic services since API version 11. 209 210**System capability**: SystemCapability.ArkUI.ArkUI.Full 211 212| Name | Type | Mandatory| Description| 213| -------- | -------------- | -------- | -------- | 214| src | [ResourceStr](ts-types.md#resourcestr) | Yes | Image path. SVG images are not supported.| 215| size | \[[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)\]| Yes | Image size.| 216| objectFit| [ImageFit](ts-appendix-enums.md#imagefit)| No | Image display mode.| 217 218## ParticleColorPropertyOptions 219 220```typescript 221interface ParticleColorPropertyOptions<UPDATER extends ParticleUpdater> { 222 range: [ResourceColor, ResourceColor]; 223 distributionType?: DistributionType; 224 updater?: { 225 type: UPDATER; 226 config: ParticleColorPropertyUpdaterConfigs[UPDATER]; 227 }; 228} 229``` 230**Atomic service API**: This API can be used in atomic services since API version 11. 231 232**System capability**: SystemCapability.ArkUI.ArkUI.Full 233 234| Name| Type| Mandatory| Description| 235| -------- | -------- | -------- | -------- | 236| range | \[[ResourceColor](ts-types.md#resourcecolor), [ResourceColor](ts-types.md#resourcecolor)\] | Yes| Initial color range of the particle. The initial color of particles generated by the particle emitter is randomly selected in this range.<br>Default value: **range:[Color.White,Color.White]**<br>**Atomic service API**: This API can be used in atomic services since API version 11. 237| distributionType<sup>12+<sup> | [DistributionType](#distributiontype12) | No| Type of random value distribution for the initial color of the particle. Both uniform distribution and normal (Gaussian) distribution are supported.<br>Default value: **DistributionType.UNIFORM**<br>**Atomic service API**: This API can be used in atomic services since API version 12. 238| updater | {<br>type: [UPDATER](#particleupdater);<br>config: [ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[UPDATER];<br>} | No| How the color property is updated. The available options of **type** are as follows:<br>1. **ParticleUpdater.NONE**: The property does not change. In this case, the **config** type is [ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.NONE].<br>2. **ParticleUpdater.RANDOM**: The property changes randomly. In this case, the **config** type is [ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.RANDOM].<br>3. **ParticleUpdater.CURVE**: The property changes with the animation curve. In this case, the **config** type is [ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.CURVE].<br>The default value of **type** is **ParticleUpdater.NONE**.<br>**NOTE**<br>When **type** is set to **ParticleUpdater.RANDOM** or **ParticleUpdater.CURVE**, the color configuration in **updater** has higher priority than that in **range**. During the animation time period configured in **updater**, the color configuration from **updater** is used. Outside of the animation time period configured in **updater**, the color configuration from **range** is used.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 239 240 241## ParticleColorPropertyUpdaterConfigs 242```typescript 243interface ParticleColorPropertyUpdaterConfigs { 244 [ParticleUpdater.NONE]: void; 245 [ParticleUpdater.RANDOM]: { 246 r: [number, number]; 247 g: [number, number]; 248 b: [number, number]; 249 a: [number, number]; 250 }; 251 [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<ResourceColor>>; 252} 253``` 254 255**Atomic service API**: This API can be used in atomic services since API version 11. 256 257**System capability**: SystemCapability.ArkUI.ArkUI.Full 258 259| Name| Type| Mandatory| Description| 260| -------- | -------- | -------- | -------- | 261|[ParticleUpdater.NONE]|void | Yes| The color does not change.| 262| [ParticleUpdater.RANDOM] | {<br> r: [number, number];<br> g: [number, number];<br> b: [number, number];<br> a: [number, number];<br>} | Yes| The color changes randomly, with the per-second change difference being a value randomly generated from the range. The target color is obtained by applying the change difference to the current color value of each of the R, G, B, A channels. | 263[ParticleUpdater.CURVE]|Array<[ParticlePropertyAnimation](#particlepropertyanimation)\<[ResourceColor](ts-types.md#resourcecolor)\>> | Yes| The color changes with the animation curve. The array type indicates that multiple animation segments can be set for the current property, for example, 0-3000 ms, 3000-5000 ms, and 5000-8000 ms.| 264 265## ParticlePropertyOptions 266```typescript 267interface ParticlePropertyOptions<TYPE, UPDATER extends ParticleUpdater> { 268 range: [TYPE, TYPE]; 269 updater?: { 270 type: UPDATER; 271 config: ParticlePropertyUpdaterConfigs<TYPE>[UPDATER]; 272 }; 273} 274``` 275 276**Atomic service API**: This API can be used in atomic services since API version 11. 277 278**System capability**: SystemCapability.ArkUI.ArkUI.Full 279 280| Name| Type| Mandatory| Description| 281| -------- | -------- | -------- | -------- | 282| range | [TYPE, TYPE] | Yes| Initial property value range of the particle. The initial property value of particles generated by the particle emitter is randomly selected in this range.<br>**NOTE**<br>If a property is set to an invalid value, the default value will be used. If the maximum value is less than the minimum value, the default range will be used. **TYPE** is number.<br>The default value varies by property:<br>1. **opacity** property: **range:[1.0,1.0]**; the value ranges from 0 to 1; the default value is **0.0**.<br>2. **scale** property: **range:[1.0,1.0]**; the value is greater than or equal to 0; the default value is **1.0**.<br>3. **speed** property in **acceleration**: **range:[0.0,0.0]**; the value is greater than or equal to 0; the default value is **0.0**.<br>4. **angle** property in **acceleration**: **range:[0.0,0.0]**; the value range is (-∞, +∞); the default value is **0.0**.<br>5. **spin** property: **range:[0.0,0.0]**; the default value is **0.0**. 283| updater | {type: [UPDATER](#particleupdater);config: [ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[UPDATER];} | No| How the property is updated. The available options of **type** are as follows:<br>1. **ParticleUpdater.NONE**: The property does not change. In this case, the **config** type is [ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.NONE].<br>2. **ParticleUpdater.RANDOM**: The property changes randomly. In this case, the **config** type is [ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.RANDOM].<br>3. **ParticleUpdater.CURVE**: The property changes with the animation curve. In this case, the **config** type is [ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.CURVE].<br>The default value of **type** is **ParticleUpdater.NONE**.| 284 285 286## ParticlePropertyUpdaterConfigs 287```typescript 288interface ParticlePropertyUpdaterConfigs<T> { 289 [ParticleUpdater.NONE]: void; 290 [ParticleUpdater.RANDOM]: [T, T]; 291 [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<T>>; 292} 293``` 294 295**Atomic service API**: This API can be used in atomic services since API version 11. 296 297**System capability**: SystemCapability.ArkUI.ArkUI.Full 298 299| Name| Type| Mandatory| Description| 300| -------- | -------- | -------- | -------- | 301| [ParticleUpdater.NONE]|void | Yes| The color does not change.| 302| [ParticleUpdater.RANDOM] | [T, T] | Yes| The property changes randomly, with the per-second change difference being a value randomly generated from the range.<br>The target property value is obtained by applying the change difference to the current property value. For example, if the current property value is **0.2** and **config** is set to **[0.1,1.0]**, then:<br>1. When the random change difference is 0.5, the target property value is 0.2 + 0.5 = 0.7.<br>2. The change difference may also be a negative value. For example, if the current property value is **0.2** and **config** is set to **[-3.0,2.0]**, then when the random change difference is **-2.0**, the target property value is 0.2 - 2.0 = -1.8.<br>**NOTE**<br>**config** sets the value range of the change difference. While the change difference does not have a maximum or minimum value limit, the target property value does. Therefore, if the target property value is greater than the maximum property value, the maximum property value will be used instead; if the target property value is less than the minimum property value, the minimum property value will be used instead. **T** represents a number.<br>For example, if the value range of **opacity** is **[0.0, 1.0]**, then if the target property value is greater than 1.0, **1.0** will be used instead.| 303|[ParticleUpdater.CURVE]|Array<[ParticlePropertyAnimation](#particlepropertyanimation)\<T\>> | Yes| The property changes with the animation curve. The array type indicates that multiple animation segments can be set for the current property, for example, 0-3000 ms, 3000-5000 ms, and 5000-8000 ms. **T** represents a number.| 304 305 306 307## ParticlePropertyAnimation 308```typescript 309interface ParticlePropertyAnimation<T> { 310 from: T; 311 to: T; 312 startMillis: number; 313 endMillis: number; 314 curve?: Curve | ICurve; 315} 316``` 317 318**Atomic service API**: This API can be used in atomic services since API version 11. 319 320**System capability**: SystemCapability.ArkUI.ArkUI.Full 321 322| Name| Type| Mandatory| Description| 323| -------- | -------- | -------- | -------- | 324|from| T | Yes| Initial value of the property. If the value is invalid, the default value will be used.| 325| to | T | Yes| Target value of the property. If the value is invalid, the default value will be used.| 326|startMillis|number | Yes| Start time of the animation.| 327|endMillis|number | Yes| End time of the animation.| 328|curve|[Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve)| No| Animation curve.<br>Default value: **Curve.Linear**| 329 330 331## ParticleType 332```typescript 333enum ParticleType { 334 POINT = 'point', 335 IMAGE = 'image', 336} 337``` 338**Atomic service API**: This API can be used in atomic services since API version 11. 339 340**System capability**: SystemCapability.ArkUI.ArkUI.Full 341 342| Name | Description| 343| -------- | -------- | 344POINT |Point particle.| 345IMAGE | Image particle.| 346 347 348 349## ParticleEmitterShape 350```typescript 351enum ParticleEmitterShape { 352 RECTANGLE = 'rectangle', 353 CIRCLE = 'circle', 354 ELLIPSE = 'ellipse', 355} 356``` 357 358**Atomic service API**: This API can be used in atomic services since API version 11. 359 360**System capability**: SystemCapability.ArkUI.ArkUI.Full 361 362| Name | Description| 363| -------- | -------- | 364RECTANGLE |The particle emitter is rectangular.| 365CIRCLE | The particle emitter is circular.| 366ELLIPSE |The particle emitter is elliptical.| 367 368## DistributionType<sup>12+<sup> 369```typescript 370enum DistributionType { 371 UNIFORM = 0, 372 GAUSSIAN = 1, 373} 374``` 375**Atomic service API**: This API can be used in atomic services since API version 12. 376 377**System capability**: SystemCapability.ArkUI.ArkUI.Full 378 379| Name | Description| 380| -------- | -------- | 381| UNIFORM |The initial color random values are distributed uniformly.| 382| GAUSSIAN | The initial color random values are distributed according to a Gaussian distribution.| 383 384## ParticleUpdater 385```typescript 386enum ParticleUpdater { 387 NONE = 'none', 388 RANDOM = 'random', 389 CURVE = 'curve', 390} 391``` 392 393**Atomic service API**: This API can be used in atomic services since API version 11. 394 395**System capability**: SystemCapability.ArkUI.ArkUI.Full 396 397| Name | Description| 398| -------- | -------- | 399|NONE |No change.| 400|RANDOM | Random change.| 401|CURVE |Change with the animation curve.| 402 403## DisturbanceFieldOptions<sup>12+</sup> 404 405**Atomic service API**: This API can be used in atomic services since API version 12. 406 407**System capability**: SystemCapability.ArkUI.ArkUI.Full 408 409| Name| Type | Mandatory| Description | 410| ------ | ------- | ---- | ---------------------------- | 411| strength | number | No |Field strength, which indicates the intensity of the repulsive force from the center outward. The default value is **0**. Positive values indicate a repulsive force directed outward, while negative values indicate an attractive force directed inward.| 412| shape | [DisturbanceFieldShape](#disturbancefieldshape12) | No | Shape of the field.<br>Default value: **DisturbanceFieldShape.RECT**| 413| size | [SizeT](../js-apis-arkui-graphics.md#sizett12)<number>| No |Size of the field.<br>Default value: {width:0, height:0}| 414| position | [PositionT](../js-apis-arkui-graphics.md#positiont12)<number> | No |Position of the field.<br>Default value: {x:0, y:0}| 415| feather | number | No |Feather value, which represents the degree of attenuation from the center of the field to its edges. The value is an integer ranging from 0 to 100. A value of 0 indicates that the field is rigid, and all particles within its range are repelled. The higher the feather value, the more gradual the field becomes, resulting in more particles close to the center point appearing within the field's range.<br>Default value: **0**| 416| noiseScale | number | No |Noise scale, used to control the overall size of the noise pattern. The value is greater than or equal to 0.<br>Default value: **1**| 417| noiseFrequency | number | No |Noise frequency. The higher the frequency, the finer the noise. The value is greater than or equal to 0.<br> Default value: **1**| 418| noiseAmplitude | number | No |Noise amplitude, which indicates the range of noise fluctuations. The greater the amplitude, the greater the difference between the noises. The value is greater than or equal to 0.<br> Default value: **1**| 419 420## DisturbanceFieldShape<sup>12+</sup> 421 422**Atomic service API**: This API can be used in atomic services since API version 12. 423 424**System capability**: SystemCapability.ArkUI.ArkUI.Full 425 426| Name | Description | 427| --------| ----------| 428| RECT | Rectangle. | 429| CIRCLE | Circle. | 430| ELLIPSE | Ellipse. | 431 432## EmitterProperty<sup>12+</sup> 433 434**Atomic service API**: This API can be used in atomic services since API version 12. 435 436**System capability**: SystemCapability.ArkUI.ArkUI.Full 437 438| Name| Type | Mandatory| Description | 439| ------ | ------- | ---- | ---------------------------- | 440| index | number | Yes |Index of the emitter based on the index array of the emitters in the initialization parameters. The value is rounded to the nearest whole number. The default value **0** is used in case of exceptions.| 441| emitRate | number | No | Emit rate, that is, the number of particles emitted per second.<br>If no value is passed in, the current emit rate is retained. If a value less than 0 is passed in, the default value **5** is used. The **emitRate** value can significantly impact performance when it exceeds 5000; you are advised to set it to be less than 5000.| 442| position | [PositionT](../js-apis-arkui-graphics.md#positiont12)<number> | No |Array of emitter positions. Only the number type is supported.<br>If no value is passed in, the current emitter position is retained. Two valid values must be passed in; if either is an invalid value, **position** will not take effect.| 443| size | [SizeT](../js-apis-arkui-graphics.md#sizett12)<number>| No |Size of the emit window. Only the number type is supported.<br>If no value is passed in, the current emitter window size is retained. Two valid values greater than 0 must be passed in; if either is an invalid value, **size** will not take effect.| 444 445## Example 446 447### Example 1 448 449This example demonstrates the basic usage of particle animation, initializing point particles. 450 451```ts 452// xxx.ets 453@Entry 454@Component 455struct ParticleExample { 456 build() { 457 Stack() { 458 Text() 459 .width(300).height(300).backgroundColor(Color.Black) 460 Particle({particles:[ 461 { 462 emitter:{ 463 particle:{ 464 type:ParticleType.POINT,// Particle type. 465 config:{ 466 radius:10// Point radius. 467 }, 468 count: 500,// Total number of particles. 469 lifetime:10000,// Particle lifetime, in ms. 470 lifetimeRange:100// Range of particle lifetime values, in ms. 471 }, 472 emitRate:10,// Number of particles emitted per second. 473 position:[0,0], 474 shape:ParticleEmitterShape.RECTANGLE// Emitter shape. 475 }, 476 color:{ 477 range:[Color.Red,Color.Yellow],// Initial color range. 478 updater:{ 479 type:ParticleUpdater.CURVE,// Change with the animation curve. 480 config:[ 481 { 482 from:Color.White,// Initial value of the change. 483 to:Color.Pink,// Target value of the change. 484 startMillis:0,// Start time. 485 endMillis:3000,// End time. 486 curve:Curve.EaseIn// Animation curve. 487 }, 488 { 489 from:Color.Pink, 490 to:Color.Orange, 491 startMillis:3000, 492 endMillis:5000, 493 curve:Curve.EaseIn 494 }, 495 { 496 from:Color.Orange, 497 to:Color.Pink, 498 startMillis:5000, 499 endMillis:8000, 500 curve:Curve.EaseIn 501 }, 502 ] 503 } 504 }, 505 opacity:{ 506 range:[0.0,1.0],// The initial value of particle opacity is randomly generated from the [0.0, 1.0] range. 507 updater:{ 508 type:ParticleUpdater.CURVE, 509 config:[ 510 { 511 from:0.0, 512 to:1.0, 513 startMillis:0, 514 endMillis:3000, 515 curve:Curve.EaseIn 516 }, 517 { 518 from:1.0, 519 to:0.0, 520 startMillis:5000, 521 endMillis:10000, 522 curve:Curve.EaseIn 523 } 524 ] 525 } 526 }, 527 scale:{ 528 range:[0.0,0.0], 529 updater:{ 530 type:ParticleUpdater.CURVE, 531 config:[ 532 { 533 from:0.0, 534 to:0.5, 535 startMillis:0, 536 endMillis:3000, 537 curve: Curve.EaseIn 538 } 539 ] 540 } 541 }, 542 acceleration:{// Acceleration. speed indicates the acceleration speed, and angle indicates the acceleration direction. 543 speed:{ 544 range:[3,9], 545 updater:{ 546 type:ParticleUpdater.RANDOM,// The speed changes randomly. 547 config:[1,20] 548 } 549 }, 550 angle:{ 551 range:[90,90] 552 } 553 } 554 555 } 556 ] 557 }).width(300).height(300) 558 }.width("100%").height("100%").align(Alignment.Center) 559 } 560} 561``` 562 563 564 565### Example 2 566 567This example demonstrates the basic usage of particle animation, initializing image particles. 568 569```ts 570@Entry 571@Component 572struct ParticleExample { 573 @State 574 myCount : number = 100 575 flag : boolean = false; 576 build() { 577 Column(){ 578 Stack() { 579 Particle({particles:[ 580 { 581 emitter:{ 582 particle:{ 583 type:ParticleType.IMAGE, 584 config:{ 585 src:$r("app.media.book"), 586 size:[10,10] 587 }, 588 count: this.myCount, 589 lifetime:10000, 590 lifetimeRange:100 591 }, 592 emitRate:3, 593 shape:ParticleEmitterShape.CIRCLE 594 }, 595 color:{ 596 range:[Color.White,Color.White] 597 }, 598 opacity:{ 599 range:[1.0,1.0], 600 updater:{ 601 type:ParticleUpdater.CURVE, 602 config:[ 603 { 604 from:0, 605 to:1.0, 606 startMillis:0, 607 endMillis:6000 608 }, 609 { 610 from:1.0, 611 to:.0, 612 startMillis:6000, 613 endMillis:10000 614 } 615 ] 616 } 617 }, 618 scale:{ 619 range:[0.1,1.0], 620 updater:{ 621 type:ParticleUpdater.CURVE, 622 config:[ 623 { 624 from: 0, 625 to: 1.5, 626 startMillis: 0, 627 endMillis: 8000, 628 curve: Curve.EaseIn 629 } 630 631 ] 632 } 633 }, 634 acceleration:{ 635 speed:{ 636 range:[3,9], 637 updater:{ 638 type: ParticleUpdater.CURVE, 639 config:[ 640 { 641 from:10, 642 to:20, 643 startMillis:0, 644 endMillis:3000, 645 curve:Curve.EaseIn 646 }, 647 { 648 from:10, 649 to:2, 650 startMillis:3000, 651 endMillis:8000, 652 curve:Curve.EaseIn 653 } 654 ] 655 } 656 }, 657 angle:{ 658 range:[0,180], 659 updater:{ 660 type:ParticleUpdater.CURVE, 661 config:[{ 662 from:1, 663 to:2, 664 startMillis:0, 665 endMillis:1000, 666 curve:Curve.EaseIn 667 }, 668 { 669 from:50, 670 to:-50, 671 startMillis:1000, 672 endMillis:3000, 673 curve:Curve.EaseIn 674 }, 675 { 676 from:3, 677 to:5, 678 startMillis:3000, 679 endMillis:8000, 680 curve:Curve.EaseIn 681 } 682 ] 683 } 684 } 685 }, 686 spin:{ 687 range:[0.1,1.0], 688 updater:{ 689 type:ParticleUpdater.CURVE, 690 config:[ 691 { 692 from: 0, 693 to: 360, 694 startMillis: 0, 695 endMillis: 8000, 696 curve: Curve.EaseIn 697 } 698 ] 699 } 700 }, 701 } 702 ,{ 703 emitter:{ 704 particle:{ 705 type:ParticleType.IMAGE, 706 config:{ 707 src:$r('app.media.heart'), 708 size:[10,10] 709 }, 710 count: this.myCount, 711 lifetime:10000, 712 lifetimeRange:100 713 }, 714 emitRate:3, 715 shape:ParticleEmitterShape.CIRCLE 716 }, 717 color:{ 718 range:[Color.White,Color.White] 719 }, 720 opacity:{ 721 range:[1.0,1.0], 722 updater:{ 723 type:ParticleUpdater.CURVE, 724 config:[ 725 { 726 from:0, 727 to:1.0, 728 startMillis:0, 729 endMillis:6000 730 }, 731 { 732 from:1.0, 733 to:.0, 734 startMillis:6000, 735 endMillis:10000 736 } 737 ] 738 } 739 }, 740 scale:{ 741 range:[0.1,1.0], 742 updater:{ 743 type:ParticleUpdater.CURVE, 744 config:[ 745 { 746 from: 0, 747 to: 2.0, 748 startMillis: 0, 749 endMillis: 10000, 750 curve: Curve.EaseIn 751 } 752 753 ] 754 } 755 }, 756 acceleration:{ 757 speed:{ 758 range:[3,9], 759 updater:{ 760 type: ParticleUpdater.CURVE, 761 config:[ 762 { 763 from:10, 764 to:20, 765 startMillis:0, 766 endMillis:3000, 767 curve:Curve.EaseIn 768 }, 769 { 770 from:10, 771 to:2, 772 startMillis:3000, 773 endMillis:8000, 774 curve:Curve.EaseIn 775 } 776 ] 777 } 778 }, 779 angle:{ 780 range:[0,180], 781 updater:{ 782 type:ParticleUpdater.CURVE, 783 config:[{ 784 from:1, 785 to:2, 786 startMillis:0, 787 endMillis:1000, 788 curve:Curve.EaseIn 789 }, 790 { 791 from:50, 792 to:-50, 793 startMillis:0, 794 endMillis:3000, 795 curve:Curve.EaseIn 796 }, 797 { 798 from:3, 799 to:5, 800 startMillis:3000, 801 endMillis:10000, 802 curve:Curve.EaseIn 803 } 804 ] 805 } 806 } 807 }, 808 spin:{ 809 range:[0.1,1.0], 810 updater:{ 811 type:ParticleUpdater.CURVE, 812 config:[ 813 { 814 from: 0, 815 to: 360, 816 startMillis: 0, 817 endMillis: 10000, 818 curve: Curve.EaseIn 819 } 820 ] 821 } 822 }, 823 },{ 824 emitter:{ 825 particle:{ 826 type:ParticleType.IMAGE, 827 config:{ 828 src:$r('app.media.sun'), 829 size:[10,10] 830 }, 831 count: this.myCount, 832 lifetime:10000, 833 lifetimeRange:100 834 }, 835 emitRate:3, 836 shape:ParticleEmitterShape.CIRCLE 837 }, 838 color:{ 839 range:[Color.White,Color.White] 840 }, 841 opacity:{ 842 range:[1.0,1.0], 843 updater:{ 844 type:ParticleUpdater.CURVE, 845 config:[ 846 { 847 from:0, 848 to:1.0, 849 startMillis:0, 850 endMillis:6000 851 }, 852 { 853 from:1.0, 854 to:.0, 855 startMillis:6000, 856 endMillis:10000 857 } 858 ] 859 } 860 }, 861 scale:{ 862 range:[0.1,1.0], 863 updater:{ 864 type:ParticleUpdater.CURVE, 865 config:[ 866 { 867 from: 0, 868 to: 2.0, 869 startMillis: 0, 870 endMillis: 10000, 871 curve: Curve.EaseIn 872 } 873 874 ] 875 } 876 }, 877 acceleration:{ 878 speed:{ 879 range:[3,9], 880 updater:{ 881 type: ParticleUpdater.CURVE, 882 config:[ 883 { 884 from:10, 885 to:20, 886 startMillis:0, 887 endMillis:3000, 888 curve:Curve.EaseIn 889 }, 890 { 891 from:10, 892 to:2, 893 startMillis:3000, 894 endMillis:8000, 895 curve:Curve.EaseIn 896 } 897 ] 898 } 899 }, 900 angle:{ 901 range:[0,180], 902 updater:{ 903 type:ParticleUpdater.CURVE, 904 config:[{ 905 from:1, 906 to:2, 907 startMillis:0, 908 endMillis:1000, 909 curve:Curve.EaseIn 910 }, 911 { 912 from:50, 913 to:-50, 914 startMillis:1000, 915 endMillis:3000, 916 curve:Curve.EaseIn 917 }, 918 { 919 from:3, 920 to:5, 921 startMillis:3000, 922 endMillis:8000, 923 curve:Curve.EaseIn 924 } 925 ] 926 } 927 } 928 }, 929 spin:{ 930 range:[0.1,1.0], 931 updater:{ 932 type:ParticleUpdater.CURVE, 933 config:[ 934 { 935 from: 0, 936 to: 360, 937 startMillis: 0, 938 endMillis: 10000, 939 curve: Curve.EaseIn 940 } 941 ] 942 } 943 }, 944 } 945 ] 946 }).width(300).height(300) 947 948 }.width(500).height(500).align(Alignment.Center) 949 }.width("100%").height("100%") 950 951 } 952} 953``` 954 955 956### Example 3 957 958This example demonstrates how particles' trajectories change under the influence of a particle disturbance field. 959``` 960@Entry 961@Component 962struct ParticleExample { 963 build() { 964 Stack() { 965 Text() 966 .width(300).height(300).backgroundColor(Color.Black) 967 Particle({particles:[ 968 { 969 emitter:{ 970 particle:{ 971 type:ParticleType.POINT,// Particle type. 972 config:{ 973 radius:10// Point radius. 974 }, 975 count: 500,// Total number of particles. 976 lifetime:10000// Particle lifetime, in ms. 977 }, 978 emitRate:10,// Number of particles emitted per second. 979 position:[0,0], 980 shape:ParticleEmitterShape.RECTANGLE// Emitter shape. 981 }, 982 color:{ 983 range:[Color.Red,Color.Yellow],// Initial color range. 984 updater:{ 985 type:ParticleUpdater.CURVE,// Change with the animation curve. 986 config:[ 987 { 988 from:Color.White,// Initial value of the change. 989 to:Color.Pink,// Target value of the change. 990 startMillis:0,// Start time. 991 endMillis:3000,// End time. 992 curve:Curve.EaseIn// Animation curve. 993 }, 994 { 995 from:Color.Pink, 996 to:Color.Orange, 997 startMillis:3000, 998 endMillis:5000, 999 curve:Curve.EaseIn 1000 }, 1001 { 1002 from:Color.Orange, 1003 to:Color.Pink, 1004 startMillis:5000, 1005 endMillis:8000, 1006 curve:Curve.EaseIn 1007 }, 1008 ] 1009 } 1010 }, 1011 opacity:{ 1012 range:[0.0,1.0],// The initial value of particle opacity is randomly generated from the [0.0, 1.0] range. 1013 updater:{ 1014 type:ParticleUpdater.CURVE, 1015 config:[ 1016 { 1017 from:0.0, 1018 to:1.0, 1019 startMillis:0, 1020 endMillis:3000, 1021 curve:Curve.EaseIn 1022 }, 1023 { 1024 from:1.0, 1025 to:0.0, 1026 startMillis:5000, 1027 endMillis:10000, 1028 curve:Curve.EaseIn 1029 } 1030 ] 1031 } 1032 }, 1033 scale:{ 1034 range:[0.0,0.0], 1035 updater:{ 1036 type:ParticleUpdater.CURVE, 1037 config:[ 1038 { 1039 from:0.0, 1040 to:0.5, 1041 startMillis:0, 1042 endMillis:3000, 1043 curve: Curve.EaseIn 1044 } 1045 ] 1046 } 1047 }, 1048 acceleration:{// Acceleration. speed indicates the acceleration speed, and angle indicates the acceleration direction. 1049 speed:{ 1050 range:[3,9], 1051 updater:{ 1052 type:ParticleUpdater.RANDOM, 1053 config:[1,20] 1054 } 1055 }, 1056 angle:{ 1057 range:[90,90] 1058 } 1059 } 1060 1061 } 1062 ] 1063 }).width(300).height(300).disturbanceFields([{ 1064 strength:10, 1065 shape:DisturbanceFieldShape.RECT, 1066 size:{width:100,height:100}, 1067 position:{x:100,y:100}, 1068 feather:15, 1069 noiseScale:10, 1070 noiseFrequency:15, 1071 noiseAmplitude:5 1072 }]) 1073 }.width("100%").height("100%").align(Alignment.Center) 1074 } 1075} 1076 1077``` 1078 1079 1080### Example 4 1081This example demonstrates how to adjust the position of the particle emitter through **emitter()**. 1082```ts 1083@Entry 1084@Component 1085struct ParticleExample { 1086 @State emitterProperties: Array<EmitterProperty> = [ 1087 { 1088 index: 0, 1089 emitRate: 100, 1090 position: { x: 60, y: 80 }, 1091 size: { width: 200, height: 200 } 1092 } 1093 ] 1094 1095 build() { 1096 Stack() { 1097 Text() 1098 .width(300).height(300).backgroundColor(Color.Black) 1099 Particle({ particles: [ 1100 { 1101 emitter: { 1102 particle: { 1103 type: ParticleType.POINT, // Particle type. 1104 config: { 1105 radius: 5// Point radius. 1106 }, 1107 count: 400, // Total number of particles. 1108 lifetime: -1// Particle lifetime. The value -1 indicates that the lifetime of the particle is infinite. 1109 }, 1110 emitRate: 10, // Number of particles emitted per second. 1111 position: [0, 0], // Emitter position. 1112 shape: ParticleEmitterShape.CIRCLE// Emitter shape. 1113 }, 1114 color: { 1115 range: [Color.Red, Color.Yellow], // Initial color range. 1116 updater: { 1117 type: ParticleUpdater.CURVE, // Change with the animation curve. 1118 config: [ 1119 { 1120 from: Color.White, 1121 to: Color.Pink, 1122 startMillis: 0, 1123 endMillis: 3000, 1124 curve: Curve.EaseIn 1125 }, 1126 { 1127 from: Color.Pink, 1128 to: Color.Orange, 1129 startMillis: 3000, 1130 endMillis: 5000, 1131 curve: Curve.EaseIn 1132 }, 1133 { 1134 from: Color.Orange, 1135 to: Color.Pink, 1136 startMillis: 5000, 1137 endMillis: 8000, 1138 curve: Curve.EaseIn 1139 }, 1140 ] 1141 } 1142 }, 1143 }, 1144 ] 1145 }) 1146 .width(300) 1147 .height(300) 1148 .emitter(this.emitterProperties) 1149 }.width("100%").height("100%").align(Alignment.Center) 1150 } 1151} 1152``` 1153 1154
