1# 粒子动画 (Particle) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @CCFFWW--> 5<!--Designer: @yangfan229--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9粒子动画是在一定范围内随机生成的大量粒子产生运动而组成的动画。动画元素是一个个粒子，这些粒子可以是圆点、图片。通过对粒子在颜色、透明度、大小、速度、加速度、自旋角度等维度变化做动画，来营造一种氛围感，比如下雪的动效，雪花飘舞就相当于一个个雪花粒子在做动画。 10 11粒子动画的效果通过Particle组件展现。 12 13 14> **说明：** 15> 16> 该组件从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 17> 18> Particle在息屏之后再次打开或者切换后台再次唤起，粒子动画会自动暂停。 19 20 21## 子组件 22 23无 24 25 26## 接口 27 28```typescript 29interface ParticleInterface { 30 < 31 PARTICLE extends ParticleType, 32 COLOR_UPDATER extends ParticleUpdater, 33 OPACITY_UPDATER extends ParticleUpdater, 34 SCALE_UPDATER extends ParticleUpdater, 35 ACC_SPEED_UPDATER extends ParticleUpdater, 36 ACC_ANGLE_UPDATER extends ParticleUpdater, 37 SPIN_UPDATER extends ParticleUpdater 38 >(particles: Particles< 39 PARTICLE, 40 COLOR_UPDATER, 41 OPACITY_UPDATER, 42 SCALE_UPDATER, 43 ACC_SPEED_UPDATER, 44 ACC_ANGLE_UPDATER, 45 SPIN_UPDATER 46 >): ParticleAttribute; 47} 48``` 49 50**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 51 52**系统能力：** SystemCapability.ArkUI.ArkUI.Full 53 54**参数：** 55 56| 名称 | 类型 | 只读 | 可选 | 说明 | 57| -------- | -------- | ---- | ---- | -------- | 58| particles | [Particles](#particles18)<<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/> | 否 | 否 | 粒子动画的集合，详见[Particles](#particles18)属性说明。 | 59 60## 属性 61 62除支持[通用属性](ts-component-general-attributes.md)外还支持以下属性： 63 64### disturbanceFields<sup>12+</sup> 65 66disturbanceFields(fields: Array<DisturbanceFieldOptions>) 67 68设置扰动场。 69 70**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 71 72**系统能力：** SystemCapability.ArkUI.ArkUI.Full 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| ------ | ------- | ---- | ---------------------------- | 78| fields | Array<[DisturbanceFieldOptions](#disturbancefieldoptions12)> | 是 | 扰动场数组。 | 79 80### emitter<sup>12+</sup> 81emitter(value: Array<EmitterProperty>) 82 83支持发射器位置动态更新 84 85**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 86 87**系统能力：** SystemCapability.ArkUI.ArkUI.Full 88 89**参数：** 90 91| 参数名 | 类型 | 必填 | 说明 | 92| ------ | ------- | ---- | ---------------------------- | 93| value | Array<[EmitterProperty](#emitterproperty12)> | 是 | 需要更新的emitter参数数组 | 94 95## 事件 96支持[通用事件](ts-component-general-events.md) 97 98## ParticleOptions 99 100```typescript 101interface ParticleOptions< 102 PARTICLE extends ParticleType, 103 COLOR_UPDATER extends ParticleUpdater, 104 OPACITY_UPDATER extends ParticleUpdater, 105 SCALE_UPDATER extends ParticleUpdater, 106 ACC_SPEED_UPDATER extends ParticleUpdater, 107 ACC_ANGLE_UPDATER extends ParticleUpdater, 108 SPIN_UPDATER extends ParticleUpdater 109> { 110 emitter: EmitterOptions<PARTICLE>; 111 color?: ParticleColorPropertyOptions<COLOR_UPDATER>; 112 opacity?: ParticlePropertyOptions<number, OPACITY_UPDATER>; 113 scale?: ParticlePropertyOptions<number, SCALE_UPDATER>; 114 velocity?: VelocityOptions; 115 acceleration?: AccelerationOptions<ACC_SPEED_UPDATER, ACC_ANGLE_UPDATER>; 116 spin?: ParticlePropertyOptions<number, SPIN_UPDATER>; 117} 118``` 119 120设置粒子参数。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126| 名称 | 类型 | 只读 | 可选 | 说明 | 127| -------- | -------- | ---- | ---- | -------- | 128| emitter | [EmitterOptions](#emitteroptions)<[PARTICLE](#particletype)> | 否 | 否 | 粒子发射器配置。 | 129| color | [ParticleColorPropertyOptions](#particlecolorpropertyoptions)<[COLOR_UPDATER](#particleupdater)> | 否 | 是 | 粒子颜色配置。<br/>**说明**：<br/>默认值：{ range:[Color.White,Color.White] } 。图片粒子不支持设置颜色。| 130| opacity | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [OPACITY_UPDATER](#particleupdater)> | 否 | 是 | 粒子透明度配置。<br/>默认值：{ range:[1.0,1.0] } | 131| scale | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [SCALE_UPDATER](#particleupdater)> | 否 | 是 | 粒子大小配置。<br/>默认值：{ range:[1.0,1.0] } | 132| velocity | [VelocityOptions](#velocityoptions18) |否 | 是 | 粒子速度配置。<br/>**说明**：<br/>speed表示速度大小。angle表示速度的方向（单位为角度），以元素几何中心为坐标原点，水平方向为X轴，正数表示顺时针方向旋转角度。<br/>默认值：{ speed:[0.0,0.0],angle:[0.0,0.0] } | 133| acceleration | [AccelerationOptions](#accelerationoptions18)<[ACC_SPEED_UPDATER](#particleupdater), [ACC_ANGLE_UPDATER](#particleupdater)> | 否 | 是 | 粒子加速度配置。 <br/>**说明**：<br/>speed表示加速度大小，angle表示加速度方向（单位为角度）。<br/>默认值：{ speed:{range:[0.0,0.0]},angle:{range:[0.0,0.0]} } | 134| spin | [ParticlePropertyOptions](#particlepropertyoptions)<number, [SPIN_UPDATER](#particleupdater)> | 否 | 是 | 粒子自旋角度配置。 <br/>默认值：{range:[0.0,0.0]}<br/>方向：正数表示顺时针旋转，负数表示逆时针旋转。 | 135 136 137## EmitterOptions 138粒子发射器的配置 139 140```typescript 141interface EmitterOptions<PARTICLE extends ParticleType> { 142 particle: EmitterParticleOptions<PARTICLE>; 143 emitRate?: number; 144 shape?: ParticleEmitterShape; 145 position?: ParticleTuple<Dimension, Dimension>; 146 size?: ParticleTuple<Dimension, Dimension>; 147 annulusRegion?: ParticleAnnulusRegion; 148} 149``` 150 151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 152 153| 名称 | 类型 | 只读 | 可选 | 说明 | 154| -------- | -------- | ---- | ---- | -------- | 155| particle | [EmitterParticleOptions](#emitterparticleoptions18)<[PARTICLE](#particletype)> | 否 | 否 | 粒子配置。<br>-type表示粒子类型，可以选择图片或者是点。<br>-config表示对应类型的配置。<br>-config类型和type值有关联：<br>1、如果type为ParticleType.POINT，则config类型为[PointParticleParameters](#pointparticleparameters) 。<br>2、如果type为ParticleType.IMAGE，则config类型为[ImageParticleParameters](#imageparticleparameters) 。<br>-count表示发射的粒子总数，count取值>=-1,当count为-1表示粒子总数无限大。<br>-lifetime表示单个粒子的生命周期，默认值1000（即1000ms，1s）,lifetime>=-1,当lifetime为-1表示粒子生命周期无限大。当lifetime<-1，取默认值。<br/>**说明：**如果不需要动画一直播放，建议不要将生命周期设置为-1，可能对性能造成较大影响。<br>-lifeTimeRange表示粒子生命周期取值范围，设置lifeTimeRange后粒子的生命周期为 [lifetime-lifeTimeRange,lifeTime+lifeTimeRange]中间的一个随机整数。lifeTimeRange 默认值为0，取值范围为0到正无穷。设置为负值时取默认值。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 156| emitRate | number | 否 | 是 | 发射器发射速率（即每秒发射粒子数）。 默认值：5，小于0时取默认值5。emitRate值超过5000时会极大影响性能，建议设置参数小于5000。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 157| shape | [ParticleEmitterShape](#particleemittershape) | 否 | 是 | 发射器形状。默认值：ParticleEmitterShape.RECTANGLE。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 158| position | [ParticleTuple](#particletuple18)<[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)> | 否 | 是 | 发射器位置（距离组件左上角的位置。第一个参数为x方向上的相对偏移，第二个参数为y轴方向相对偏移。） <br>默认值：`[0.0, 0.0]`。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 159| size | [ParticleTuple](#particletuple18)<[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)> |否 | 是 | 发射窗口的大小。第一个参数为发射器宽，第二个参数为发射器高。<br>默认值：`['100%','100%']`(即发射窗口占满Particle组件)。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 160| annulusRegion<sup>20+</sup> | [ParticleAnnulusRegion](ts-particle-animation.md#particleannulusregion20)| 否 | 是 |环形发射器参数。需要发射器形状为环形（即shape参数为ParticleEmitterShape.ANNULUS）时才生效，且对于环形发射器，形状信息必须通过annulusRegion参数指定，position和size不生效。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 161 162## ParticleConfigs 163 164设置粒子配置项。 165 166**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 167 168**系统能力：** SystemCapability.ArkUI.ArkUI.Full 169 170| 名称 | 类型 | 只读 | 可选 | 说明 | 171| -------- | -------- | ------ | -------- | -------- | 172| [ParticleType.POINT] | [PointParticleParameters](#pointparticleparameters) | 否 | 否 | 点状粒子配置。 | 173| [ParticleType.IMAGE] | [ImageParticleParameters](#imageparticleparameters) | 否 | 否 | 图片粒子配置。 | 174 175## PointParticleParameters 176 177设置粒子半径。 178 179**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 180 181**系统能力：** SystemCapability.ArkUI.ArkUI.Full 182 183| 名称 | 类型 | 只读 | 可选 | 说明 | 184| -------- | ------- | ------- | -------- | -------- | 185| radius | [VP](ts-types.md#vp10)| 否 | 否 | 粒子半径。 | 186 187## ImageParticleParameters 188 189设置图片选项。 190 191**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 192 193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 194 195| 名称 | 类型 | 只读 | 可选 | 说明 | 196| -------- | ------- | ------- | -------- | -------- | 197| src | [ResourceStr](ts-types.md#resourcestr) | 否 | 否 | 图片路径，支持本地图片和网络图片，引用方式请参考[加载图片资源](../../../ui/arkts-graphics-display.md#加载图片资源)。<br/>暂不支持svg图片类型。<br>src未发生变化时，会优先使用缓存的资源，无法动态切换资源。如需动态切换资源建议切换为不同的src。 | 198| size | [ParticleTuple](#particletuple18)<[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)> | 否 | 否 | 图像尺寸。 | 199| objectFit| [ImageFit](ts-appendix-enums.md#imagefit)| 否 | 是 | 图片显示模式。 | 200 201## ParticleColorPropertyOptions 202 203```typescript 204interface ParticleColorPropertyOptions<UPDATER extends ParticleUpdater> { 205 range: ParticleTuple<ResourceColor, ResourceColor>; 206 distributionType?: DistributionType; 207 updater?: ParticleColorUpdaterOptions<UPDATER>; 208} 209``` 210 211设置粒子颜色属性更新器配置。 212 213**系统能力：** SystemCapability.ArkUI.ArkUI.Full 214 215| 名称 | 类型 | 只读 | 可选 | 说明 | 216| -------- | -------- | ---- | ---- | -------- | 217| range | [ParticleTuple](#particletuple18)<[ResourceColor](ts-types.md#resourcecolor), [ResourceColor](ts-types.md#resourcecolor)> | 否 | 否 | 粒子初始颜色区间，粒子发射器生成粒子的初始颜色在range区间随机取值。<br>默认值：range:[Color.White,Color.White] <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 218| distributionType<sup>12+<sup> | [DistributionType](#distributiontype12) | 否 | 是 | 粒子初始颜色随机值分布，允许用户选择颜色随机值生成的分布类型，支持均匀分布或正态（高斯）分布。<br>默认值：DistributionType.UNIFORM<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 219| updater | [ParticleColorUpdaterOptions](#particlecolorupdateroptions18)<[UPDATER](#particleupdater)> | 否 | 是 | 颜色属性变化配置。颜色属性变化类型type有三类：<br>1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.NONE]。 <br>2、type为ParticleUpdater.RANDOM，表示随机变化，则config类型为[ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.RANDOM]。 <br>3、type为ParticleUpdater.CURVE,表示按动画曲线变化，则config类型为[ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.CURVE]。<br>默认值：type默认为 ParticleUpdater.NONE。 <br>**说明**：<br>当type为ParticleUpdater.RANDOM或者ParticleUpdater.CURVE时，updater中颜色配置的优先级高于range中的颜色配置。在updater配置的动画时间周期内，以updater中的颜色配置来变化；在updater配置的动画时间周期外，以range中的颜色配置来变化。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 220 221 222## ParticleColorPropertyUpdaterConfigs 223 224设置粒子颜色属性更新器的配置。 225 226**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 227 228**系统能力：** SystemCapability.ArkUI.ArkUI.Full 229 230| 名称 | 类型 | 只读 | 可选 | 说明 | 231| -------- | -------- | ---- | ---- | -------- | 232|[ParticleUpdater.NONE]|void | 否 | 否 | 无变化。| 233| [ParticleUpdater.RANDOM] | [ParticleColorOptions](#particlecoloroptions18) | 否 | 否 | 表示变化方式为均匀变化的时候，在区间内随机生成一个差值。r、g、b、a四个颜色通道每秒分别使用差值叠加当前颜色值，生成目标颜色值。实现颜色随机变化的效果。 | 234[ParticleUpdater.CURVE]|Array<[ParticlePropertyAnimation](#particlepropertyanimation)\<[ResourceColor](ts-types.md#resourcecolor)\>> | 否 | 否 | 表示变化方式为曲线变化时，颜色变化的配置。数组类型表示当前属性可以设置多段动画，如0ms-3000ms，3000ms-5000ms，5000ms-8000ms分别设置动画。| 235 236## ParticlePropertyOptions 237```typescript 238interface ParticlePropertyOptions<TYPE, UPDATER extends ParticleUpdater> { 239 range: ParticleTuple<TYPE, TYPE>; 240 updater?: ParticleUpdaterOptions<TYPE, UPDATER>; 241} 242``` 243 244设置粒子属性选项。 245 246**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 247 248**系统能力：** SystemCapability.ArkUI.ArkUI.Full 249 250| 名称 | 类型 | 只读 | 可选 | 说明 | 251| -------- | -------- | ---- | ---- | -------- | 252| range | [ParticleTuple](#particletuple18)<[TYPE](#particleupdater), [TYPE](#particleupdater)> | 否 | 否 | 粒子初始属性值区间，粒子发射器生成粒子的属性值在range区间随机取值。<br/>**说明**<br/>各项属性的非法输入取默认值，当最大值小于最小值的时候取默认区间。TYPE为number。<br/>不同属性的默认值不同：<br>1、opacity属性：range:[1.0,1.0]，取值范围为[0, 1]，默认值为1.0。<br/>2、scale属性：range:[1.0,1.0]，取值范围为[0, 10000]，默认值为1.0。<br/>3、acceleration加速度speed属性：range:[0.0,0.0]，取值范围为[0, 10000]，默认值为0.0。<br/>4、acceleration加速度angle属性：range:[0.0,0.0]，取值范围为[-10000, 10000]，默认值为0.0。<br/>5、spin属性：range:[0.0,0.0]，取值范围为[-10000, 10000]，默认值为0.0。 253| updater | [ParticleUpdaterOptions](#particleupdateroptions18)<[TYPE](#particleupdater), [UPDATER](#particleupdater)> | 否 | 是 | 属性变化配置。属性变化类型type有三类：<br/>1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.NONE]。<br>2、当type为ParticleUpdater.RANDOM，表示变化类型为随机变化，则config类型为[ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.RANDOM]。<br>3、当type为ParticleUpdater.CURVE，表示变化类型为曲线变化，则config类型为[ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.CURVE] <br>默认值：type默认为ParticleUpdater.NONE。 | 254 255 256## ParticlePropertyUpdaterConfigs 257```typescript 258interface ParticlePropertyUpdaterConfigs<T> { 259 [ParticleUpdater.NONE]: void; 260 [ParticleUpdater.RANDOM]: ParticleTuple<T, T>; 261 [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<T>>; 262} 263``` 264 265设置粒子属性更新器配置。 266 267**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 268 269**系统能力：** SystemCapability.ArkUI.ArkUI.Full 270 271| 名称 | 类型 | 只读 | 可选 | 说明 | 272| -------- | -------- | ---- | ---- | -------- | 273[[ParticleUpdater.NONE]|void | 否 | 否 | 无变化。| 274| [ParticleUpdater.RANDOM] | [ParticleTuple](#particletuple18)<T, T> | 否 | 否 | 表示变化方式为匀速变化时，每秒的变化差值为设置区间随机生成的值。<br/>目标属性值为当前属性值叠加变化差值。如当前属性值为0.2，config取[0.1,1.0]:<br/>1、如果变化差值在区间[0.1,1.0]取随机值0.5，则目标属性值为0.2+0.5 = 0.7；<br/>2、变化差值也可以取负值。如当前属性值为0.2，config为 [-3.0,2.0],如果变化差值在区间[-3.0,2.0]取随机值-2.0，则目标属性值为0.2-2.0 = -1.8。<br>**说明：**<br>config配置的是变化差值的取值范围，差值的最大最小值没有约束。但是如果当前属性值叠加差值大于属性最大值，目标属性值取属性最大值；如果当前属性值叠加差值小于属性最小值，目标属性值取属性最小值。T为number。<br>例如：opacity的取值范围[0.0,1.0]则当当前属性值叠加差值超过1.0，则取1.0。| 275|[ParticleUpdater.CURVE]|Array<[ParticlePropertyAnimation](#particlepropertyanimation)\<T\>> | 否 | 否 | 表示变化方式为曲线变化时，属性变化的配置。数组类型表示当前属性可以设置多段动画，如0ms-3000ms，3000ms-5000ms，5000ms-8000ms分别设置动画。T为number。| 276 277## ParticlePropertyAnimation 278```typescript 279interface ParticlePropertyAnimation<T> { 280 from: T; 281 to: T; 282 startMillis: number; 283 endMillis: number; 284 curve?: Curve | ICurve; 285} 286``` 287 288设置粒子属性声明周期。 289 290**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 291 292**系统能力：** SystemCapability.ArkUI.ArkUI.Full 293 294| 名称 | 类型 | 只读 | 可选 | 说明 | 295| -------- | ---- | ---- | -------- | -------- | 296|from| T | 否 | 否 | 属性起始值。非法输入取对应属性的默认值。| 297| to | T | 否 | 否 | 属性目标值。非法输入取对应属性的默认值。| 298|startMillis|number | 否 | 否 | 动画开始时间。<br/>单位：毫秒。<br/>取值范围：[0, +∞)。| 299|endMillis|number | 否 | 否 | 动画结束时间。<br/>单位：毫秒。<br/>取值范围：[0, +∞)。| 300|curve|[Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve9)| 否 | 是 | 设置动画曲线。<br>默认值：Curve.Linear| 301 302 303## ParticleType 304 305粒子类型。 306 307**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 308 309**系统能力：** SystemCapability.ArkUI.ArkUI.Full 310 311| 名称 | 值 | 说明 | 312| -------- | -------- | -------- | 313| POINT | 'point' | 点状粒子 | 314| IMAGE | 'image' | 图片粒子 | 315 316 317 318## ParticleEmitterShape 319 320粒子发射器形状。 321 322**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 323 324**系统能力：** SystemCapability.ArkUI.ArkUI.Full 325 326| 名称 | 值 | 说明 | 327| -------- | -------- | -------- | 328| RECTANGLE | 'rectangle' | 粒子发射器为矩形。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 329| CIRCLE | 'circle' | 粒子发射器为圆形。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 330| ELLIPSE | 'ellipse' | 粒子发射器为椭圆形。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 331| ANNULUS<sup>20+</sup> | 'annulus' | 粒子发射器为环形。<br/> **原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 332 333## DistributionType<sup>12+<sup> 334 335初始颜色随机值分布类型。 336 337**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 338 339**系统能力：** SystemCapability.ArkUI.ArkUI.Full 340 341| 名称 | 值 | 说明 | 342| -------- | -------- | -------- | 343| UNIFORM | 0 | 初始颜色随机值分布为均匀分布。| 344| GAUSSIAN | 1 | 初始颜色随机值分布为高斯分布。| 345 346## ParticleUpdater 347 348粒子变化类型。 349 350**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 351 352**系统能力：** SystemCapability.ArkUI.ArkUI.Full 353 354| 名称 | 值 | 说明 | 355| -------- | -------- | -------- | 356|NONE | 'none' | 无变化| 357|RANDOM | 'random' | 随机变化| 358|CURVE | 'curve' | 动画曲线变化| 359 360## DisturbanceFieldOptions<sup>12+</sup> 361 362设置粒子扰动场参数。 363 364**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 365 366**系统能力：** SystemCapability.ArkUI.ArkUI.Full 367 368| 名称 | 类型 | 只读 | 可选 | 说明 | 369| ------ | ------- | ---- | ------- | --------------------- | 370| strength | number | 否 | 是 |场强，表示场从中心向外的排斥力的强度，默认值0。正数表示排斥力方向朝外，负数表示吸引力，方向朝内。<br/>取值范围：(-∞, +∞)。 | 371| shape | [DisturbanceFieldShape](#disturbancefieldshape12) | 否 | 是 | 场的形状。<br/>默认为DisturbanceFieldShape.RECT。 | 372| size | [SizeT](../js-apis-arkui-graphics.md#sizett12)<number>| 否 | 是 |场的大小。<br/>默认值 {width:0，height:0}。<br/>width和height的取值范围：[0, +∞)。 | 373| position | [PositionT](../js-apis-arkui-graphics.md#positiont12)<number> | 否 | 是 |场的位置。<br/>默认值{x:0，y:0}。<br/>x、y的取值范围：(-∞, +∞)。 | 374| feather | number | 否 | 是 |羽化值，表示场从中心点到场边缘的衰减程度，取值范围0到100的整数，如果0则表示场是一个刚体，所有范围内的粒子都被排斥在外。羽化值越大场的缓和程度越大，场范围内出现越多靠近中心点的粒子。<br/>默认值为0。 | 375| noiseScale | number | 否 | 是 |噪声尺度，用于控制噪声图案的整体大小，取值大于等于0。<br/>默认值1。 | 376| noiseFrequency | number | 否 | 是 |噪声频率，频率越大噪声越细腻，取值大于等于0。<br/> 默认值1。 | 377| noiseAmplitude | number | 否 | 是 |噪声震幅，噪声的波动的范围，震幅越大噪音之间差异越大。取值大于等于0。<br/> 默认值1。 | 378 379## DisturbanceFieldShape<sup>12+</sup> 380 381粒子形状。 382 383**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 384 385**系统能力：** SystemCapability.ArkUI.ArkUI.Full 386 387| 名称 | 值 | 说明 | 388| --------| ---- | ------| 389| RECT | 0 | 长方形。 | 390| CIRCLE | 1 | 圆。 | 391| ELLIPSE | 2 | 椭圆。 | 392 393## EmitterProperty<sup>12+</sup> 394 395设置发射器属性。 396 397**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 398 399**系统能力：** SystemCapability.ArkUI.ArkUI.Full 400 401| 名称 | 类型 | 只读 | 可选 | 说明 | 402| ------ | ------- | ---- | ------- | --------------------- | 403| index | number | 否 | 否 |索引，取整，按初始化参数中发射器的数组索引指定对应的发射器。异常默认值为0。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 404| emitRate | number | 否 | 是 | 发射器发射速率，即每秒发射粒子的数量。<br/>未传入时保持其当前的发射速率， 传入值小于0时取默认值5。emitRate值超过5000时会极大影响性能，建议设置参数小于5000。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 405| position | [PositionT](../js-apis-arkui-graphics.md#positiont12)<number> | 否 | 是 |发射器位置的数组，只支持number类型。<br/>未传入时保持其当前的发射器位置。需传入两个有效参数，若其中一个为异常值，则position不生效。<br/>x、y的取值范围：(-∞, +∞)。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 406| size | [SizeT](../js-apis-arkui-graphics.md#sizett12)<number>| 否 | 是 |发射窗口的大小，只支持number类型。<br/>未传入时保持其当前发射窗口大小。需传入两个有效参数且都大于0，若其中一个为异常值，则size不生效。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 407| annulusRegion<sup>20+</sup> | [ParticleAnnulusRegion](ts-particle-animation.md#particleannulusregion20)| 否 | 是 |环形发射器参数。需要对应index的发射器形状为环形才生效。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 408 409## ParticleTuple<sup>18+</sup> 410 411```typescript 412declare type ParticleTuple<T1, T2> = [T1, T2]; 413``` 414 415粒子元组，表示定义一些动画参数的类型。 416 417**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 418 419**系统能力：** SystemCapability.ArkUI.ArkUI.Full 420 421| 类型 | 说明 | 422| ----------- | ---------------------------------------------- | 423| [T1, T2] | 一些动画参数的类型，可能是任何类型。 | 424 425## Particles<sup>18+</sup> 426 427```typescript 428interface Particles< 429 PARTICLE extends ParticleType, 430 COLOR_UPDATER extends ParticleUpdater, 431 OPACITY_UPDATER extends ParticleUpdater, 432 SCALE_UPDATER extends ParticleUpdater, 433 ACC_SPEED_UPDATER extends ParticleUpdater, 434 ACC_ANGLE_UPDATER extends ParticleUpdater, 435 SPIN_UPDATER extends ParticleUpdater 436> { 437 particles: Array< 438 ParticleOptions< 439 PARTICLE, 440 COLOR_UPDATER, 441 OPACITY_UPDATER, 442 SCALE_UPDATER, 443 ACC_SPEED_UPDATER, 444 ACC_ANGLE_UPDATER, 445 SPIN_UPDATER 446 > 447 >; 448} 449``` 450 451粒子动画的集合。 452 453> **说明：** 454> 455> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 456 457**系统能力：** SystemCapability.ArkUI.ArkUI.Full 458 459| 名称 | 类型 | 只读 | 可选 | 说明 | 460| ------ | ------------------------------ | ---- | ------------------------------------------ | ----------------------------------------------------------------------------- | 461| particles<sup>10+</sup> | 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/>> | 否 | 否 | 粒子动画的集合。每一个的粒子动画（[ParticleOptions](#particleoptions)）包含粒子发射，同时可配置粒子的颜色、透明度、大小、速度、加速度与旋转速度，旋转速度，详见[ParticleOptions](#particleoptions)属性说明。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 462 463## VelocityOptions<sup>18+</sup> 464 465粒子速度配置。 466 467> **说明：** 468> 469> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 470 471**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 472 473**系统能力：** SystemCapability.ArkUI.ArkUI.Full 474 475| 名称 | 类型 | 只读 | 可选 | 说明 | 476| ------ | ------------------------------ | ---- | ------------------------- | ---------------------------------------------------------------------------------------------- | 477| speed<sup>10+</sup> | [ParticleTuple](#particletuple18)<number, number> | 否 | 否 | 表示速度大小。<br/>默认值：{range:[0.0,0.0]} <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 478| angle<sup>10+</sup> | [ParticleTuple](#particletuple18)<number, number> | 否 | 否 | 表示速度的方向（单位为角度）。以元素几何中心为坐标原点，水平方向为X轴，正数表示顺时针方向旋转角度。<br/>默认值：{range:[0.0,0.0]} <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 479 480## AccelerationOptions<sup>18+</sup> 481 482```typescript 483declare interface AccelerationOptions< 484 ACC_SPEED_UPDATER extends ParticleUpdater, 485 ACC_ANGLE_UPDATER extends ParticleUpdater 486> { 487 speed?: ParticlePropertyOptions<number, ACC_SPEED_UPDATER>; 488 angle?: ParticlePropertyOptions<number, ACC_ANGLE_UPDATER>; 489} 490``` 491 492粒子加速度配置。 493 494> **说明：** 495> 496> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 497 498**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 499 500**系统能力：** SystemCapability.ArkUI.ArkUI.Full 501 502| 名称 | 类型 | 只读 | 可选 | 说明 | 503| ------ | --------------------------------------------------- | ---- | ----------- | ---------------------------------------------- | 504| speed<sup>10+</sup> | [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_SPEED_UPDATER](#particleupdater)> | 否 | 是 | 表示加速度大小。<br/>默认值：{range:[0.0,0.0]} <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 505| angle<sup>10+</sup> | [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_ANGLE_UPDATER](#particleupdater)> | 否 | 是 | 表示加速度方向（单位为角度）。<br/>默认值：{range:[0.0,0.0]} <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 506 507## EmitterParticleOptions<sup>18+</sup> 508 509```typescript 510interface EmitterParticleOptions<PARTICLE extends ParticleType> { 511 type: PARTICLE; 512 config: ParticleConfigs[PARTICLE]; 513 count: number; 514 lifetime?: number; 515 lifetimeRange?: number; 516} 517``` 518 519粒子配置。 520 521> **说明：** 522> 523> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 524 525**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 526 527**系统能力：** SystemCapability.ArkUI.ArkUI.Full 528 529| 名称 | 类型 | 只读 | 可选 | 说明 | 530| ------ | --------------------------------------------------- | ---- | ----------- | ---------------------------------------------- | 531| type<sup>10+</sup> | [PARTICLE](#particletype) | 否 | 否 | 表示粒子类型，可以选择图片或者是点。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 532| config<sup>10+</sup> | [ParticleConfigs](#particleconfigs)[PARTICLE] | 否 | 否 | 表示对应类型的配置。<br/>config类型和type值有关联：<br>1、如果type为ParticleType.POINT，则config类型为[PointParticleParameters](#pointparticleparameters) 。<br>2、如果type为ParticleType.IMAGE，则config类型为[ImageParticleParameters](#imageparticleparameters) 。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 533| count<sup>10+</sup> | number | 否 | 否 | 表示发射的粒子总数，count取值>=-1,当count为-1表示粒子总数无限大。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 534| lifetime<sup>10+</sup> | number | 否 | 是 | 表示单个粒子的生命周期，默认值1000（即1000ms，1s），lifetime>=-1。当lifetime为-1表示粒子生命周期无限大。当lifetime<-1，取默认值。<br/>**说明：** 如果不需要动画一直播放，建议不要将生命周期设置为-1，可能对性能造成较大影响。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 535| lifetimeRange<sup>12+</sup> | number | 否 | 是 | 表示粒子生命周期取值范围，设置lifetimeRange后粒子的生命周期为 [lifetime-lifetimeRange,lifeTime+lifetimeRange]中间的一个随机整数。lifetimeRange 默认值为0，取值范围为0到正无穷。设置为负值时取默认值。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 536 537## ParticleUpdaterOptions<sup>18+</sup> 538 539```typescript 540interface ParticleUpdaterOptions<TYPE, UPDATER extends ParticleUpdater> { 541 type: UPDATER; 542 config: ParticlePropertyUpdaterConfigs<TYPE>[UPDATER]; 543} 544``` 545 546颜色属性变化配置。 547 548> **说明：** 549> 550> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 551 552**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 553 554**系统能力：** SystemCapability.ArkUI.ArkUI.Full 555 556| 名称 | 类型 | 只读 | 可选 | 说明 | 557| ------ | ----------------------------------- | ---------------- | ---- | --------------------------------------------------------- | 558| type<sup>10+</sup> | [UPDATER](#particleupdater) | 否 | 否 | 表示颜色属性变化类型。 <br>默认值：type默认为ParticleUpdater.NONE。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 559| config<sup>10+</sup> | [ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)<[TYPE](#particleupdater)[[UPDATER](#particleupdater)] | 否 | 否 | 属性变化配置。属性变化类型type有三类：<br/>1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.NONE]。<br>2、当type为ParticleUpdater.RANDOM，表示变化类型为随机变化，则config类型为[ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.RANDOM]。<br>3、当type为ParticleUpdater.CURVE，表示变化类型为曲线变化，则config类型为[ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[ParticleUpdater.CURVE]。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 560 561## ParticleColorUpdaterOptions<sup>18+</sup> 562 563```typescript 564interface ParticleColorUpdaterOptions<UPDATER extends ParticleUpdater> { 565 type: UPDATER; 566 config: ParticleColorPropertyUpdaterConfigs[UPDATER]; 567} 568``` 569 570颜色属性变化配置。 571 572> **说明：** 573> 574> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 575 576**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 577 578**系统能力：** SystemCapability.ArkUI.ArkUI.Full 579 580| 名称 | 类型 | 只读 | 可选 | 说明 | 581| ------ | --------------------------------------------------- | ---- | ---------- | ----------------------------------------------- | 582| type<sup>10+</sup> | [UPDATER](#particleupdater) | 否 | 否 | 表示颜色属性变化类型。<br>默认值：type默认为 ParticleUpdater.NONE。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 583| config<sup>10+</sup> | [ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[[UPDATER](#particleupdater)] | 否 | 否 | 颜色属性变化类型type有三类：<br>1、当type为ParticleUpdater.NONE，表示无变化，则config类型为[ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.NONE]。 <br>2、type为ParticleUpdater.RANDOM，表示随机变化，则config类型为[ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.RANDOM]。 <br>3、type为ParticleUpdater.CURVE,表示按动画曲线变化，则config类型为[ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[ParticleUpdater.CURVE]。 <br>**说明**：<br>当type为ParticleUpdater.RANDOM或者ParticleUpdater.CURVE时，updater中颜色配置的优先级高于range中的颜色配置。在updater配置的动画时间周期内，以updater中的颜色配置来变化；在updater配置的动画时间周期前，以range中的颜色配置来变化。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 584 585## ParticleColorOptions<sup>18+</sup> 586 587颜色变化方式为均匀变化的时候，在区间内随机生成一个差值。r、g、b、a四个颜色通道每秒分别使用差值叠加当前颜色值，生成目标颜色值。实现颜色随机变化的效果。 588 589> **说明：** 590> 591> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 592 593**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 594 595**系统能力：** SystemCapability.ArkUI.ArkUI.Full 596 597| 名称 | 类型 | 只读 | 可选 | 说明 | 598| ---- | ----------------- | ------------- | ---- | --------------------------- | 599| r<sup>10+</sup> | [ParticleTuple](#particletuple18)<number, number> | 否 | 否 | r颜色通道的差值。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 600| g<sup>10+</sup> | [ParticleTuple](#particletuple18)<number, number> | 否 | 否 | g颜色通道的差值。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 601| b<sup>10+</sup> | [ParticleTuple](#particletuple18)<number, number> | 否 | 否 | b颜色通道的差值。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 602| a<sup>10+</sup> | [ParticleTuple](#particletuple18)<number, number> | 否 | 否 | a颜色通道的差值。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 603 604## ParticleAnnulusRegion<sup>20+</sup> 605 606用于设置环形发射器区域的配置信息。 607 608**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 609 610**系统能力：** SystemCapability.ArkUI.ArkUI.Full 611 612| 名称 | 类型 | 只读 | 可选 | 说明 | 613| ------ | ------ | -- | -- | ---- | 614| center | [PositionT](../js-apis-arkui-graphics.md#positiont12)<[LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12)> | 否 | 是 | 圆环的圆心坐标，组件的左上角为坐标原点。默认值：{x:LengthMetrics.percent(0.5),y:LengthMetrics.percent(0.5)} | 615| outerRadius | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 否 | 圆环的外圆半径。 | 616| innerRadius | [LengthMetrics](../js-apis-arkui-graphics.md#lengthmetrics12) | 否 | 否 | 圆环的内圆半径。 | 617| startAngle | number | 否 | 是 | 圆环的起始角度。<br>单位：度<br>默认值：0 | 618| endAngle | number | 否 | 是 | 圆环的结束角度。<br>单位：度<br>默认值：360 | 619 620 621> **说明：** 622> 623> 1、outerRadius、innerRadius小于零或使用百分比单位时，会按零进行处理。 624> 625> 2、当outerRadius小于innerRadius时（即外圆半径小于内圆半径时），会将当前较小的值作为新的内圆半径，将较大的值作为新的外圆半径。 626> 627> 3、当endAngle小于startAngle时（即结束角度小于起始角度时），会将当前较小的值作为新的起始角度，将较大的值作为新的结束角度。 628 629 630 631## 示例 632 633### 示例1（圆形初始化粒子） 634 635描述粒子动画基础用法，通过圆形初始化粒子。 636 637```ts 638// xxx.ets 639@Entry 640@Component 641struct ParticleExample { 642 build() { 643 Stack() { 644 Text() 645 .width(300).height(300).backgroundColor(Color.Black) 646 Particle({ 647 particles: [ 648 { 649 emitter: { 650 particle: { 651 type: ParticleType.POINT, //粒子类型 652 config: { 653 radius: 10//圆点半径 654 }, 655 count: 500, //粒子总数 656 lifetime: 10000, //粒子生命周期，单位ms 657 lifetimeRange: 100//粒子生命周期取值范围，单位ms 658 }, 659 emitRate: 10, //每秒发射粒子数 660 position: [0, 0], 661 shape: ParticleEmitterShape.RECTANGLE//发射器形状 662 }, 663 color: { 664 range: [Color.Red, Color.Yellow], //初始颜色范围 665 updater: { 666 type: ParticleUpdater.CURVE, //变化方式为曲线变化 667 config: [ 668 { 669 from: Color.White, //变化起始值 670 to: Color.Pink, //变化终点值 671 startMillis: 0, //开始时间 672 endMillis: 3000, //结束时间 673 curve: Curve.EaseIn//变化曲线 674 }, 675 { 676 from: Color.Pink, 677 to: Color.Orange, 678 startMillis: 3000, 679 endMillis: 5000, 680 curve: Curve.EaseIn 681 }, 682 { 683 from: Color.Orange, 684 to: Color.Pink, 685 startMillis: 5000, 686 endMillis: 8000, 687 curve: Curve.EaseIn 688 }, 689 ] 690 } 691 }, 692 opacity: { 693 range: [0.0, 1.0], //粒子透明度的初始值从【0.0到1.0】随机产生 694 updater: { 695 type: ParticleUpdater.CURVE, 696 config: [ 697 { 698 from: 0.0, 699 to: 1.0, 700 startMillis: 0, 701 endMillis: 3000, 702 curve: Curve.EaseIn 703 }, 704 { 705 from: 1.0, 706 to: 0.0, 707 startMillis: 5000, 708 endMillis: 10000, 709 curve: Curve.EaseIn 710 } 711 ] 712 } 713 }, 714 scale: { 715 range: [0.0, 0.0], 716 updater: { 717 type: ParticleUpdater.CURVE, 718 config: [ 719 { 720 from: 0.0, 721 to: 0.5, 722 startMillis: 0, 723 endMillis: 3000, 724 curve: Curve.EaseIn 725 } 726 ] 727 } 728 }, 729 acceleration: { 730 //加速度的配置，从大小和方向两个维度变化，speed表示加速度大小，angle表示加速度方向 731 speed: { 732 range: [3, 9], 733 updater: { 734 type: ParticleUpdater.RANDOM, //Speed的变化方式是随机变化 735 config: [1, 20] 736 } 737 }, 738 angle: { 739 range: [90, 90] 740 } 741 } 742 743 } 744 ] 745 }).width(300).height(300) 746 }.width("100%").height("100%").align(Alignment.Center) 747 } 748} 749``` 750 751 752 753### 示例2（图片初始化粒子） 754 755描述粒子动画基础用法，通过图片初始化粒子。 756 757```ts 758@Entry 759@Component 760struct ParticleExample { 761 @State 762 myCount: number = 100 763 flag: boolean = false; 764 765 build() { 766 Column() { 767 Stack() { 768 Particle({ 769 particles: [ 770 { 771 emitter: { 772 particle: { 773 type: ParticleType.IMAGE, 774 config: { 775 src: $r("app.media.book"), 776 size: [10, 10] 777 }, 778 count: this.myCount, 779 lifetime: 10000, 780 lifetimeRange: 100 781 }, 782 emitRate: 3, 783 shape: ParticleEmitterShape.CIRCLE 784 }, 785 color: { 786 range: [Color.White, Color.White] 787 }, 788 opacity: { 789 range: [1.0, 1.0], 790 updater: { 791 type: ParticleUpdater.CURVE, 792 config: [ 793 { 794 from: 0, 795 to: 1.0, 796 startMillis: 0, 797 endMillis: 6000 798 }, 799 { 800 from: 1.0, 801 to: 0, 802 startMillis: 6000, 803 endMillis: 10000 804 } 805 ] 806 } 807 }, 808 scale: { 809 range: [0.1, 1.0], 810 updater: { 811 type: ParticleUpdater.CURVE, 812 config: [ 813 { 814 from: 0, 815 to: 1.5, 816 startMillis: 0, 817 endMillis: 8000, 818 curve: Curve.EaseIn 819 } 820 821 ] 822 } 823 }, 824 acceleration: { 825 speed: { 826 range: [3, 9], 827 updater: { 828 type: ParticleUpdater.CURVE, 829 config: [ 830 { 831 from: 10, 832 to: 20, 833 startMillis: 0, 834 endMillis: 3000, 835 curve: Curve.EaseIn 836 }, 837 { 838 from: 10, 839 to: 2, 840 startMillis: 3000, 841 endMillis: 8000, 842 curve: Curve.EaseIn 843 } 844 ] 845 } 846 }, 847 angle: { 848 range: [0, 180], 849 updater: { 850 type: ParticleUpdater.CURVE, 851 config: [{ 852 from: 1, 853 to: 2, 854 startMillis: 0, 855 endMillis: 1000, 856 curve: Curve.EaseIn 857 }, 858 { 859 from: 50, 860 to: -50, 861 startMillis: 1000, 862 endMillis: 3000, 863 curve: Curve.EaseIn 864 }, 865 { 866 from: 3, 867 to: 5, 868 startMillis: 3000, 869 endMillis: 8000, 870 curve: Curve.EaseIn 871 } 872 ] 873 } 874 } 875 }, 876 spin: { 877 range: [0.1, 1.0], 878 updater: { 879 type: ParticleUpdater.CURVE, 880 config: [ 881 { 882 from: 0, 883 to: 360, 884 startMillis: 0, 885 endMillis: 8000, 886 curve: Curve.EaseIn 887 } 888 ] 889 } 890 }, 891 } 892 , { 893 emitter: { 894 particle: { 895 type: ParticleType.IMAGE, 896 config: { 897 src: $r('app.media.heart'), 898 size: [10, 10] 899 }, 900 count: this.myCount, 901 lifetime: 10000, 902 lifetimeRange: 100 903 }, 904 emitRate: 3, 905 shape: ParticleEmitterShape.CIRCLE 906 }, 907 color: { 908 range: [Color.White, Color.White] 909 }, 910 opacity: { 911 range: [1.0, 1.0], 912 updater: { 913 type: ParticleUpdater.CURVE, 914 config: [ 915 { 916 from: 0, 917 to: 1.0, 918 startMillis: 0, 919 endMillis: 6000 920 }, 921 { 922 from: 1.0, 923 to: 0, 924 startMillis: 6000, 925 endMillis: 10000 926 } 927 ] 928 } 929 }, 930 scale: { 931 range: [0.1, 1.0], 932 updater: { 933 type: ParticleUpdater.CURVE, 934 config: [ 935 { 936 from: 0, 937 to: 2.0, 938 startMillis: 0, 939 endMillis: 10000, 940 curve: Curve.EaseIn 941 } 942 943 ] 944 } 945 }, 946 acceleration: { 947 speed: { 948 range: [3, 9], 949 updater: { 950 type: ParticleUpdater.CURVE, 951 config: [ 952 { 953 from: 10, 954 to: 20, 955 startMillis: 0, 956 endMillis: 3000, 957 curve: Curve.EaseIn 958 }, 959 { 960 from: 10, 961 to: 2, 962 startMillis: 3000, 963 endMillis: 8000, 964 curve: Curve.EaseIn 965 } 966 ] 967 } 968 }, 969 angle: { 970 range: [0, 180], 971 updater: { 972 type: ParticleUpdater.CURVE, 973 config: [{ 974 from: 1, 975 to: 2, 976 startMillis: 0, 977 endMillis: 1000, 978 curve: Curve.EaseIn 979 }, 980 { 981 from: 50, 982 to: -50, 983 startMillis: 0, 984 endMillis: 3000, 985 curve: Curve.EaseIn 986 }, 987 { 988 from: 3, 989 to: 5, 990 startMillis: 3000, 991 endMillis: 10000, 992 curve: Curve.EaseIn 993 } 994 ] 995 } 996 } 997 }, 998 spin: { 999 range: [0.1, 1.0], 1000 updater: { 1001 type: ParticleUpdater.CURVE, 1002 config: [ 1003 { 1004 from: 0, 1005 to: 360, 1006 startMillis: 0, 1007 endMillis: 10000, 1008 curve: Curve.EaseIn 1009 } 1010 ] 1011 } 1012 }, 1013 }, { 1014 emitter: { 1015 particle: { 1016 type: ParticleType.IMAGE, 1017 config: { 1018 src: $r('app.media.sun'), 1019 size: [10, 10] 1020 }, 1021 count: this.myCount, 1022 lifetime: 10000, 1023 lifetimeRange: 100 1024 }, 1025 emitRate: 3, 1026 shape: ParticleEmitterShape.CIRCLE 1027 }, 1028 color: { 1029 range: [Color.White, Color.White] 1030 }, 1031 opacity: { 1032 range: [1.0, 1.0], 1033 updater: { 1034 type: ParticleUpdater.CURVE, 1035 config: [ 1036 { 1037 from: 0, 1038 to: 1.0, 1039 startMillis: 0, 1040 endMillis: 6000 1041 }, 1042 { 1043 from: 1.0, 1044 to: 0, 1045 startMillis: 6000, 1046 endMillis: 10000 1047 } 1048 ] 1049 } 1050 }, 1051 scale: { 1052 range: [0.1, 1.0], 1053 updater: { 1054 type: ParticleUpdater.CURVE, 1055 config: [ 1056 { 1057 from: 0, 1058 to: 2.0, 1059 startMillis: 0, 1060 endMillis: 10000, 1061 curve: Curve.EaseIn 1062 } 1063 1064 ] 1065 } 1066 }, 1067 acceleration: { 1068 speed: { 1069 range: [3, 9], 1070 updater: { 1071 type: ParticleUpdater.CURVE, 1072 config: [ 1073 { 1074 from: 10, 1075 to: 20, 1076 startMillis: 0, 1077 endMillis: 3000, 1078 curve: Curve.EaseIn 1079 }, 1080 { 1081 from: 10, 1082 to: 2, 1083 startMillis: 3000, 1084 endMillis: 8000, 1085 curve: Curve.EaseIn 1086 } 1087 ] 1088 } 1089 }, 1090 angle: { 1091 range: [0, 180], 1092 updater: { 1093 type: ParticleUpdater.CURVE, 1094 config: [{ 1095 from: 1, 1096 to: 2, 1097 startMillis: 0, 1098 endMillis: 1000, 1099 curve: Curve.EaseIn 1100 }, 1101 { 1102 from: 50, 1103 to: -50, 1104 startMillis: 1000, 1105 endMillis: 3000, 1106 curve: Curve.EaseIn 1107 }, 1108 { 1109 from: 3, 1110 to: 5, 1111 startMillis: 3000, 1112 endMillis: 8000, 1113 curve: Curve.EaseIn 1114 } 1115 ] 1116 } 1117 } 1118 }, 1119 spin: { 1120 range: [0.1, 1.0], 1121 updater: { 1122 type: ParticleUpdater.CURVE, 1123 config: [ 1124 { 1125 from: 0, 1126 to: 360, 1127 startMillis: 0, 1128 endMillis: 10000, 1129 curve: Curve.EaseIn 1130 } 1131 ] 1132 } 1133 }, 1134 } 1135 ] 1136 }).width(300).height(300) 1137 1138 }.width(500).height(500).align(Alignment.Center) 1139 }.width("100%").height("100%") 1140 1141 } 1142} 1143``` 1144 1145 1146### 示例3（粒子扰动场的干扰下运动轨迹发生变化） 1147 1148该示例主要演示如何通过粒子扰动场的干扰下来实现运动轨迹发生变化的效果。 1149 1150``` 1151@Entry 1152@Component 1153struct ParticleExample { 1154 build() { 1155 Stack() { 1156 Text() 1157 .width(300).height(300).backgroundColor(Color.Black) 1158 Particle({ 1159 particles: [ 1160 { 1161 emitter: { 1162 particle: { 1163 type: ParticleType.POINT, //粒子类型 1164 config: { 1165 radius: 10//圆点半径 1166 }, 1167 count: 500, //粒子总数 1168 lifetime: 10000//粒子生命周期，单位ms 1169 }, 1170 emitRate: 10, //每秒发射粒子数 1171 position: [0, 0], 1172 shape: ParticleEmitterShape.RECTANGLE//发射器形状 1173 }, 1174 color: { 1175 range: [Color.Red, Color.Yellow], //初始颜色范围 1176 updater: { 1177 type: ParticleUpdater.CURVE, //变化方式为曲线变化 1178 config: [ 1179 { 1180 from: Color.White, //变化起始值 1181 to: Color.Pink, //变化终点值 1182 startMillis: 0, //开始时间 1183 endMillis: 3000, //结束时间 1184 curve: Curve.EaseIn//变化曲线 1185 }, 1186 { 1187 from: Color.Pink, 1188 to: Color.Orange, 1189 startMillis: 3000, 1190 endMillis: 5000, 1191 curve: Curve.EaseIn 1192 }, 1193 { 1194 from: Color.Orange, 1195 to: Color.Pink, 1196 startMillis: 5000, 1197 endMillis: 8000, 1198 curve: Curve.EaseIn 1199 }, 1200 ] 1201 } 1202 }, 1203 opacity: { 1204 range: [0.0, 1.0], //粒子透明度的初始值从[0.0,1.0]随机产生 1205 updater: { 1206 type: ParticleUpdater.CURVE, 1207 config: [ 1208 { 1209 from: 0.0, 1210 to: 1.0, 1211 startMillis: 0, 1212 endMillis: 3000, 1213 curve: Curve.EaseIn 1214 }, 1215 { 1216 from: 1.0, 1217 to: 0.0, 1218 startMillis: 5000, 1219 endMillis: 10000, 1220 curve: Curve.EaseIn 1221 } 1222 ] 1223 } 1224 }, 1225 scale: { 1226 range: [0.0, 0.0], 1227 updater: { 1228 type: ParticleUpdater.CURVE, 1229 config: [ 1230 { 1231 from: 0.0, 1232 to: 0.5, 1233 startMillis: 0, 1234 endMillis: 3000, 1235 curve: Curve.EaseIn 1236 } 1237 ] 1238 } 1239 }, 1240 acceleration: { 1241 //加速度的配置，从大小和方向两个维度变化，speed表示加速度大小，angle表示加速度方向 1242 speed: { 1243 range: [3, 9], 1244 updater: { 1245 type: ParticleUpdater.RANDOM, 1246 config: [1, 20] 1247 } 1248 }, 1249 angle: { 1250 range: [90, 90] 1251 } 1252 } 1253 1254 } 1255 ] 1256 }).width(300).height(300).disturbanceFields([{ 1257 strength: 10, 1258 shape: DisturbanceFieldShape.RECT, 1259 size: { width: 100, height: 100 }, 1260 position: { x: 100, y: 100 }, 1261 feather: 15, 1262 noiseScale: 10, 1263 noiseFrequency: 15, 1264 noiseAmplitude: 5 1265 }]) 1266 }.width("100%").height("100%").align(Alignment.Center) 1267 } 1268} 1269 1270``` 1271 1272 1273### 示例4（调整粒子发射器位置） 1274通过emitter()调整粒子发射器的位置。 1275```ts 1276@Entry 1277@Component 1278struct ParticleExample { 1279 @State emitterProperties: Array<EmitterProperty> = [ 1280 { 1281 index: 0, 1282 emitRate: 100, 1283 position: { x: 60, y: 80 }, 1284 size: { width: 200, height: 200 } 1285 } 1286 ] 1287 1288 build() { 1289 Stack() { 1290 Text() 1291 .width(300).height(300).backgroundColor(Color.Black) 1292 Particle({ 1293 particles: [ 1294 { 1295 emitter: { 1296 particle: { 1297 type: ParticleType.POINT, // 粒子类型 1298 config: { 1299 radius: 5// 圆点半径 1300 }, 1301 count: 400, // 粒子总数 1302 lifetime: -1// 粒子的生命周期，-1表示粒子生命周期无限大 1303 }, 1304 emitRate: 10, // 每秒发射粒子数 1305 position: [0, 0], // 粒子发射位置 1306 shape: ParticleEmitterShape.CIRCLE// 发射器形状 1307 }, 1308 color: { 1309 range: [Color.Red, Color.Yellow], // 初始颜色范围 1310 updater: { 1311 type: ParticleUpdater.CURVE, // 变化方式为曲线变化 1312 config: [ 1313 { 1314 from: Color.White, 1315 to: Color.Pink, 1316 startMillis: 0, 1317 endMillis: 3000, 1318 curve: Curve.EaseIn 1319 }, 1320 { 1321 from: Color.Pink, 1322 to: Color.Orange, 1323 startMillis: 3000, 1324 endMillis: 5000, 1325 curve: Curve.EaseIn 1326 }, 1327 { 1328 from: Color.Orange, 1329 to: Color.Pink, 1330 startMillis: 5000, 1331 endMillis: 8000, 1332 curve: Curve.EaseIn 1333 }, 1334 ] 1335 } 1336 }, 1337 }, 1338 ] 1339 }) 1340 .width(300) 1341 .height(300) 1342 .emitter(this.emitterProperties) 1343 }.width("100%").height("100%").align(Alignment.Center) 1344 } 1345} 1346``` 1347 1348 1349### 示例5（环形发射器创建） 1350描述粒子动画环形发射器创建的基础用法。 1351```ts 1352import { LengthMetrics } from '@kit.ArkUI'; 1353 1354@Entry 1355@Component 1356struct ParticleExample { 1357 build() { 1358 Stack() { 1359 Text() 1360 .width(300).height(300).backgroundColor(Color.Black) 1361 Particle({ 1362 particles: [ 1363 { 1364 emitter: { 1365 particle: { 1366 type: ParticleType.POINT, //粒子类型 1367 config: { 1368 radius: 5//圆点半径 1369 }, 1370 count: 2000, //粒子总数 1371 lifetime: 10000, //粒子生命周期，单位ms 1372 lifetimeRange: 100//粒子生命周期取值范围，单位ms 1373 }, 1374 emitRate: 100, //每秒发射粒子数 1375 shape: ParticleEmitterShape.ANNULUS,//环形发射器 1376 annulusRegion:{ 1377 center:{x:LengthMetrics.percent(0.5),y:LengthMetrics.percent(0.5)}, // 圆环的圆心坐标 1378 innerRadius:LengthMetrics.vp(100), // 圆环的外圆半径 1379 outerRadius:LengthMetrics.vp(120), // 圆环的内圆半径 1380 startAngle:0, // 圆环的起始角度 1381 endAngle:360 // 圆环的结束角度 1382 } 1383 }, 1384 color: { 1385 range: [Color.Pink, Color.White], 1386 }, 1387 opacity: { 1388 range: [0.0, 1.0], 1389 updater: { 1390 type: ParticleUpdater.CURVE, 1391 config: [ 1392 { 1393 from: 0.0, 1394 to: 1.0, 1395 startMillis: 0, 1396 endMillis: 3000, 1397 curve: Curve.EaseIn 1398 }, 1399 { 1400 from: 1.0, 1401 to: 0.0, 1402 startMillis: 5000, 1403 endMillis: 10000, 1404 curve: Curve.EaseIn 1405 } 1406 ] 1407 } 1408 }, 1409 scale: { 1410 range: [0.0, 0.0], 1411 updater: { 1412 type: ParticleUpdater.CURVE, 1413 config: [ 1414 { 1415 from: 0.0, 1416 to: 0.5, 1417 startMillis: 0, 1418 endMillis: 3000, 1419 curve: Curve.EaseIn 1420 } 1421 ] 1422 } 1423 }, 1424 } 1425 ] 1426 }).width(300).height(300) 1427 }.width("100%").height("100%").align(Alignment.Center) 1428 } 1429} 1430``` 1431 1432 1433### 示例6（环形发射器更新） 1434描述粒子动画环形发射器更新的基础用法。 1435```ts 1436// xxx.ets 1437import { LengthMetrics } from '@kit.ArkUI' 1438 1439@Entry 1440@Component 1441struct ParticleExample { 1442 1443 @State radius: number = 1 1444 @State shape: ParticleEmitterShape = ParticleEmitterShape.ANNULUS 1445 @State emitRate: number = 200 1446 @State count: number = 2000 1447 private timerID: number = -1 1448 private centerX: LengthMetrics = LengthMetrics.percent(0.5) 1449 private centerY: LengthMetrics = LengthMetrics.percent(0.5) 1450 private inRadius: LengthMetrics = LengthMetrics.vp(120) 1451 private outRadius: LengthMetrics = LengthMetrics.vp(120) 1452 private startAngle: number = 0 1453 private endAngle: number = 90 1454 @State emitterProperties: Array<EmitterProperty> = [ 1455 { 1456 index: 0, 1457 emitRate: 100, 1458 annulusRegion: { 1459 center:{x:this.centerX, y: this.centerY}, // 圆环的圆心坐标 1460 outerRadius: this.outRadius, // 圆环的外圆半径 1461 innerRadius: this.inRadius, // 圆环的内圆半径 1462 startAngle: -90, // 圆环的起始角度 1463 endAngle: 0 // 圆环的结束角度 1464 } 1465 } 1466 ] 1467 @State region: ParticleAnnulusRegion = { 1468 center:{x:this.centerX, y: this.centerY}, 1469 outerRadius: this.outRadius, 1470 innerRadius: this.inRadius, 1471 startAngle: -90, 1472 endAngle: 0 1473 } 1474 1475 aboutToDisappear(): void { 1476 // 页面销毁时清除计时器 1477 if (this.timerID != -1) { 1478 clearInterval(this.timerID); 1479 } 1480 } 1481 1482 build() { 1483 Column({ space: 10}) { 1484 Stack() { 1485 Text() 1486 .width(300).height(300).backgroundColor(Color.Black) 1487 1488 Particle({ 1489 particles: [ 1490 { 1491 emitter: { 1492 particle: { 1493 type: ParticleType.POINT, // 粒子类型 1494 config: { 1495 radius: this.radius // 圆点半径 1496 }, 1497 count: this.count, // 粒子总数 1498 lifetime: -1 // 粒子的生命周期，-1表示粒子生命周期无限大 1499 }, 1500 emitRate: this.emitRate, // 每秒发射粒子数 1501 shape: this.shape, //发射器形状 1502 annulusRegion: this.region 1503 }, 1504 color: { 1505 range: [Color.White, Color.Pink], // 初始颜色范围 1506 }, 1507 }, 1508 ] 1509 }).width("100%") 1510 .height("100%") 1511 .emitter(this.emitterProperties) 1512 .onClick(()=>{ 1513 // 清除已有定时器 1514 if (this.timerID != -1) { 1515 clearInterval(this.timerID); 1516 } 1517 1518 // 创建定时器（每秒更新） 1519 this.timerID = setInterval(() => { 1520 this.emitterProperties = [ 1521 { 1522 index: 0, 1523 emitRate: this.emitRate, 1524 annulusRegion: { 1525 center:{x:this.centerX, y: this.centerY}, 1526 outerRadius: this.outRadius, 1527 innerRadius: this.inRadius, 1528 startAngle: this.startAngle, 1529 endAngle: this.endAngle 1530 } 1531 } 1532 ]; 1533 if (this.endAngle >= 270) { 1534 if (this.timerID != -1) { 1535 clearInterval(this.timerID); 1536 } 1537 return; 1538 } 1539 // 更新角度值（5度/秒） 1540 this.startAngle += 30; 1541 this.endAngle += 30; 1542 }, 1000); 1543 1544 }) 1545 } 1546 .width("100%") 1547 .height("100%") 1548 .align(Alignment.Center) 1549 } 1550 } 1551} 1552``` 1553 1554
