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 >(particles: Particles< 31 PARTICLE, 32 COLOR_UPDATER, 33 OPACITY_UPDATER, 34 SCALE_UPDATER, 35 ACC_SPEED_UPDATER, 36 ACC_ANGLE_UPDATER, 37 SPIN_UPDATER 38 >): ParticleAttribute; 39} 40``` 41 42**Atomic service API**: This API can be used in atomic services since API version 11. 43 44**Parameters** 45 46| Name| Type| Mandatory| Description| 47| -------- | -------- | -------- | -------- | 48| particles | [Particles](#particles14)<<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| Particles. For details, see [Particles](#particles14).| 49 50## Attributes 51 52In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 53 54### disturbanceFields<sup>12+</sup> 55 56disturbanceFields(fields: Array<DisturbanceFieldOptions>) 57 58Sets the disturbance fields. 59 60**Atomic service API**: This API can be used in atomic services since API version 12. 61 62**System capability**: SystemCapability.ArkUI.ArkUI.Full 63 64**Parameters** 65 66| Name| Type | Mandatory| Description | 67| ------ | ------- | ---- | ---------------------------- | 68| fields | Array<[DisturbanceFieldOptions](#disturbancefieldoptions12)> | Yes | Array of disturbance fields.| 69 70### emitter<sup>12+</sup> 71emitter(value: Array<EmitterProperty>) 72 73Sets the emitter parameters. 74 75**Atomic service API**: This API can be used in atomic services since API version 12. 76 77**System capability**: SystemCapability.ArkUI.ArkUI.Full 78 79**Parameters** 80 81| Name| Type | Mandatory| Description | 82| ------ | ------- | ---- | ---------------------------- | 83| value | Array<[EmitterProperty](#emitterproperty12)> | Yes | Array of emitter parameters to set.| 84 85## Events 86The [universal events](ts-component-general-events.md) are supported. 87 88## ParticleOptions 89 90```typescript 91interface ParticleOptions< 92 PARTICLE extends ParticleType, 93 COLOR_UPDATER extends ParticleUpdater, 94 OPACITY_UPDATER extends ParticleUpdater, 95 SCALE_UPDATER extends ParticleUpdater, 96 ACC_SPEED_UPDATER extends ParticleUpdater, 97 ACC_ANGLE_UPDATER extends ParticleUpdater, 98 SPIN_UPDATER extends ParticleUpdater 99> { 100 emitter: EmitterOptions<PARTICLE>; 101 color?: ParticleColorPropertyOptions<COLOR_UPDATER>; 102 opacity?: ParticlePropertyOptions<number, OPACITY_UPDATER>; 103 scale?: ParticlePropertyOptions<number, SCALE_UPDATER>; 104 velocity?: VelocityOptions; 105 acceleration?: AccelerationOptions<ACC_SPEED_UPDATER, ACC_ANGLE_UPDATER>; 106 spin?: ParticlePropertyOptions<number, SPIN_UPDATER>; 107} 108``` 109 110**Atomic service API**: This API can be used in atomic services since API version 11. 111 112**System capability**: SystemCapability.ArkUI.ArkUI.Full 113 114| Name| Type| Mandatory| Description| 115| -------- | -------- | -------- | -------- | 116| emitter | [EmitterOptions](#emitteroptions)<[PARTICLE](#particletype)> | Yes| Particle emitter.| 117| 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.| 118| opacity | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [OPACITY_UPDATER](#particleupdater)> | No| Particle opacity.<br>Default value: **{ range:[1.0,1.0] }**| 119| scale | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [SCALE_UPDATER](#particleupdater)> | No| Particle scale.<br>Default value: **{ range:[1.0,1.0] }**| 120| velocity | [VelocityOptions](#velocityoptions14) |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] }**| 121| acceleration | [AccelerationOptions](#accelerationoptions14)<[ACC_SPEED_UPDATER](#particleupdater), [ACC_ANGLE_UPDATER](#particleupdater)> | 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]} }**| 122| 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.| 123 124 125## EmitterOptions 126Provides particle emitter configuration. 127 128```typescript 129interface EmitterOptions<PARTICLE extends ParticleType> { 130 particle: EmitterParticleOptions<PARTICLE>; 131 emitRate?: number; 132 shape?: ParticleEmitterShape; 133 position?: ParticleTuple<Dimension, Dimension>; 134 size?: ParticleTuple<Dimension, Dimension>; 135} 136``` 137 138**Atomic service API**: This API can be used in atomic services since API version 11. 139 140**System capability**: SystemCapability.ArkUI.ArkUI.Full 141 142| Name| Type| Mandatory| Description| 143| -------- | -------- | -------- | -------- | 144| particle | [EmitterParticleOptions](#emitterparticleoptions14)<[PARTICLE](#particletype)> | 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>**NOTE**<br>Setting the lifespan to **-1** is not recommended unless continuous animation is required, as it may significantly impact performance.<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.| 145| 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.| 146| shape | [ParticleEmitterShape](#particleemittershape) | No| Emitter shape.<br> Default value: **ParticleEmitterShape.RECTANGLE**| 147| position | [ParticleTuple](#particletuple14)<[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]**| 148| size | [ParticleTuple](#particletuple14)<[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).| 149 150## ParticleConfigs 151 152```typescript 153interface ParticleConfigs { 154 [ParticleType.POINT]: PointParticleParameters; 155 [ParticleType.IMAGE]: ImageParticleParameters; 156} 157``` 158 159**Atomic service API**: This API can be used in atomic services since API version 11. 160 161**System capability**: SystemCapability.ArkUI.ArkUI.Full 162 163| Name | Type | Mandatory| Description| 164| -------- | -------------- | -------- | -------- | 165| [ParticleType.POINT] | [PointParticleParameters](#pointparticleparameters) | Yes | Point particle configuration.| 166| [ParticleType.IMAGE] | [ImageParticleParameters](#imageparticleparameters) | Yes | Image particle configuration.| 167 168## PointParticleParameters 169```typescript 170interface PointParticleParameters { 171 radius: VP; 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| radius | [VP](ts-types.md#vp10)| Yes | Particle radius.| 182 183## ImageParticleParameters 184```typescript 185interface ImageParticleParameters { 186 src: ResourceStr; 187 size: ParticleTuple<Dimension, Dimension>; 188 objectFit?: ImageFit; 189} 190``` 191 192**Atomic service API**: This API can be used in atomic services since API version 11. 193 194**System capability**: SystemCapability.ArkUI.ArkUI.Full 195 196| Name | Type | Mandatory| Description| 197| -------- | -------------- | -------- | -------- | 198| src | [ResourceStr](ts-types.md#resourcestr) | Yes | Image path. SVG images are not supported.| 199| size | [ParticleTuple](#particletuple14)<[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)> | Yes | Image size.| 200| objectFit| [ImageFit](ts-appendix-enums.md#imagefit)| No | Image display mode.| 201 202## ParticleColorPropertyOptions 203 204```typescript 205interface ParticleColorPropertyOptions<UPDATER extends ParticleUpdater> { 206 range: ParticleTuple<ResourceColor, ResourceColor>; 207 distributionType?: DistributionType; 208 updater?: ParticleColorUpdaterOptions<UPDATER>; 209} 210``` 211**Atomic service API**: This API can be used in atomic services since API version 11. 212 213**System capability**: SystemCapability.ArkUI.ArkUI.Full 214 215| Name| Type| Mandatory| Description| 216| -------- | -------- | -------- | -------- | 217| range | [ParticleTuple](#particletuple14)<[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]**| 218| 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.| 219| updater | [ParticleColorUpdaterOptions](#particlecolorupdateroptions14)<[UPDATER](#particleupdater)> | 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.| 220 221 222## ParticleColorPropertyUpdaterConfigs 223```typescript 224interface ParticleColorPropertyUpdaterConfigs { 225 [ParticleUpdater.NONE]: void; 226 [ParticleUpdater.RANDOM]: ParticleColorOptions; 227 [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<ResourceColor>>; 228} 229``` 230 231**Atomic service API**: This API can be used in atomic services since API version 11. 232 233**System capability**: SystemCapability.ArkUI.ArkUI.Full 234 235| Name| Type| Mandatory| Description| 236| -------- | -------- | -------- | -------- | 237|[ParticleUpdater.NONE]|void | Yes| The color does not change.| 238| [ParticleUpdater.RANDOM] | [ParticleColorOptions](#particlecoloroptions14) | 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. | 239[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.| 240 241## ParticlePropertyOptions 242```typescript 243interface ParticlePropertyOptions<TYPE, UPDATER extends ParticleUpdater> { 244 range: ParticleTuple<TYPE, TYPE>; 245 updater?: ParticleUpdaterOptions<TYPE, UPDATER>; 246} 247``` 248 249**Atomic service API**: This API can be used in atomic services since API version 11. 250 251**System capability**: SystemCapability.ArkUI.ArkUI.Full 252 253| Name| Type| Mandatory| Description| 254| -------- | -------- | -------- | -------- | 255| range | [ParticleTuple](#particletuple14)<[TYPE](#particleupdater), [TYPE](#particleupdater)> | 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 range is [0, 1]; the default value is **0.0**.<br>2. **scale** property: **range:[1.0,1.0]**; the value range is [0, 10000]; the default value is **0.0**.<br>3. **acceleration** speed property: **range:[0.0,0.0]**; the value range is [0, 10000]; the default value is **0.0**.<br>4. **acceleration** angle property: **range:[0.0,0.0]**; the value range is [-10000, 10000]; the default value is **0.0**.<br>5. **spin** speed property: **range:[0.0,0.0]**; the value range is [-10000, 10000]; the default value is **0.0**. 256| updater | [ParticleUpdaterOptions](#particleupdateroptions14)<[TYPE](#particleupdater), [UPDATER](#particleupdater)> | 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**.| 257 258 259## ParticlePropertyUpdaterConfigs 260```typescript 261interface ParticlePropertyUpdaterConfigs<T> { 262 [ParticleUpdater.NONE]: void; 263 [ParticleUpdater.RANDOM]: ParticleTuple<T, T>; 264 [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<T>>; 265} 266``` 267 268**Atomic service API**: This API can be used in atomic services since API version 11. 269 270**System capability**: SystemCapability.ArkUI.ArkUI.Full 271 272| Name| Type| Mandatory| Description| 273| -------- | -------- | -------- | -------- | 274| [ParticleUpdater.NONE]|void | Yes| The property does not change.| 275| [ParticleUpdater.RANDOM] | [ParticleTuple](#particletuple14)<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.| 276|[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.| 277 278## ParticlePropertyAnimation 279```typescript 280interface ParticlePropertyAnimation<T> { 281 from: T; 282 to: T; 283 startMillis: number; 284 endMillis: number; 285 curve?: Curve | ICurve; 286} 287``` 288 289**Atomic service API**: This API can be used in atomic services since API version 11. 290 291**System capability**: SystemCapability.ArkUI.ArkUI.Full 292 293| Name| Type| Mandatory| Description| 294| -------- | -------- | -------- | -------- | 295|from| T | Yes| Initial value of the property. If the value is invalid, the default value will be used.| 296| to | T | Yes| Target value of the property. If the value is invalid, the default value will be used.| 297|startMillis|number | Yes| Start time of the animation.<br>Unit: ms.<br>Value range: [0, +∞).| 298|endMillis|number | Yes| End time of the animation.<br>Unit: ms.<br>Value range: [0, +∞).| 299|curve|[Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve9)| No| Animation curve.<br>Default value: **Curve.Linear**| 300 301 302## ParticleType 303```typescript 304enum ParticleType { 305 POINT = 'point', 306 IMAGE = 'image', 307} 308``` 309**Atomic service API**: This API can be used in atomic services since API version 11. 310 311**System capability**: SystemCapability.ArkUI.ArkUI.Full 312 313| Name | Description| 314| -------- | -------- | 315POINT |Point particle.| 316IMAGE | Image particle.| 317 318 319 320## ParticleEmitterShape 321```typescript 322enum ParticleEmitterShape { 323 RECTANGLE = 'rectangle', 324 CIRCLE = 'circle', 325 ELLIPSE = 'ellipse', 326} 327``` 328 329**Atomic service API**: This API can be used in atomic services since API version 11. 330 331**System capability**: SystemCapability.ArkUI.ArkUI.Full 332 333| Name | Description| 334| -------- | -------- | 335RECTANGLE |The particle emitter is rectangular.| 336CIRCLE | The particle emitter is circular.| 337ELLIPSE |The particle emitter is elliptical.| 338 339## DistributionType<sup>12+<sup> 340```typescript 341enum DistributionType { 342 UNIFORM = 0, 343 GAUSSIAN = 1, 344} 345``` 346**Atomic service API**: This API can be used in atomic services since API version 12. 347 348**System capability**: SystemCapability.ArkUI.ArkUI.Full 349 350| Name | Description| 351| -------- | -------- | 352| UNIFORM |The initial color random values are distributed uniformly.| 353| GAUSSIAN | The initial color random values are distributed according to a Gaussian distribution.| 354 355## ParticleUpdater 356```typescript 357enum ParticleUpdater { 358 NONE = 'none', 359 RANDOM = 'random', 360 CURVE = 'curve', 361} 362``` 363 364**Atomic service API**: This API can be used in atomic services since API version 11. 365 366**System capability**: SystemCapability.ArkUI.ArkUI.Full 367 368| Name | Description| 369| -------- | -------- | 370|NONE |No change.| 371|RANDOM | Random change.| 372|CURVE |Change with the animation curve.| 373 374## DisturbanceFieldOptions<sup>12+</sup> 375 376**Atomic service API**: This API can be used in atomic services since API version 12. 377 378**System capability**: SystemCapability.ArkUI.ArkUI.Full 379 380| Name| Type | Mandatory| Description | 381| ------ | ------- | ---- | ---------------------------- | 382| 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.<br>Value range: (-∞, +∞).| 383| shape | [DisturbanceFieldShape](#disturbancefieldshape12) | No | Shape of the field.<br>Default value: **DisturbanceFieldShape.RECT**| 384| size | [SizeT](../js-apis-arkui-graphics.md#sizett12)<number>| No |Size of the field.<br>Default value: {width:0, height:0}.<br>Value range of **width** and **height**: [0, +∞).| 385| position | [PositionT](../js-apis-arkui-graphics.md#positiont12)<number> | No |Position of the field.<br>Default value: {x:0, y:0}.<br>Value range of **x** and **y**: (-∞, +∞).| 386| 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**.| 387| 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**.| 388| 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**.| 389| 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**.| 390 391## DisturbanceFieldShape<sup>12+</sup> 392 393**Atomic service API**: This API can be used in atomic services since API version 12. 394 395**System capability**: SystemCapability.ArkUI.ArkUI.Full 396 397| Name | Description | 398| --------| ----------| 399| RECT | Rectangle. | 400| CIRCLE | Circle. | 401| ELLIPSE | Ellipse. | 402 403## EmitterProperty<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| 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.| 412| 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.| 413| 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.| 414| 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.| 415 416## ParticleTuple<sup>14+</sup> 417 418```typescript 419declare type ParticleTuple<T1, T2> = [T1, T2]; 420``` 421 422Defines the tuple type representing a pair of animation parameters. 423 424**Atomic service API**: This API can be used in atomic services since API version 14. 425 426**System capability**: SystemCapability.ArkUI.ArkUI.Full 427 428| Type | Description | 429| ----------- | ---------------------------------------------- | 430| [T1, T2] | A pair of animation parameters, which can be of any type. | 431 432## Particles<sup>14+</sup> 433 434```typescript 435interface Particles< 436 PARTICLE extends ParticleType, 437 COLOR_UPDATER extends ParticleUpdater, 438 OPACITY_UPDATER extends ParticleUpdater, 439 SCALE_UPDATER extends ParticleUpdater, 440 ACC_SPEED_UPDATER extends ParticleUpdater, 441 ACC_ANGLE_UPDATER extends ParticleUpdater, 442 SPIN_UPDATER extends ParticleUpdater 443> { 444 particles: Array< 445 ParticleOptions< 446 PARTICLE, 447 COLOR_UPDATER, 448 OPACITY_UPDATER, 449 SCALE_UPDATER, 450 ACC_SPEED_UPDATER, 451 ACC_ANGLE_UPDATER, 452 SPIN_UPDATER 453 > 454 >; 455} 456``` 457 458Defines an array of particle options. 459 460**Atomic service API**: This API can be used in atomic services since API version 14. 461 462**System capability**: SystemCapability.ArkUI.ArkUI.Full 463 464| Name | Type | Mandatory| Description | 465| ------ | ------------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------- | 466| particles | Array<<br> ParticleOptions<<br> PARTICLE,<br> COLOR_UPDATER,<br> OPACITY_UPDATER,<br> SCALE_UPDATER,<br> ACC_SPEED_UPDATER,<br> ACC_ANGLE_UPDATER,<br> SPIN_UPDATER<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).| 467 468## VelocityOptions<sup>14+</sup> 469 470```typescript 471declare interface VelocityOptions { 472 speed: ParticleTuple<number, number>; 473 angle: ParticleTuple<number, number>; 474} 475``` 476 477Defines the particle velocity. 478 479**Atomic service API**: This API can be used in atomic services since API version 14. 480 481**System capability**: SystemCapability.ArkUI.ArkUI.Full 482 483| Name | Type | Mandatory| Description | 484| ------ | ------------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------- | 485| speed | [ParticleTuple](#particletuple14)<number, number> | Yes | Time rate at which the particle moves.<br>Default value: **{range:[0.0,0.0]}** | 486| angle | [ParticleTuple](#particletuple14)<number, number> | Yes | 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: **{range:[0.0,0.0]}**| 487 488## AccelerationOptions<sup>14+</sup> 489 490```typescript 491declare interface AccelerationOptions< 492 ACC_SPEED_UPDATER extends ParticleUpdater, 493 ACC_ANGLE_UPDATER extends ParticleUpdater 494> { 495 speed?: ParticlePropertyOptions<number, ACC_SPEED_UPDATER>; 496 angle?: ParticlePropertyOptions<number, ACC_ANGLE_UPDATER>; 497} 498``` 499 500Defines the particle acceleration. 501 502**Atomic service API**: This API can be used in atomic services since API version 14. 503 504**System capability**: SystemCapability.ArkUI.ArkUI.Full 505 506| Name | Type | Mandatory| Description | 507| ------ | --------------------------------------------------- | ---- | --------------------------------------------------------- | 508| speed | [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_SPEED_UPDATER](#particleupdater)> | No | Acceleration speed.<br>Default value: **{range:[0.0,0.0]}** | 509| angle | [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_SPEED_UPDATER](#particleupdater)> | No | Acceleration direction (in angles).<br>Default value: **{range:[0.0,0.0]}**| 510 511## EmitterParticleOptions<sup>14+</sup> 512 513```typescript 514interface EmitterParticleOptions<PARTICLE extends ParticleType> { 515 type: PARTICLE; 516 config: ParticleConfigs[PARTICLE]; 517 count: number; 518 lifetime?: number; 519 lifetimeRange?: number; 520} 521``` 522 523Defines the particle configuration. 524 525**Atomic service API**: This API can be used in atomic services since API version 14. 526 527**System capability**: SystemCapability.ArkUI.ArkUI.Full 528 529| Name | Type | Mandatory| Description | 530| ------ | --------------------------------------------------- | ---- | --------------------------------------------------------- | 531| type | [PARTICLE](#particletype) | Yes | Particle type, which can be **IMAGE** or **POINT**. | 532| config | [ParticleConfigs](#particleconfigs)[PARTICLE] | Yes | 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).| 533| count | number | Yes | Number of particles. The value is greater than or equal to -1. The value **-1** indicates that the number of particles is infinite.| 534| lifetime | number | No | 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>**NOTE**<br>Setting the lifespan to **-1** is not recommended unless continuous animation is required, as it may significantly impact performance.| 535| lifeTimeRange | number | No | 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.| 536 537## ParticleUpdaterOptions<sup>14+</sup> 538 539```typescript 540interface ParticleUpdaterOptions<TYPE, UPDATER extends ParticleUpdater> { 541 type: UPDATER; 542 config: ParticlePropertyUpdaterConfigs<TYPE>[UPDATER]; 543} 544``` 545 546Defines how the color property is updated. 547 548**Atomic service API**: This API can be used in atomic services since API version 14. 549 550**System capability**: SystemCapability.ArkUI.ArkUI.Full 551 552| Name | Type | Mandatory| Description | 553| ------ | --------------------------------------------------- | ---- | --------------------------------------------------------- | 554| type | [UPDATER](#particleupdater) | Yes | Type of property updating.<br>The default value of **type** is **ParticleUpdater.NONE**. | 555| config | [UPDATER](#particleupdater) | Yes | 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].| 556 557## ParticleColorUpdaterOptions<sup>14+</sup> 558 559```typescript 560interface ParticleColorUpdaterOptions<UPDATER extends ParticleUpdater> { 561 type: UPDATER; 562 config: ParticleColorPropertyUpdaterConfigs[UPDATER]; 563} 564``` 565 566Defines how the color property is updated. 567 568**Atomic service API**: This API can be used in atomic services since API version 14. 569 570**System capability**: SystemCapability.ArkUI.ArkUI.Full 571 572| Name | Type | Mandatory| Description | 573| ------ | --------------------------------------------------- | ---- | --------------------------------------------------------- | 574| type | [UPDATER](#particleupdater) | Yes | Type of property updating.<br>The default value of **type** is **ParticleUpdater.NONE**. | 575| config | [UPDATER](#particleupdater) | Yes | 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>**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.| 576 577## ParticleColorOptions<sup>14+</sup> 578 579```typescript 580interface ParticleColorOptions { 581 r: ParticleTuple<number, number>; 582 g: ParticleTuple<number, number>; 583 b: ParticleTuple<number, number>; 584 a: ParticleTuple<number, number>; 585} 586``` 587 588Defines the particle color options. 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. 589 590**Atomic service API**: This API can be used in atomic services since API version 14. 591 592**System capability**: SystemCapability.ArkUI.ArkUI.Full 593 594| Name | Type | Mandatory| Description | 595| ---- | ------------------------------ | ---- | --------------------------- | 596| r | [ParticleTuple](#particletuple14)<number, number> | Yes | Difference value for the red color channel. | 597| g | [ParticleTuple](#particletuple14)<number, number> | Yes | Difference value for the green color channel. | 598| b | [ParticleTuple](#particletuple14)<number, number> | Yes | Difference value for the blue color channel. | 599| a | [ParticleTuple](#particletuple14)<number, number> | Yes | Difference value for the alpha (transparency) channel. | 600 601## Example 602 603### Example 1: Initializing Particles with Circular Shapes 604 605This example demonstrates the basic usage of particle animations by initializing particles with circular shapes. 606 607```ts 608// xxx.ets 609@Entry 610@Component 611struct ParticleExample { 612 build() { 613 Stack() { 614 Text() 615 .width(300).height(300).backgroundColor(Color.Black) 616 Particle({ 617 particles: [ 618 { 619 emitter: { 620 particle: { 621 type: ParticleType.POINT, // Particle type. 622 config: { 623 radius: 10// Point radius. 624 }, 625 count: 500, // Total number of particles. 626 lifetime: 10000, // Particle lifetime, in ms. 627 lifetimeRange: 100// Range of particle lifetime values, in ms. 628 }, 629 emitRate: 10, // Number of particles emitted per second. 630 position: [0, 0], 631 shape: ParticleEmitterShape.RECTANGLE// Emitter shape. 632 }, 633 color: { 634 range: [Color.Red, Color.Yellow], // Initial color range. 635 updater: { 636 type: ParticleUpdater.CURVE, // Change with the animation curve. 637 config: [ 638 { 639 from: Color.White, // Initial value of the change. 640 to: Color.Pink, // Target value of the change. 641 startMillis: 0, // Start time. 642 endMillis: 3000, // End time. 643 curve: Curve.EaseIn// Animation curve. 644 }, 645 { 646 from: Color.Pink, 647 to: Color.Orange, 648 startMillis: 3000, 649 endMillis: 5000, 650 curve: Curve.EaseIn 651 }, 652 { 653 from: Color.Orange, 654 to: Color.Pink, 655 startMillis: 5000, 656 endMillis: 8000, 657 curve: Curve.EaseIn 658 }, 659 ] 660 } 661 }, 662 opacity: { 663 range: [0.0, 1.0], // The initial value of particle opacity is randomly generated from the [0.0, 1.0] range. 664 updater: { 665 type: ParticleUpdater.CURVE, 666 config: [ 667 { 668 from: 0.0, 669 to: 1.0, 670 startMillis: 0, 671 endMillis: 3000, 672 curve: Curve.EaseIn 673 }, 674 { 675 from: 1.0, 676 to: 0.0, 677 startMillis: 5000, 678 endMillis: 10000, 679 curve: Curve.EaseIn 680 } 681 ] 682 } 683 }, 684 scale: { 685 range: [0.0, 0.0], 686 updater: { 687 type: ParticleUpdater.CURVE, 688 config: [ 689 { 690 from: 0.0, 691 to: 0.5, 692 startMillis: 0, 693 endMillis: 3000, 694 curve: Curve.EaseIn 695 } 696 ] 697 } 698 }, 699 acceleration: { 700 // Acceleration. speed indicates the acceleration speed, and angle indicates the acceleration direction. 701 speed: { 702 range: [3, 9], 703 updater: { 704 type: ParticleUpdater.RANDOM, // The speed changes randomly. 705 config: [1, 20] 706 } 707 }, 708 angle: { 709 range: [90, 90] 710 } 711 } 712 713 } 714 ] 715 }).width(300).height(300) 716 }.width("100%").height("100%").align(Alignment.Center) 717 } 718} 719``` 720 721 722 723### Example 2: Initializing Particles with Images 724 725This example demonstrates the basic usage of particle animations by initializing particles with images. 726 727```ts 728@Entry 729@Component 730struct ParticleExample { 731 @State 732 myCount: number = 100 733 flag: boolean = false; 734 735 build() { 736 Column() { 737 Stack() { 738 Particle({ 739 particles: [ 740 { 741 emitter: { 742 particle: { 743 type: ParticleType.IMAGE, 744 config: { 745 src: $r("app.media.book"), 746 size: [10, 10] 747 }, 748 count: this.myCount, 749 lifetime: 10000, 750 lifetimeRange: 100 751 }, 752 emitRate: 3, 753 shape: ParticleEmitterShape.CIRCLE 754 }, 755 color: { 756 range: [Color.White, Color.White] 757 }, 758 opacity: { 759 range: [1.0, 1.0], 760 updater: { 761 type: ParticleUpdater.CURVE, 762 config: [ 763 { 764 from: 0, 765 to: 1.0, 766 startMillis: 0, 767 endMillis: 6000 768 }, 769 { 770 from: 1.0, 771 to: .0, 772 startMillis: 6000, 773 endMillis: 10000 774 } 775 ] 776 } 777 }, 778 scale: { 779 range: [0.1, 1.0], 780 updater: { 781 type: ParticleUpdater.CURVE, 782 config: [ 783 { 784 from: 0, 785 to: 1.5, 786 startMillis: 0, 787 endMillis: 8000, 788 curve: Curve.EaseIn 789 } 790 791 ] 792 } 793 }, 794 acceleration: { 795 speed: { 796 range: [3, 9], 797 updater: { 798 type: ParticleUpdater.CURVE, 799 config: [ 800 { 801 from: 10, 802 to: 20, 803 startMillis: 0, 804 endMillis: 3000, 805 curve: Curve.EaseIn 806 }, 807 { 808 from: 10, 809 to: 2, 810 startMillis: 3000, 811 endMillis: 8000, 812 curve: Curve.EaseIn 813 } 814 ] 815 } 816 }, 817 angle: { 818 range: [0, 180], 819 updater: { 820 type: ParticleUpdater.CURVE, 821 config: [{ 822 from: 1, 823 to: 2, 824 startMillis: 0, 825 endMillis: 1000, 826 curve: Curve.EaseIn 827 }, 828 { 829 from: 50, 830 to: -50, 831 startMillis: 1000, 832 endMillis: 3000, 833 curve: Curve.EaseIn 834 }, 835 { 836 from: 3, 837 to: 5, 838 startMillis: 3000, 839 endMillis: 8000, 840 curve: Curve.EaseIn 841 } 842 ] 843 } 844 } 845 }, 846 spin: { 847 range: [0.1, 1.0], 848 updater: { 849 type: ParticleUpdater.CURVE, 850 config: [ 851 { 852 from: 0, 853 to: 360, 854 startMillis: 0, 855 endMillis: 8000, 856 curve: Curve.EaseIn 857 } 858 ] 859 } 860 }, 861 } 862 , { 863 emitter: { 864 particle: { 865 type: ParticleType.IMAGE, 866 config: { 867 src: $r('app.media.heart'), 868 size: [10, 10] 869 }, 870 count: this.myCount, 871 lifetime: 10000, 872 lifetimeRange: 100 873 }, 874 emitRate: 3, 875 shape: ParticleEmitterShape.CIRCLE 876 }, 877 color: { 878 range: [Color.White, Color.White] 879 }, 880 opacity: { 881 range: [1.0, 1.0], 882 updater: { 883 type: ParticleUpdater.CURVE, 884 config: [ 885 { 886 from: 0, 887 to: 1.0, 888 startMillis: 0, 889 endMillis: 6000 890 }, 891 { 892 from: 1.0, 893 to: .0, 894 startMillis: 6000, 895 endMillis: 10000 896 } 897 ] 898 } 899 }, 900 scale: { 901 range: [0.1, 1.0], 902 updater: { 903 type: ParticleUpdater.CURVE, 904 config: [ 905 { 906 from: 0, 907 to: 2.0, 908 startMillis: 0, 909 endMillis: 10000, 910 curve: Curve.EaseIn 911 } 912 913 ] 914 } 915 }, 916 acceleration: { 917 speed: { 918 range: [3, 9], 919 updater: { 920 type: ParticleUpdater.CURVE, 921 config: [ 922 { 923 from: 10, 924 to: 20, 925 startMillis: 0, 926 endMillis: 3000, 927 curve: Curve.EaseIn 928 }, 929 { 930 from: 10, 931 to: 2, 932 startMillis: 3000, 933 endMillis: 8000, 934 curve: Curve.EaseIn 935 } 936 ] 937 } 938 }, 939 angle: { 940 range: [0, 180], 941 updater: { 942 type: ParticleUpdater.CURVE, 943 config: [{ 944 from: 1, 945 to: 2, 946 startMillis: 0, 947 endMillis: 1000, 948 curve: Curve.EaseIn 949 }, 950 { 951 from: 50, 952 to: -50, 953 startMillis: 0, 954 endMillis: 3000, 955 curve: Curve.EaseIn 956 }, 957 { 958 from: 3, 959 to: 5, 960 startMillis: 3000, 961 endMillis: 10000, 962 curve: Curve.EaseIn 963 } 964 ] 965 } 966 } 967 }, 968 spin: { 969 range: [0.1, 1.0], 970 updater: { 971 type: ParticleUpdater.CURVE, 972 config: [ 973 { 974 from: 0, 975 to: 360, 976 startMillis: 0, 977 endMillis: 10000, 978 curve: Curve.EaseIn 979 } 980 ] 981 } 982 }, 983 }, { 984 emitter: { 985 particle: { 986 type: ParticleType.IMAGE, 987 config: { 988 src: $r('app.media.sun'), 989 size: [10, 10] 990 }, 991 count: this.myCount, 992 lifetime: 10000, 993 lifetimeRange: 100 994 }, 995 emitRate: 3, 996 shape: ParticleEmitterShape.CIRCLE 997 }, 998 color: { 999 range: [Color.White, Color.White] 1000 }, 1001 opacity: { 1002 range: [1.0, 1.0], 1003 updater: { 1004 type: ParticleUpdater.CURVE, 1005 config: [ 1006 { 1007 from: 0, 1008 to: 1.0, 1009 startMillis: 0, 1010 endMillis: 6000 1011 }, 1012 { 1013 from: 1.0, 1014 to: .0, 1015 startMillis: 6000, 1016 endMillis: 10000 1017 } 1018 ] 1019 } 1020 }, 1021 scale: { 1022 range: [0.1, 1.0], 1023 updater: { 1024 type: ParticleUpdater.CURVE, 1025 config: [ 1026 { 1027 from: 0, 1028 to: 2.0, 1029 startMillis: 0, 1030 endMillis: 10000, 1031 curve: Curve.EaseIn 1032 } 1033 1034 ] 1035 } 1036 }, 1037 acceleration: { 1038 speed: { 1039 range: [3, 9], 1040 updater: { 1041 type: ParticleUpdater.CURVE, 1042 config: [ 1043 { 1044 from: 10, 1045 to: 20, 1046 startMillis: 0, 1047 endMillis: 3000, 1048 curve: Curve.EaseIn 1049 }, 1050 { 1051 from: 10, 1052 to: 2, 1053 startMillis: 3000, 1054 endMillis: 8000, 1055 curve: Curve.EaseIn 1056 } 1057 ] 1058 } 1059 }, 1060 angle: { 1061 range: [0, 180], 1062 updater: { 1063 type: ParticleUpdater.CURVE, 1064 config: [{ 1065 from: 1, 1066 to: 2, 1067 startMillis: 0, 1068 endMillis: 1000, 1069 curve: Curve.EaseIn 1070 }, 1071 { 1072 from: 50, 1073 to: -50, 1074 startMillis: 1000, 1075 endMillis: 3000, 1076 curve: Curve.EaseIn 1077 }, 1078 { 1079 from: 3, 1080 to: 5, 1081 startMillis: 3000, 1082 endMillis: 8000, 1083 curve: Curve.EaseIn 1084 } 1085 ] 1086 } 1087 } 1088 }, 1089 spin: { 1090 range: [0.1, 1.0], 1091 updater: { 1092 type: ParticleUpdater.CURVE, 1093 config: [ 1094 { 1095 from: 0, 1096 to: 360, 1097 startMillis: 0, 1098 endMillis: 10000, 1099 curve: Curve.EaseIn 1100 } 1101 ] 1102 } 1103 }, 1104 } 1105 ] 1106 }).width(300).height(300) 1107 1108 }.width(500).height(500).align(Alignment.Center) 1109 }.width("100%").height("100%") 1110 1111 } 1112} 1113``` 1114 1115 1116### Example 3: Changing Motion Trajectories with the Particle Disturbance Field 1117 1118This example demonstrates how to change the motion trajectories of particles by applying disturbances through the particle disturbance field. 1119 1120``` 1121@Entry 1122@Component 1123struct ParticleExample { 1124 build() { 1125 Stack() { 1126 Text() 1127 .width(300).height(300).backgroundColor(Color.Black) 1128 Particle({ 1129 particles: [ 1130 { 1131 emitter: { 1132 particle: { 1133 type: ParticleType.POINT, // Particle type. 1134 config: { 1135 radius: 10// Point radius. 1136 }, 1137 count: 500, // Total number of particles. 1138 lifetime: 10000// Particle lifetime, in ms. 1139 }, 1140 emitRate: 10, // Number of particles emitted per second. 1141 position: [0, 0], 1142 shape: ParticleEmitterShape.RECTANGLE// Emitter shape. 1143 }, 1144 color: { 1145 range: [Color.Red, Color.Yellow], // Initial color range. 1146 updater: { 1147 type: ParticleUpdater.CURVE, // Change with the animation curve. 1148 config: [ 1149 { 1150 from: Color.White, // Initial value of the change. 1151 to: Color.Pink, // Target value of the change. 1152 startMillis: 0, // Start time. 1153 endMillis: 3000, // End time. 1154 curve: Curve.EaseIn// Animation curve. 1155 }, 1156 { 1157 from: Color.Pink, 1158 to: Color.Orange, 1159 startMillis: 3000, 1160 endMillis: 5000, 1161 curve: Curve.EaseIn 1162 }, 1163 { 1164 from: Color.Orange, 1165 to: Color.Pink, 1166 startMillis: 5000, 1167 endMillis: 8000, 1168 curve: Curve.EaseIn 1169 }, 1170 ] 1171 } 1172 }, 1173 opacity: { 1174 range: [0.0, 1.0], // The initial value of particle opacity is randomly generated from the [0.0, 1.0] range. 1175 updater: { 1176 type: ParticleUpdater.CURVE, 1177 config: [ 1178 { 1179 from: 0.0, 1180 to: 1.0, 1181 startMillis: 0, 1182 endMillis: 3000, 1183 curve: Curve.EaseIn 1184 }, 1185 { 1186 from: 1.0, 1187 to: 0.0, 1188 startMillis: 5000, 1189 endMillis: 10000, 1190 curve: Curve.EaseIn 1191 } 1192 ] 1193 } 1194 }, 1195 scale: { 1196 range: [0.0, 0.0], 1197 updater: { 1198 type: ParticleUpdater.CURVE, 1199 config: [ 1200 { 1201 from: 0.0, 1202 to: 0.5, 1203 startMillis: 0, 1204 endMillis: 3000, 1205 curve: Curve.EaseIn 1206 } 1207 ] 1208 } 1209 }, 1210 acceleration: { 1211 // Acceleration. speed indicates the acceleration speed, and angle indicates the acceleration direction. 1212 speed: { 1213 range: [3, 9], 1214 updater: { 1215 type: ParticleUpdater.RANDOM, 1216 config: [1, 20] 1217 } 1218 }, 1219 angle: { 1220 range: [90, 90] 1221 } 1222 } 1223 1224 } 1225 ] 1226 }).width(300).height(300).disturbanceFields([{ 1227 strength: 10, 1228 shape: DisturbanceFieldShape.RECT, 1229 size: { width: 100, height: 100 }, 1230 position: { x: 100, y: 100 }, 1231 feather: 15, 1232 noiseScale: 10, 1233 noiseFrequency: 15, 1234 noiseAmplitude: 5 1235 }]) 1236 }.width("100%").height("100%").align(Alignment.Center) 1237 } 1238} 1239 1240``` 1241 1242 1243### Example 4: Adjusting the Emitter Position 1244This example demonstrates how to adjust the position of the particle emitter through **emitter()**. 1245```ts 1246@Entry 1247@Component 1248struct ParticleExample { 1249 @State emitterProperties: Array<EmitterProperty> = [ 1250 { 1251 index: 0, 1252 emitRate: 100, 1253 position: { x: 60, y: 80 }, 1254 size: { width: 200, height: 200 } 1255 } 1256 ] 1257 1258 build() { 1259 Stack() { 1260 Text() 1261 .width(300).height(300).backgroundColor(Color.Black) 1262 Particle({ 1263 particles: [ 1264 { 1265 emitter: { 1266 particle: { 1267 type: ParticleType.POINT, // Particle type. 1268 config: { 1269 radius: 5// Point radius. 1270 }, 1271 count: 400, // Total number of particles. 1272 lifetime: -1// Particle lifetime. The value -1 indicates that the lifetime of the particle is infinite. 1273 }, 1274 emitRate: 10, // Number of particles emitted per second. 1275 position: [0, 0], // Emitter position. 1276 shape: ParticleEmitterShape.CIRCLE// Emitter shape. 1277 }, 1278 color: { 1279 range: [Color.Red, Color.Yellow], // Initial color range. 1280 updater: { 1281 type: ParticleUpdater.CURVE, // Change with the animation curve. 1282 config: [ 1283 { 1284 from: Color.White, 1285 to: Color.Pink, 1286 startMillis: 0, 1287 endMillis: 3000, 1288 curve: Curve.EaseIn 1289 }, 1290 { 1291 from: Color.Pink, 1292 to: Color.Orange, 1293 startMillis: 3000, 1294 endMillis: 5000, 1295 curve: Curve.EaseIn 1296 }, 1297 { 1298 from: Color.Orange, 1299 to: Color.Pink, 1300 startMillis: 5000, 1301 endMillis: 8000, 1302 curve: Curve.EaseIn 1303 }, 1304 ] 1305 } 1306 }, 1307 }, 1308 ] 1309 }) 1310 .width(300) 1311 .height(300) 1312 .emitter(this.emitterProperties) 1313 }.width("100%").height("100%").align(Alignment.Center) 1314 } 1315} 1316``` 1317 1318
