鸿蒙API14开发【粒子动画 (Particle)】ArkTS组件

粒子动画是通过随机生成大量粒子运动形成的动画效果，支持圆点、图片等多种粒子类型。开发者可控制粒子在颜色、透明度、大小、速度等维度的动态变化，从而营造特殊场景氛围（如雪花飘落效果）。该功能由Particle组件实现，API版本从10开始支持，并逐步扩展了扰动场（12+）、发射器动态更新（12+）等特性。组件通过ParticleInterface接口配置粒子集合参数，支持原子化服务调用（11+）。主要

是秃子总会反光

902人浏览 · 2025-06-10 13:39:06

是秃子总会反光 · 2025-06-10 13:39:06 发布

粒子动画是在一定范围内随机生成的大量粒子产生运动而组成的动画。动画元素是一个个粒子，这些粒子可以是圆点、图片。通过对粒子在颜色、透明度、大小、速度、加速度、自旋角度等维度变化做动画，来营造一种氛围感，比如下雪的动效，雪花飘舞就相当于一个个雪花粒子在做动画。

粒子动画的效果通过Particle组件展现。

说明：

该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

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;
}
typescript

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

参数：

参数名	类型	必填	描述
particles	[Particles]< [PARTICLE], [COLOR_UPDATER], [OPACITY_UPDATER], [SCALE_UPDATER], [ACC_SPEED_UPDATER], [ACC_ANGLE_UPDATER], [SPIN_UPDATER] >	是	粒子动画的集合，详见[Particles]属性说明。

属性

除支持[通用属性]外还支持以下属性：

disturbanceFields12+

disturbanceFields(fields: Array)

设置扰动场。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
fields	Array<[DisturbanceFieldOptions]>	是	扰动场数组。

emitter12+

emitter(value: Array)

支持发射器位置动态更新

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Array<[EmitterProperty]>	是	需要更新的emitter参数数组

事件

支持[通用事件]

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>;
}
typescript

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
emitter	[EmitterOptions]<[PARTICLE]>	是	粒子发射器配置。
color	[ParticleColorPropertyOptions]<[COLOR_UPDATER]>	否	粒子颜色配置。说明：默认值：{ range:[Color.White,Color.White] } 。图片粒子不支持设置颜色。
opacity	[ParticlePropertyOptions]<number, [OPACITY_UPDATER]>	否	粒子透明度配置。默认值：{ range:[1.0,1.0] }
scale	[ParticlePropertyOptions]<number, [SCALE_UPDATER]>	否	粒子大小配置。默认值：{ range:[1.0,1.0] }
velocity	[VelocityOptions]	否	粒子速度配置。说明： speed表示速度大小。angle表示速度的方向（单位为角度），以元素几何中心为坐标原点，水平方向为X轴，正数表示顺时针方向旋转角度。默认值：{ speed:[0.0,0.0],angle:[0.0,0.0] }
acceleration	[AccelerationOptions]<[ACC_SPEED_UPDATER], [ACC_ANGLE_UPDATER]>	否	粒子加速度配置。说明： speed表示加速度大小，angle表示加速度方向（单位为角度）。默认值：{ speed:{range:[0.0,0.0]},angle:{range:[0.0,0.0]} }
spin	[ParticlePropertyOptions]<number, [SPIN_UPDATER]>	否	粒子自旋角度配置。默认值：{range:[0.0,0.0]} 方向：正数表示顺时针旋转，负数表示逆时针旋转。

EmitterOptions

粒子发射器的配置

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
particle	[EmitterParticleOptions]<[PARTICLE]>	是	粒子配置。 -type表示粒子类型，可以选择图片或者是点。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。 -config表示对应类型的配置。 -config类型和type值有关联： 1、如果type为ParticleType.POINT，则config类型为[PointParticleParameters] 。 2、如果type为ParticleType.IMAGE，则config类型为[ImageParticleParameters] 。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。 -count表示发射的粒子总数，count取值>=-1,当count为-1表示粒子总数无限大。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。 -lifetime表示单个粒子的生命周期，默认值1000（即1000ms，1s）,lifetime>=-1,当lifetime为-1表示粒子生命周期无限大。当lifetime<-1，取默认值。说明：如果不需要动画一直播放，建议不要将生命周期设置为-1，可能对性能造成较大影响。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。 -lifeTimeRange表示粒子生命周期取值范围，设置lifeTimeRange后粒子的生命周期为 [lifetime-lifeTimeRange,lifeTime+lifeTimeRange]中间的一个随机整数。lifeTimeRange 默认值为0，取值范围为为0到正无穷。设置为负值时取默认值。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
emitRate	number	否	发射器发射速率（即每秒发射粒子数）。默认值：5，小于0时取默认值5。emitRate值超过5000时会极大影响性能，建议设置参数小于5000。
shape	[ParticleEmitterShape]	否	发射器形状。默认值：ParticleEmitterShape.RECTANGLE。
position	[ParticleTuple]<[Dimension], [Dimension]>	否	发射器位置（距离组件左上角的位置。第一个参数为x方向上的相对偏移，第二个参数为y轴方向相对偏移。）默认值：`[0.0, 0.0]`。
size	[ParticleTuple]<[Dimension], [Dimension]>	否	发射窗口的大小。第一个参数为发射器宽，第二个参数为发射器高。默认值：`['100%','100%']`(即发射窗口占满Particle组件)。

ParticleConfigs

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
[ParticleType.POINT]	[PointParticleParameters]	是	点状粒子配置。
[ParticleType.IMAGE]	[ImageParticleParameters]	是	图片粒子配置。

PointParticleParameters

interface PointParticleParameters {
  radius: VP;
}
typescript

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
radius	[VP]	是	粒子半径。

ImageParticleParameters

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
src	[ResourceStr]	是	图片路径。暂不支持svg图片类型。
size	[ParticleTuple]<[Dimension], [Dimension]>	是	图像尺寸。
objectFit	[ImageFit]	否	图片显示模式。

ParticleColorPropertyOptions

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
range	[ParticleTuple]<[ResourceColor], [ResourceColor]>	是	粒子初始颜色区间，粒子发射器生成粒子的初始颜色在range区间随机取值。默认值：range:[Color.White,Color.White]
distributionType12+	[DistributionType]	否	粒子初始颜色随机值分布，允许用户选择颜色随机值生成的分布类型，支持均匀分布或正态（高斯）分布。默认值：DistributionType.UNIFORM 原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
updater	[ParticleColorUpdaterOptions]<[UPDATER]>	否	颜色属性变化配置。颜色属性变化类型type有三类： 1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticleColorPropertyUpdaterConfigs][ParticleUpdater.NONE]。 2、type为ParticleUpdater.RANDOM，表示随机变化，则config类型为[ParticleColorPropertyUpdaterConfigs][ParticleUpdater.RANDOM]。 3、type为ParticleUpdater.CURVE,表示按动画曲线变化，则config类型为[ParticleColorPropertyUpdaterConfigs][ParticleUpdater.CURVE]。默认值：type默认为 ParticleUpdater.NONE。说明：当type为ParticleUpdater.RANDOM或者ParticleUpdater.CURVE时，updater中颜色配置的优先级高于range中的颜色配置。在updater配置的动画时间周期内，以updater中的颜色配置来变化；在updater配置的动画时间周期外，以range中的颜色配置来变化。

ParticleColorPropertyUpdaterConfigs

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
[ParticleUpdater.NONE]	void	是	无变化。
[ParticleUpdater.RANDOM]	[ParticleColorOptions]	是	表示变化方式为均匀变化的时候，在区间内随机生成一个差值。r、g、b、a四个颜色通道每秒分别使用差值叠加当前颜色值，生成目标颜色值。实现颜色随机变化的效果。
[ParticleUpdater.CURVE]	Array<[ParticlePropertyAnimation]<[ResourceColor]>>	是	表示变化方式为曲线变化时，颜色变化的配置。数组类型表示当前属性可以设置多段动画，如0ms-3000ms，3000ms-5000ms，5000ms-8000ms分别设置动画。

ParticlePropertyOptions

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
range	[ParticleTuple]<[TYPE], [TYPE]>	是	粒子初始属性值区间，粒子发射器生成粒子的属性值在range区间随机取值。说明各项属性的非法输入取默认值，当最大值小于最小值的时候取默认区间。TYPE为number。不同属性的默认值不同： 1、opacity属性：range:[1.0,1.0]，取值范围为[0, 1]，默认值为1.0。 2、scale属性：range:[1.0,1.0]，取值范围为[0, 10000]，默认值为1.0。 3、acceleration加速度speed属性：range:[0.0,0.0]，取值范围为[0, 10000]，默认值为0.0。 4、acceleration加速度angle属性：range:[0.0,0.0]，取值范围为[-10000, 10000]，默认值为0.0。 5、spin属性：range:[0.0,0.0]，取值范围为[-10000, 10000]，默认值为0.0。
updater	[ParticleUpdaterOptions]<[TYPE], [UPDATER]>	否	属性变化配置。属性变化类型type有三类： 1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticlePropertyUpdaterConfigs][ParticleUpdater.NONE]。 2、当type为ParticleUpdater.RANDOM，表示变化类型为随机变化，则config类型为[ParticlePropertyUpdaterConfigs][ParticleUpdater.RANDOM]。 3、当type为ParticleUpdater.CURVE，表示变化类型为曲线变化，则config类型为[ParticlePropertyUpdaterConfigs][ParticleUpdater.CURVE] 默认值：type默认为ParticleUpdater.NONE。

ParticlePropertyUpdaterConfigs

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
[[ParticleUpdater.NONE]	void	是	无变化。
[ParticleUpdater.RANDOM]	[ParticleTuple]<T, T>	是	表示变化方式为匀速变化时，每秒的变化差值为设置区间随机生成的值。目标属性值为当前属性值叠加变化差值。如当前属性值为0.2，config取[0.1,1.0]: 1、如果变化差值在区间[0.1,1.0]取随机值0.5，则目标属性值为0.2+0.5 = 0.7； 2、变化差值也可以取负值。如当前属性值为0.2，config为 [-3.0,2.0],如果变化差值在区间[-3.0,2.0]取随机值-2.0，则目标属性值为0.2-2.0 = -1.8。说明： config配置的是变化差值的取值范围，差值的最大最小值没有约束。但是如果当前属性值叠加差值大于属性最大值，目标属性值取属性最大值；如果当前属性值叠加差值小于属性最小值，目标属性值取属性最小值。T为number。例如：opacity的取值范围[0.0,1.0]则当当前属性值叠加差值超过1.0，则取1.0。
[ParticleUpdater.CURVE]	Array<[ParticlePropertyAnimation]>	是	表示变化方式为曲线变化时，属性变化的配置。数组类型表示当前属性可以设置多段动画，如0ms-3000ms，3000ms-5000ms，5000ms-8000ms分别设置动画。T为number。

ParticlePropertyAnimation

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
from	T	是	属性起始值。非法输入取对应属性的默认值。
to	T	是	属性目标值。非法输入取对应属性的默认值。
startMillis	number	是	动画开始时间。单位：毫秒。取值范围：[0, +∞)。
endMillis	number	是	动画结束时间。单位：毫秒。取值范围：[0, +∞)。
curve	[Curve]	[ICurve]	否

ParticleType

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	描述
POINT	点状粒子
IMAGE	图片粒子

ParticleEmitterShape

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	描述
RECTANGLE	粒子发射器为矩形
CIRCLE	粒子发射器为圆形
ELLIPSE	粒子发射器为椭圆形

DistributionType12+

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

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	描述
UNIFORM	初始颜色随机值分布为均匀分布。
GAUSSIAN	初始颜色随机值分布为高斯分布。

ParticleUpdater

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

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	描述
NONE	无变化
RANDOM	随机变化
CURVE	动画曲线变化

DisturbanceFieldOptions12+

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
strength	number	否	场强，表示场从中心向外的排斥力的强度，默认值0。正数表示排斥力方向朝外，负数表示吸引力，方向朝内。取值范围：(-∞, +∞)。
shape	[DisturbanceFieldShape]	否	场的形状。默认为DisturbanceFieldShape.RECT。
size	[SizeT]	否	场的大小。默认值 {width:0，height:0}。 width和height的取值范围：[0, +∞)。
position	[PositionT]	否	场的位置。默认值{x:0，y:0}。 x、y的取值范围：(-∞, +∞)。
feather	number	否	羽化值，表示场从中心点到场边缘的衰减程度，取值范围0到100的整数，如果0则表示场是一个刚体，所有范围内的粒子都被排斥在外。羽化值越大场的缓和程度越大，场范围内出现越多靠近中心点的粒子。默认值为0。
noiseScale	number	否	噪声尺度，用于控制噪声图案的整体大小，取值大于等于0。默认值1。
noiseFrequency	number	否	噪声频率，频率越大噪声越细腻，取值大于等于0。默认值1。
noiseAmplitude	number	否	噪声震幅，噪声的波动的范围，震幅越大噪音之间差异越大。取值大于等于0。默认值1。

DisturbanceFieldShape12+

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	描述
RECT	长方形。
CIRCLE	圆。
ELLIPSE	椭圆。

EmitterProperty12+

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
index	number	是	索引，取整，按初始化参数中发射器的数组索引指定对应的发射器。异常默认值为0。
emitRate	number	否	发射器发射速率，即每秒发射粒子的数量。未传入时保持其当前的发射速率，传入值小于0时取默认值5。emitRate值超过5000时会极大影响性能，建议设置参数小于5000。
position	[PositionT]	否	发射器位置的数组，只支持number类型。未传入时保持其当前的发射器位置。需传入两个有效参数，若其中一个为异常值，则position不生效。 x、y的取值范围：(-∞, +∞)。
size	[SizeT]	否	发射窗口的大小，只支持number类型。未传入时保持其当前发射窗口大小。需传入两个有效参数且都大于0，若其中一个为异常值，则size不生效。

ParticleTuple14+

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

粒子元组，表示定义一些动画参数的类型。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

类型	说明
[T1, T2]	一些动画参数的类型，可能是任何类型。

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
    >
  >;
}
typescript

粒子动画的集合。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
particles	Array< ParticleOptions< PARTICLE, COLOR_UPDATER, OPACITY_UPDATER, SCALE_UPDATER, ACC_SPEED_UPDATER, ACC_ANGLE_UPDATER, SPIN_UPDATER > >	是	粒子动画的集合。每一个的粒子动画（[ParticleOptions]）包含粒子发射，同时可配置粒子的颜色、透明度、大小、速度、加速度与旋转速度，旋转速度，详见[ParticleOptions]属性说明。

VelocityOptions14+

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

粒子速度配置。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
speed	[ParticleTuple]<number, number>	是	表示速度大小。默认值：{range:[0.0,0.0]}
angle	[ParticleTuple]<number, number>	是	表示速度的方向（单位为角度）。以元素几何中心为坐标原点，水平方向为X轴，正数表示顺时针方向旋转角度。默认值：{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>;
}
typescript

粒子加速度配置。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
speed	[ParticlePropertyOptions]<number, [ACC_SPEED_UPDATER]>	否	表示加速度大小。默认值：{range:[0.0,0.0]}
angle	[ParticlePropertyOptions]<number, [ACC_SPEED_UPDATER]>	否	表示加速度方向（单位为角度）。默认值：{range:[0.0,0.0]}

EmitterParticleOptions14+

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

粒子配置。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
type	[PARTICLE]	是	表示粒子类型，可以选择图片或者是点。
config	[ParticleConfigs][PARTICLE]	是	表示对应类型的配置。 config类型和type值有关联： 1、如果type为ParticleType.POINT，则config类型为[PointParticleParameters] 。 2、如果type为ParticleType.IMAGE，则config类型为[ImageParticleParameters]。
count	number	是	表示发射的粒子总数，count取值>=-1,当count为-1表示粒子总数无限大。
lifetime	number	否	表示单个粒子的生命周期，默认值1000（即1000ms，1s），lifetime>=-1。当lifetime为-1表示粒子生命周期无限大。当lifetime<-1，取默认值。说明：如果不需要动画一直播放，建议不要将生命周期设置为-1，可能对性能造成较大影响。
lifeTimeRange	number	否	表示粒子生命周期取值范围，设置lifeTimeRange后粒子的生命周期为 [lifetime-lifeTimeRange,lifeTime+lifeTimeRange]中间的一个随机整数。lifeTimeRange 默认值为0，取值范围为为0到正无穷。设置为负值时取默认值。

ParticleUpdaterOptions14+

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

颜色属性变化配置。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
type	[UPDATER]	是	表示颜色属性变化类型。默认值：type默认为ParticleUpdater.NONE。
config	[UPDATER]	是	属性变化配置。属性变化类型type有三类： 1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticlePropertyUpdaterConfigs][ParticleUpdater.NONE]。 2、当type为ParticleUpdater.RANDOM，表示变化类型为随机变化，则config类型为[ParticlePropertyUpdaterConfigs][ParticleUpdater.RANDOM]。 3、当type为ParticleUpdater.CURVE，表示变化类型为曲线变化，则config类型为[ParticlePropertyUpdaterConfigs][ParticleUpdater.CURVE]。

4)ParticleColorUpdaterOptions14+

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

颜色属性变化配置。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
type	[UPDATER]	是	表示颜色属性变化类型。默认值：type默认为 ParticleUpdater.NONE。
config	[UPDATER]	是	颜色属性变化类型type有三类： 1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticleColorPropertyUpdaterConfigs][ParticleUpdater.NONE]。 2、type为ParticleUpdater.RANDOM，表示随机变化，则config类型为[ParticleColorPropertyUpdaterConfigs][ParticleUpdater.RANDOM]。 3、type为ParticleUpdater.CURVE,表示按动画曲线变化，则config类型为[ParticleColorPropertyUpdaterConfigs][ParticleUpdater.CURVE]。说明：当type为ParticleUpdater.RANDOM或者ParticleUpdater.CURVE时，updater中颜色配置的优先级高于range中的颜色配置。在updater配置的动画时间周期内，以updater中的颜色配置来变化；在updater配置的动画时间周期外，以range中的颜色配置来变化。

ParticleColorOptions14+

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

颜色变化方式为均匀变化的时候，在区间内随机生成一个差值。r、g、b、a四个颜色通道每秒分别使用差值叠加当前颜色值，生成目标颜色值。实现颜色随机变化的效果。

原子化服务API： 从API version 14开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
r	[ParticleTuple]<number, number>	是	r颜色通道的差值。
g	[ParticleTuple]<number, number>	是	g颜色通道的差值。
b	[ParticleTuple]<number, number>	是	b颜色通道的差值。
a	[ParticleTuple]<number, number>	是	a颜色通道的差值。

示例

示例1（圆形初始化粒子）

描述粒子动画基础用法，通过圆形初始化粒子。

// xxx.ets
@Entry
@Component
struct ParticleExample {
  build() {
    Stack() {
      Text()
        .width(300).height(300).backgroundColor(Color.Black)
      Particle({
        particles: [
          {
            emitter: {
              particle: {
                type: ParticleType.POINT, //粒子类型
                config: {
                  radius: 10//圆点半径
                },
                count: 500, //粒子总数
                lifetime: 10000, //粒子生命周期，单位ms
                lifetimeRange: 100//粒子生命周期取值范围，单位ms
              },
              emitRate: 10, //每秒发射粒子数
              position: [0, 0],
              shape: ParticleEmitterShape.RECTANGLE//发射器形状
            },
            color: {
              range: [Color.Red, Color.Yellow], //初始颜色范围
              updater: {
                type: ParticleUpdater.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
                  },
                ]
              }
            },
            opacity: {
              range: [0.0, 1.0], //粒子透明度的初始值从【0.0到1.0】随机产生
              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: {
              //加速度的配置，从大小和方向两个维度变化，speed表示加速度大小，angle表示加速度方向
              speed: {
                range: [3, 9],
                updater: {
                  type: ParticleUpdater.RANDOM, //Speed的变化方式是随机变化
                  config: [1, 20]
                }
              },
              angle: {
                range: [90, 90]
              }
            }

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

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例2（图片初始化粒子）

描述粒子动画基础用法，通过图片初始化粒子。

@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%")

  }
}
ts

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例3（粒子扰动场的干扰下运动轨迹发生变化）

该示例主要演示如何通过粒子扰动场的干扰下来实现运动轨迹发生变化的效果。

@Entry
@Component
struct ParticleExample {
  build() {
    Stack() {
      Text()
        .width(300).height(300).backgroundColor(Color.Black)
      Particle({
        particles: [
          {
            emitter: {
              particle: {
                type: ParticleType.POINT, //粒子类型
                config: {
                  radius: 10//圆点半径
                },
                count: 500, //粒子总数
                lifetime: 10000//粒子生命周期，单位ms
              },
              emitRate: 10, //每秒发射粒子数
              position: [0, 0],
              shape: ParticleEmitterShape.RECTANGLE//发射器形状
            },
            color: {
              range: [Color.Red, Color.Yellow], //初始颜色范围
              updater: {
                type: ParticleUpdater.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
                  },
                ]
              }
            },
            opacity: {
              range: [0.0, 1.0], //粒子透明度的初始值从[0.0,1.0]随机产生
              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: {
              //加速度的配置，从大小和方向两个维度变化，speed表示加速度大小，angle表示加速度方向
              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)
  }
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

示例4（调整粒子发射器位置）

通过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, // 粒子类型
                config: {
                  radius: 5// 圆点半径
                },
                count: 400, // 粒子总数
                lifetime: -1// 粒子的生命周期，-1表示粒子生命周期无限大
              },
              emitRate: 10, // 每秒发射粒子数
              position: [0, 0], // 粒子发射位置
              shape: ParticleEmitterShape.CIRCLE// 发射器形状
            },
            color: {
              range: [Color.Red, Color.Yellow], // 初始颜色范围
              updater: {
                type: ParticleUpdater.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)
  }
}
ts

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

在这里插入图片描述

HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

鸿蒙AI智能问答，助力开发者高效开发

传统开发模式中，开发者需在官网文档、论坛帖子、API参考间反复切换，频繁查阅文档，导致效率低下。在此背景下，华为在6月21日举办的2025开发者大会（HDC 2025）上正式上线了AI智能问答，以自然语言对话为核心交互方式，构建权威、实时、精准的鸿蒙开发知识中枢，重新定义开发者的问题解决范式。鸿蒙AI智能问答不仅是工具的革新，更是连接开发者与鸿蒙技术体系的智能桥梁。立即对话，让开发更简单！依托盘古

HarmonyOS开发者社区

轻松投，丝滑播——鸿蒙投播重塑跨屏观影体验

在长视频领域，如咪咕视频、腾讯视频、bilibili等，集成全局投播组件，用户可在应用内或播控中心直接调用投屏服务，提升大屏观影体验。在移动视频内容爆炸式增长的今天，如何将掌中的方寸精彩无损地放大至更广阔的视听空间，成为了提升用户沉浸感的关键，而投播技术（即手机视频投送至电视/电脑播放）则成为了优化居家观影娱乐体验的核心解决方案。Cast Engine是华为提供以手机为中心的大小屏协同能力，通过集

HarmonyOS开发者社区

使用“一次开发，多端部署”，实现Pura X阔折叠的全新设计

一多专区聚焦“一次开发，多端部署”，通过“多设备界面开发”和“多设备功能开发”两大板块，帮助开发者高效解决跨设备适配问题。最佳实践已上线华为HarmonyOS开发者官网，开发者可进入“HarmonyOS开发者官网”搜索《Pura X外屏开发实践》快速获取技术文档、示例代码及实战案例，快速打造优质的HarmonyOS一多应用。目前，小红书、蜻蜓FM等应用已依据HarmonyOS开发者官网一多专区及设