harmony 鸿蒙Particle Animation (Particle)

  • 2025-06-12
  • 浏览 (3)

Particle Animation (Particle)

Particle 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.

The component used for producing particle animations is Particle.

NOTE

This component is supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.

Child Components

Not supported

APIs

interface ParticleInterface {
  <
    PARTICLE extends ParticleType,
    COLOR_UPDATER extends ParticleUpdater,
    OPACITY_UPDATER extends ParticleUpdater,
    SCALE_UPDATER extends ParticleUpdater,
    ACC_SPEED_UPDATER extends ParticleUpdater,
    ACC_ANGLE_UPDATER extends ParticleUpdater,
    SPIN_UPDATER extends ParticleUpdater
  >(particles: Particles<
      PARTICLE,
      COLOR_UPDATER,
      OPACITY_UPDATER,
      SCALE_UPDATER,
      ACC_SPEED_UPDATER,
      ACC_ANGLE_UPDATER,
      SPIN_UPDATER
    >): ParticleAttribute;
}

Atomic service API: This API can be used in atomic services since API version 11.

Parameters

Name Type Mandatory Description
particles Particles<
PARTICLE,
COLOR_UPDATER,
OPACITY_UPDATER,
SCALE_UPDATER,
ACC_SPEED_UPDATER,
ACC_ANGLE_UPDATER,
SPIN_UPDATER
>
 Yes Particles. For details, see Particles.

Attributes

In addition to the universal attributes, the following attributes are supported.

disturbanceFields12+

disturbanceFields(fields: Array&lt;DisturbanceFieldOptions&gt;)

Sets the disturbance fields.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
fields Array<DisturbanceFieldOptions> Yes Array of disturbance fields.

emitter12+

emitter(value: Array&lt;EmitterProperty&gt;)

Sets the emitter parameters.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
value Array<EmitterProperty> Yes Array of emitter parameters to set.

Events

The universal events are supported.

ParticleOptions

interface ParticleOptions<
  PARTICLE extends ParticleType,
  COLOR_UPDATER extends ParticleUpdater,
  OPACITY_UPDATER extends ParticleUpdater,
  SCALE_UPDATER extends ParticleUpdater,
  ACC_SPEED_UPDATER extends ParticleUpdater,
  ACC_ANGLE_UPDATER extends ParticleUpdater,
  SPIN_UPDATER extends ParticleUpdater
> {
  emitter: EmitterOptions<PARTICLE>;
  color?: ParticleColorPropertyOptions<COLOR_UPDATER>;
  opacity?: ParticlePropertyOptions<number, OPACITY_UPDATER>;
  scale?: ParticlePropertyOptions<number, SCALE_UPDATER>;
  velocity?: VelocityOptions;
  acceleration?: AccelerationOptions<ACC_SPEED_UPDATER, ACC_ANGLE_UPDATER>;
  spin?: ParticlePropertyOptions<number, SPIN_UPDATER>;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
emitter EmitterOptions<PARTICLE> Yes Particle emitter.
color ParticleColorPropertyOptions<COLOR_UPDATER> No Particle color.
NOTE
Default value: { range:[Color.White,Color.White] }. Colors cannot be set for image particles.
opacity ParticlePropertyOptions<number, OPACITY_UPDATER> No Particle opacity.
Default value: { range:[1.0,1.0] }
scale ParticlePropertyOptions<number, SCALE_UPDATER> No Particle scale.
Default value: { range:[1.0,1.0] }
velocity VelocityOptions No Particle velocity.
NOTE
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.
Default value: {speed: [0.0,0.0],angle: [0.0,0.0] }
acceleration AccelerationOptions<ACC_SPEED_UPDATER, ACC_ANGLE_UPDATER> No Particle acceleration.
NOTE
speed indicates the acceleration speed, and angle indicates the acceleration direction (in angles).
Default value: { speed:{range:[0.0,0.0]},angle:{range:[0.0,0.0]} }
spin ParticlePropertyOptions No Particle spin angle.
Default value: {range:[0.0,0.0]}
Direction: A positive number indicates clockwise spinning, and a negative number indicates anticlockwise spinning.

EmitterOptions

Provides particle emitter configuration.

interface EmitterOptions<PARTICLE extends ParticleType> {   
  particle: EmitterParticleOptions<PARTICLE>;
  emitRate?: number;
  shape?: ParticleEmitterShape;
  position?: ParticleTuple<Dimension, Dimension>;
  size?: ParticleTuple<Dimension, Dimension>;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
particle EmitterParticleOptions<PARTICLE> Yes Particle configuration.
- type: particle type, which can be IMAGE or POINT.

Atomic service API: This API can be used in atomic services since API version 11.
- config: configuration of the particle type.
- The value type of config is subject to the value of type.
1. If type is ParticleType.POINT, the config type is PointParticleParameters.
2. If type is ParticleType.IMAGE, the config type is ImageParticleParameters.
Atomic service API: This API can be used in atomic services since API version 11.
- count: number of particles. The value is greater than or equal to -1. The value -1 indicates that the number of particles is infinite.
Atomic service API: This API can be used in atomic services since API version 11.
- 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.
NOTE
Setting the lifespan to -1 is not recommended unless continuous animation is required, as it may significantly impact performance.
Atomic service API: This API can be used in atomic services since API version 11.
- 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.
Atomic service API: This API can be used in atomic services since API version 12.
emitRate number No Emit rate (that is, the number of particles emitted per second).
Default value: 5. If the value specified is less than 0, the default value is used.
The emitRate value can significantly impact performance when it exceeds 5000; you are advised to set it to be less than 5000.
shape ParticleEmitterShape No Emitter shape.
Default value: ParticleEmitterShape.RECTANGLE
position ParticleTuple<Dimension, Dimension> 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.
Default value: [0.0, 0.0]
size ParticleTuple<Dimension, Dimension> No Size of the emit window. The first parameter indicates the emitter width, and the second parameter indicates the emitter height.
Default value: [‘100%’, ‘100%’] (that is, the emit window fully occupies the component).

ParticleConfigs

interface ParticleConfigs { 
  [ParticleType.POINT]: PointParticleParameters;
  [ParticleType.IMAGE]: ImageParticleParameters;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
[ParticleType.POINT] PointParticleParameters Yes Point particle configuration.
[ParticleType.IMAGE] ImageParticleParameters Yes Image particle configuration.

PointParticleParameters

interface PointParticleParameters {
  radius: VP;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
radius VP Yes Particle radius.

ImageParticleParameters

interface ImageParticleParameters {
  src: ResourceStr;
  size: ParticleTuple<Dimension, Dimension>;
  objectFit?: ImageFit;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
src ResourceStr Yes Image path. SVG images are not supported.
size ParticleTuple<Dimension, Dimension> Yes Image size.
objectFit ImageFit No Image display mode.

ParticleColorPropertyOptions

interface ParticleColorPropertyOptions<UPDATER extends ParticleUpdater> {
  range: ParticleTuple<ResourceColor, ResourceColor>; 
  distributionType?: DistributionType;
  updater?: ParticleColorUpdaterOptions<UPDATER>;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
range ParticleTuple<ResourceColor, ResourceColor> Yes Initial color range of the particle. The initial color of particles generated by the particle emitter is randomly selected in this range.
Default value: range:[Color.White,Color.White]
distributionType12+ DistributionType No Type of random value distribution for the initial color of the particle. Both uniform distribution and normal (Gaussian) distribution are supported.
Default value: DistributionType.UNIFORM
Atomic service API: This API can be used in atomic services since API version 12.
updater ParticleColorUpdaterOptions<UPDATER> No How the color property is updated. The available options of type are as follows:
1. ParticleUpdater.NONE: The property does not change. In this case, the config type is ParticleColorPropertyUpdaterConfigs[ParticleUpdater.NONE].
2. ParticleUpdater.RANDOM: The property changes randomly. In this case, the config type is ParticleColorPropertyUpdaterConfigs[ParticleUpdater.RANDOM].
3. ParticleUpdater.CURVE: The property changes with the animation curve. In this case, the config type is ParticleColorPropertyUpdaterConfigs[ParticleUpdater.CURVE].
The default value of type is ParticleUpdater.NONE.
NOTE
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.

ParticleColorPropertyUpdaterConfigs

interface ParticleColorPropertyUpdaterConfigs {
  [ParticleUpdater.NONE]: void;
  [ParticleUpdater.RANDOM]: ParticleColorOptions;
  [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<ResourceColor>>;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
[ParticleUpdater.NONE] void Yes The color does not change.
[ParticleUpdater.RANDOM] ParticleColorOptions 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.
[ParticleUpdater.CURVE] Array<ParticlePropertyAnimation<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.

ParticlePropertyOptions

interface ParticlePropertyOptions<TYPE, UPDATER extends ParticleUpdater> {
  range: ParticleTuple<TYPE, TYPE>;
  updater?: ParticleUpdaterOptions<TYPE, UPDATER>;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
range ParticleTuple<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.
NOTE
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.
The default value varies by property:
1. opacity property: range:[1.0,1.0]; the value range is [0, 1]; the default value is 0.0.
2. scale property: range:[1.0,1.0]; the value range is [0, 10000]; the default value is 0.0.
3. acceleration speed property: range:[0.0,0.0]; the value range is [0, 10000]; the default value is 0.0.
4. acceleration angle property: range:[0.0,0.0]; the value range is [-10000, 10000]; the default value is 0.0.
5. spin speed property: range:[0.0,0.0]; the value range is [-10000, 10000]; the default value is 0.0.
updater ParticleUpdaterOptions<TYPE, UPDATER> No How the property is updated. The available options of type are as follows:
1. ParticleUpdater.NONE: The property does not change. In this case, the config type is ParticlePropertyUpdaterConfigs[ParticleUpdater.NONE].
2. ParticleUpdater.RANDOM: The property changes randomly. In this case, the config type is ParticlePropertyUpdaterConfigs[ParticleUpdater.RANDOM].
3. ParticleUpdater.CURVE: The property changes with the animation curve. In this case, the config type is ParticlePropertyUpdaterConfigs[ParticleUpdater.CURVE].
The default value of type is ParticleUpdater.NONE.

ParticlePropertyUpdaterConfigs

interface ParticlePropertyUpdaterConfigs<T> {
    [ParticleUpdater.NONE]: void;
    [ParticleUpdater.RANDOM]: ParticleTuple<T, T>;
    [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<T>>;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
[ParticleUpdater.NONE] void Yes The property does not change.
[ParticleUpdater.RANDOM] ParticleTuple Yes The property changes randomly, with the per-second change difference being a value randomly generated from the range.
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:
1. When the random change difference is 0.5, the target property value is 0.2 + 0.5 = 0.7.
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.
NOTE
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.
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.
[ParticleUpdater.CURVE] Array<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.

ParticlePropertyAnimation

interface ParticlePropertyAnimation<T> {
  from: T;
  to: T;
  startMillis: number;
  endMillis: number;
  curve?: Curve|ICurve;
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
from T Yes Initial value of the property. If the value is invalid, the default value will be used.
to T Yes Target value of the property. If the value is invalid, the default value will be used.
startMillis number Yes Start time of the animation.
Unit: ms.
Value range: [0, +∞).
endMillis number Yes End time of the animation.
Unit: ms.
Value range: [0, +∞).
curve Curve |ICurve No Animation curve.
Default value: Curve.Linear

ParticleType

enum ParticleType {
  POINT = 'point',
  IMAGE = 'image',
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Description
POINT Point particle.
IMAGE Image particle.

ParticleEmitterShape

enum ParticleEmitterShape {
  RECTANGLE = 'rectangle',
  CIRCLE = 'circle',
  ELLIPSE = 'ellipse',
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Description
RECTANGLE The particle emitter is rectangular.
CIRCLE The particle emitter is circular.
ELLIPSE The particle emitter is elliptical.

DistributionType12+

enum DistributionType {
  UNIFORM = 0,
  GAUSSIAN = 1,
}

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Description
UNIFORM The initial color random values are distributed uniformly.
GAUSSIAN The initial color random values are distributed according to a Gaussian distribution.

ParticleUpdater

enum ParticleUpdater {
  NONE = 'none',
  RANDOM = 'random',
  CURVE = 'curve',
}

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Description
NONE No change.
RANDOM Random change.
CURVE Change with the animation curve.

DisturbanceFieldOptions12+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
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.
Value range: (-∞, +∞).
shape DisturbanceFieldShape No Shape of the field.
Default value: DisturbanceFieldShape.RECT
size SizeT&lt;number&gt; No Size of the field.
Default value: {width:0, height:0}.
Value range of width and height: [0, +∞).
position PositionT&lt;number&gt; No Position of the field.
Default value: {x:0, y:0}.
Value range of x and y: (-∞, +∞).
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.
Default value: 0.
noiseScale number No Noise scale, used to control the overall size of the noise pattern. The value is greater than or equal to 0.
Default value: 1.
noiseFrequency number No Noise frequency. The higher the frequency, the finer the noise. The value is greater than or equal to 0.
Default value: 1.
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.
Default value: 1.

DisturbanceFieldShape12+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Description
RECT Rectangle.
CIRCLE Circle.
ELLIPSE Ellipse.

EmitterProperty12+

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
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.
emitRate number No Emit rate, that is, the number of particles emitted per second.
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.
position PositionT&lt;number&gt; No Array of emitter positions. Only the number type is supported.
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.
size SizeT&lt;number&gt; No Size of the emit window. Only the number type is supported.
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.

ParticleTuple14+

declare type ParticleTuple<T1, T2> = [T1, T2];

Defines the tuple type representing a pair of animation parameters.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type Description
[T1, T2] A pair of animation parameters, which can be of any type.

Particles14+

interface Particles<
  PARTICLE extends ParticleType,
  COLOR_UPDATER extends ParticleUpdater,
  OPACITY_UPDATER extends ParticleUpdater,
  SCALE_UPDATER extends ParticleUpdater,
  ACC_SPEED_UPDATER extends ParticleUpdater,
  ACC_ANGLE_UPDATER extends ParticleUpdater,
  SPIN_UPDATER extends ParticleUpdater
> {
  particles: Array<
    ParticleOptions<
      PARTICLE,
      COLOR_UPDATER,
      OPACITY_UPDATER,
      SCALE_UPDATER,
      ACC_SPEED_UPDATER,
      ACC_ANGLE_UPDATER,
      SPIN_UPDATER
    >
  >;
}

Defines an array of particle options.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
particles Array<
ParticleOptions<
PARTICLE,
COLOR_UPDATER,
OPACITY_UPDATER,
SCALE_UPDATER,
ACC_SPEED_UPDATER,
ACC_ANGLE_UPDATER,
SPIN_UPDATER
>
>		 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.

VelocityOptions14+

declare interface VelocityOptions {
  speed: ParticleTuple<number, number>;
  angle: ParticleTuple<number, number>;
}

Defines the particle velocity.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
speed ParticleTuple Yes Time rate at which the particle moves.
Default value: {range:[0.0,0.0]}
angle ParticleTuple 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.
Default value: {range:[0.0,0.0]}

AccelerationOptions14+

declare interface AccelerationOptions<
  ACC_SPEED_UPDATER extends ParticleUpdater,
  ACC_ANGLE_UPDATER extends ParticleUpdater
> {
  speed?: ParticlePropertyOptions<number, ACC_SPEED_UPDATER>;
  angle?: ParticlePropertyOptions<number, ACC_ANGLE_UPDATER>;
}

Defines the particle acceleration.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
speed ParticlePropertyOptions No Acceleration speed.
Default value: {range:[0.0,0.0]}
angle ParticlePropertyOptions No Acceleration direction (in angles).
Default value: {range:[0.0,0.0]}

EmitterParticleOptions14+

interface EmitterParticleOptions<PARTICLE extends ParticleType> {
  type: PARTICLE;
  config: ParticleConfigs[PARTICLE];
  count: number;
  lifetime?: number;
  lifetimeRange?: number;
}

Defines the particle configuration.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
type PARTICLE Yes Particle type, which can be IMAGE or POINT.
config ParticleConfigs[PARTICLE] Yes Configuration of the particle type.
The value type of config is subject to the value of type.
1. If type is ParticleType.POINT, the config type is PointParticleParameters.
2. If type is ParticleType.IMAGE, the config type is ImageParticleParameters.
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.
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.
NOTE
Setting the lifespan to -1 is not recommended unless continuous animation is required, as it may significantly impact performance.
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.

ParticleUpdaterOptions14+

interface ParticleUpdaterOptions<TYPE, UPDATER extends ParticleUpdater> {
  type: UPDATER;
  config: ParticlePropertyUpdaterConfigs<TYPE>[UPDATER];
}

Defines how the color property is updated.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
type UPDATER Yes Type of property updating.
The default value of type is ParticleUpdater.NONE.
config UPDATER Yes How the property is updated. The available options of type are as follows:
1. ParticleUpdater.NONE: The property does not change. In this case, the config type is ParticlePropertyUpdaterConfigs[ParticleUpdater.NONE].
2. ParticleUpdater.RANDOM: The property changes randomly. In this case, the config type is ParticlePropertyUpdaterConfigs[ParticleUpdater.RANDOM].
3. ParticleUpdater.CURVE: The property changes with the animation curve. In this case, the config type is ParticlePropertyUpdaterConfigs[ParticleUpdater.CURVE].

ParticleColorUpdaterOptions14+

interface ParticleColorUpdaterOptions<UPDATER extends ParticleUpdater> {
  type: UPDATER;
  config: ParticleColorPropertyUpdaterConfigs[UPDATER];
}

Defines how the color property is updated.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
type UPDATER Yes Type of property updating.
The default value of type is ParticleUpdater.NONE.
config UPDATER Yes The available options of type are as follows:
1. ParticleUpdater.NONE: The property does not change. In this case, the config type is ParticleColorPropertyUpdaterConfigs[ParticleUpdater.NONE].
2. ParticleUpdater.RANDOM: The property changes randomly. In this case, the config type is ParticleColorPropertyUpdaterConfigs[ParticleUpdater.RANDOM].
3. ParticleUpdater.CURVE: The property changes with the animation curve. In this case, the config type is ParticleColorPropertyUpdaterConfigs[ParticleUpdater.CURVE].
NOTE
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.

ParticleColorOptions14+

interface ParticleColorOptions {
  r: ParticleTuple<number, number>;
  g: ParticleTuple<number, number>;
  b: ParticleTuple<number, number>;
  a: ParticleTuple<number, number>;
}

Defines 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.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Mandatory Description
r ParticleTuple Yes Difference value for the red color channel.
g ParticleTuple Yes Difference value for the green color channel.
b ParticleTuple Yes Difference value for the blue color channel.
a ParticleTuple Yes Difference value for the alpha (transparency) channel.

Example

Example 1: Initializing Particles with Circular Shapes

This example demonstrates the basic usage of particle animations by initializing particles with circular shapes.

// xxx.ets
@Entry
@Component
struct ParticleExample {
  build() {
    Stack() {
      Text()
        .width(300).height(300).backgroundColor(Color.Black)
      Particle({
        particles: [
          {
            emitter: {
              particle: {
                type: ParticleType.POINT, // Particle type.
                config: {
                  radius: 10// Point radius.
                },
                count: 500, // Total number of particles.
                lifetime: 10000, // Particle lifetime, in ms.
                lifetimeRange: 100// Range of particle lifetime values, in ms.
              },
              emitRate: 10, // Number of particles emitted per second.
              position: [0, 0],
              shape: ParticleEmitterShape.RECTANGLE// Emitter shape.
            },
            color: {
              range: [Color.Red, Color.Yellow], // Initial color range.
              updater: {
                type: ParticleUpdater.CURVE, // Change with the animation curve.
                config: [
                  {
                    from: Color.White, // Initial value of the change.
                    to: Color.Pink, // Target value of the change.
                    startMillis: 0, // Start time.
                    endMillis: 3000, // End time.
                    curve: Curve.EaseIn// Animation curve.
                  },
                  {
                    from: Color.Pink,
                    to: Color.Orange,
                    startMillis: 3000,
                    endMillis: 5000,
                    curve: Curve.EaseIn
                  },
                  {
                    from: Color.Orange,
                    to: Color.Pink,
                    startMillis: 5000,
                    endMillis: 8000,
                    curve: Curve.EaseIn
                  },
                ]
              }
            },
            opacity: {
              range: [0.0, 1.0], // The initial value of particle opacity is randomly generated from the [0.0, 1.0] range.
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0.0,
                    to: 1.0,
                    startMillis: 0,
                    endMillis: 3000,
                    curve: Curve.EaseIn
                  },
                  {
                    from: 1.0,
                    to: 0.0,
                    startMillis: 5000,
                    endMillis: 10000,
                    curve: Curve.EaseIn
                  }
                ]
              }
            },
            scale: {
              range: [0.0, 0.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0.0,
                    to: 0.5,
                    startMillis: 0,
                    endMillis: 3000,
                    curve: Curve.EaseIn
                  }
                ]
              }
            },
            acceleration: {
              // Acceleration. speed indicates the acceleration speed, and angle indicates the acceleration direction.
              speed: {
                range: [3, 9],
                updater: {
                  type: ParticleUpdater.RANDOM, // The speed changes randomly.
                  config: [1, 20]
                }
              },
              angle: {
                range: [90, 90]
              }
            }

          }
        ]
      }).width(300).height(300)
    }.width("100%").height("100%").align(Alignment.Center)
  }
}

particle

Example 2: Initializing Particles with Images

This example demonstrates the basic usage of particle animations by initializing particles with images.

@Entry
@Component
struct ParticleExample {
  @State
  myCount: number = 100
  flag: boolean = false;

  build() {
    Column() {
      Stack() {
        Particle({
          particles: [
            {
              emitter: {
                particle: {
                  type: ParticleType.IMAGE,
                  config: {
                    src: $r("app.media.book"),
                    size: [10, 10]
                  },
                  count: this.myCount,
                  lifetime: 10000,
                  lifetimeRange: 100
                },
                emitRate: 3,
                shape: ParticleEmitterShape.CIRCLE
              },
              color: {
                range: [Color.White, Color.White]
              },
              opacity: {
                range: [1.0, 1.0],
                updater: {
                  type: ParticleUpdater.CURVE,
                  config: [
                    {
                      from: 0,
                      to: 1.0,
                      startMillis: 0,
                      endMillis: 6000
                    },
                    {
                      from: 1.0,
                      to: .0,
                      startMillis: 6000,
                      endMillis: 10000
                    }
                  ]
                }
              },
              scale: {
                range: [0.1, 1.0],
                updater: {
                  type: ParticleUpdater.CURVE,
                  config: [
                    {
                      from: 0,
                      to: 1.5,
                      startMillis: 0,
                      endMillis: 8000,
                      curve: Curve.EaseIn
                    }

                  ]
                }
              },
              acceleration: {
                speed: {
                  range: [3, 9],
                  updater: {
                    type: ParticleUpdater.CURVE,
                    config: [
                      {
                        from: 10,
                        to: 20,
                        startMillis: 0,
                        endMillis: 3000,
                        curve: Curve.EaseIn
                      },
                      {
                        from: 10,
                        to: 2,
                        startMillis: 3000,
                        endMillis: 8000,
                        curve: Curve.EaseIn
                      }
                    ]
                  }
                },
                angle: {
                  range: [0, 180],
                  updater: {
                    type: ParticleUpdater.CURVE,
                    config: [{
                      from: 1,
                      to: 2,
                      startMillis: 0,
                      endMillis: 1000,
                      curve: Curve.EaseIn
                    },
                      {
                        from: 50,
                        to: -50,
                        startMillis: 1000,
                        endMillis: 3000,
                        curve: Curve.EaseIn
                      },
                      {
                        from: 3,
                        to: 5,
                        startMillis: 3000,
                        endMillis: 8000,
                        curve: Curve.EaseIn
                      }
                    ]
                  }
                }
              },
              spin: {
                range: [0.1, 1.0],
                updater: {
                  type: ParticleUpdater.CURVE,
                  config: [
                    {
                      from: 0,
                      to: 360,
                      startMillis: 0,
                      endMillis: 8000,
                      curve: Curve.EaseIn
                    }
                  ]
                }
              },
            }
            , {
            emitter: {
              particle: {
                type: ParticleType.IMAGE,
                config: {
                  src: $r('app.media.heart'),
                  size: [10, 10]
                },
                count: this.myCount,
                lifetime: 10000,
                lifetimeRange: 100
              },
              emitRate: 3,
              shape: ParticleEmitterShape.CIRCLE
            },
            color: {
              range: [Color.White, Color.White]
            },
            opacity: {
              range: [1.0, 1.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0,
                    to: 1.0,
                    startMillis: 0,
                    endMillis: 6000
                  },
                  {
                    from: 1.0,
                    to: .0,
                    startMillis: 6000,
                    endMillis: 10000
                  }
                ]
              }
            },
            scale: {
              range: [0.1, 1.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0,
                    to: 2.0,
                    startMillis: 0,
                    endMillis: 10000,
                    curve: Curve.EaseIn
                  }

                ]
              }
            },
            acceleration: {
              speed: {
                range: [3, 9],
                updater: {
                  type: ParticleUpdater.CURVE,
                  config: [
                    {
                      from: 10,
                      to: 20,
                      startMillis: 0,
                      endMillis: 3000,
                      curve: Curve.EaseIn
                    },
                    {
                      from: 10,
                      to: 2,
                      startMillis: 3000,
                      endMillis: 8000,
                      curve: Curve.EaseIn
                    }
                  ]
                }
              },
              angle: {
                range: [0, 180],
                updater: {
                  type: ParticleUpdater.CURVE,
                  config: [{
                    from: 1,
                    to: 2,
                    startMillis: 0,
                    endMillis: 1000,
                    curve: Curve.EaseIn
                  },
                    {
                      from: 50,
                      to: -50,
                      startMillis: 0,
                      endMillis: 3000,
                      curve: Curve.EaseIn
                    },
                    {
                      from: 3,
                      to: 5,
                      startMillis: 3000,
                      endMillis: 10000,
                      curve: Curve.EaseIn
                    }
                  ]
                }
              }
            },
            spin: {
              range: [0.1, 1.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0,
                    to: 360,
                    startMillis: 0,
                    endMillis: 10000,
                    curve: Curve.EaseIn
                  }
                ]
              }
            },
          }, {
            emitter: {
              particle: {
                type: ParticleType.IMAGE,
                config: {
                  src: $r('app.media.sun'),
                  size: [10, 10]
                },
                count: this.myCount,
                lifetime: 10000,
                lifetimeRange: 100
              },
              emitRate: 3,
              shape: ParticleEmitterShape.CIRCLE
            },
            color: {
              range: [Color.White, Color.White]
            },
            opacity: {
              range: [1.0, 1.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0,
                    to: 1.0,
                    startMillis: 0,
                    endMillis: 6000
                  },
                  {
                    from: 1.0,
                    to: .0,
                    startMillis: 6000,
                    endMillis: 10000
                  }
                ]
              }
            },
            scale: {
              range: [0.1, 1.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0,
                    to: 2.0,
                    startMillis: 0,
                    endMillis: 10000,
                    curve: Curve.EaseIn
                  }

                ]
              }
            },
            acceleration: {
              speed: {
                range: [3, 9],
                updater: {
                  type: ParticleUpdater.CURVE,
                  config: [
                    {
                      from: 10,
                      to: 20,
                      startMillis: 0,
                      endMillis: 3000,
                      curve: Curve.EaseIn
                    },
                    {
                      from: 10,
                      to: 2,
                      startMillis: 3000,
                      endMillis: 8000,
                      curve: Curve.EaseIn
                    }
                  ]
                }
              },
              angle: {
                range: [0, 180],
                updater: {
                  type: ParticleUpdater.CURVE,
                  config: [{
                    from: 1,
                    to: 2,
                    startMillis: 0,
                    endMillis: 1000,
                    curve: Curve.EaseIn
                  },
                    {
                      from: 50,
                      to: -50,
                      startMillis: 1000,
                      endMillis: 3000,
                      curve: Curve.EaseIn
                    },
                    {
                      from: 3,
                      to: 5,
                      startMillis: 3000,
                      endMillis: 8000,
                      curve: Curve.EaseIn
                    }
                  ]
                }
              }
            },
            spin: {
              range: [0.1, 1.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0,
                    to: 360,
                    startMillis: 0,
                    endMillis: 10000,
                    curve: Curve.EaseIn
                  }
                ]
              }
            },
          }
          ]
        }).width(300).height(300)

      }.width(500).height(500).align(Alignment.Center)
    }.width("100%").height("100%")

  }
}

particle

Example 3: Changing Motion Trajectories with the Particle Disturbance Field

This example demonstrates how to change the motion trajectories of particles by applying disturbances through the particle disturbance field.

@Entry
@Component
struct ParticleExample {
  build() {
    Stack() {
      Text()
        .width(300).height(300).backgroundColor(Color.Black)
      Particle({
        particles: [
          {
            emitter: {
              particle: {
                type: ParticleType.POINT, // Particle type.
                config: {
                  radius: 10// Point radius.
                },
                count: 500, // Total number of particles.
                lifetime: 10000// Particle lifetime, in ms.
              },
              emitRate: 10, // Number of particles emitted per second.
              position: [0, 0],
              shape: ParticleEmitterShape.RECTANGLE// Emitter shape.
            },
            color: {
              range: [Color.Red, Color.Yellow], // Initial color range.
              updater: {
                type: ParticleUpdater.CURVE, // Change with the animation curve.
                config: [
                  {
                    from: Color.White, // Initial value of the change.
                    to: Color.Pink, // Target value of the change.
                    startMillis: 0, // Start time.
                    endMillis: 3000, // End time.
                    curve: Curve.EaseIn// Animation curve.
                  },
                  {
                    from: Color.Pink,
                    to: Color.Orange,
                    startMillis: 3000,
                    endMillis: 5000,
                    curve: Curve.EaseIn
                  },
                  {
                    from: Color.Orange,
                    to: Color.Pink,
                    startMillis: 5000,
                    endMillis: 8000,
                    curve: Curve.EaseIn
                  },
                ]
              }
            },
            opacity: {
              range: [0.0, 1.0], // The initial value of particle opacity is randomly generated from the [0.0, 1.0] range.
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0.0,
                    to: 1.0,
                    startMillis: 0,
                    endMillis: 3000,
                    curve: Curve.EaseIn
                  },
                  {
                    from: 1.0,
                    to: 0.0,
                    startMillis: 5000,
                    endMillis: 10000,
                    curve: Curve.EaseIn
                  }
                ]
              }
            },
            scale: {
              range: [0.0, 0.0],
              updater: {
                type: ParticleUpdater.CURVE,
                config: [
                  {
                    from: 0.0,
                    to: 0.5,
                    startMillis: 0,
                    endMillis: 3000,
                    curve: Curve.EaseIn
                  }
                ]
              }
            },
            acceleration: {
              // Acceleration. speed indicates the acceleration speed, and angle indicates the acceleration direction.
              speed: {
                range: [3, 9],
                updater: {
                  type: ParticleUpdater.RANDOM,
                  config: [1, 20]
                }
              },
              angle: {
                range: [90, 90]
              }
            }

          }
        ]
      }).width(300).height(300).disturbanceFields([{
        strength: 10,
        shape: DisturbanceFieldShape.RECT,
        size: { width: 100, height: 100 },
        position: { x: 100, y: 100 },
        feather: 15,
        noiseScale: 10,
        noiseFrequency: 15,
        noiseAmplitude: 5
      }])
    }.width("100%").height("100%").align(Alignment.Center)
  }
}

particle

Example 4: Adjusting the Emitter Position

This example demonstrates how to adjust the position of the particle emitter through emitter().

@Entry
@Component
struct ParticleExample {
  @State emitterProperties: Array<EmitterProperty> = [
    {
      index: 0,
      emitRate: 100,
      position: { x: 60, y: 80 },
      size: { width: 200, height: 200 }
    }
  ]

  build() {
    Stack() {
      Text()
        .width(300).height(300).backgroundColor(Color.Black)
      Particle({
        particles: [
          {
            emitter: {
              particle: {
                type: ParticleType.POINT, // Particle type.
                config: {
                  radius: 5// Point radius.
                },
                count: 400, // Total number of particles.
                lifetime: -1// Particle lifetime. The value -1 indicates that the lifetime of the particle is infinite.
              },
              emitRate: 10, // Number of particles emitted per second.
              position: [0, 0], // Emitter position.
              shape: ParticleEmitterShape.CIRCLE// Emitter shape.
            },
            color: {
              range: [Color.Red, Color.Yellow], // Initial color range.
              updater: {
                type: ParticleUpdater.CURVE, // Change with the animation curve.
                config: [
                  {
                    from: Color.White,
                    to: Color.Pink,
                    startMillis: 0,
                    endMillis: 3000,
                    curve: Curve.EaseIn
                  },
                  {
                    from: Color.Pink,
                    to: Color.Orange,
                    startMillis: 3000,
                    endMillis: 5000,
                    curve: Curve.EaseIn
                  },
                  {
                    from: Color.Orange,
                    to: Color.Pink,
                    startMillis: 5000,
                    endMillis: 8000,
                    curve: Curve.EaseIn
                  },
                ]
              }
            },
          },
        ]
      })
        .width(300)
        .height(300)
        .emitter(this.emitterProperties)
    }.width("100%").height("100%").align(Alignment.Center)
  }
}

particle

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/wLMdGh
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录