1# 粒子动画 (Particle) 2 3粒子动画是在一定范围内随机生成的大量粒子产生运动而组成的动画。动画元素是一个个粒子，这些粒子可以是圆点、图片。通过对粒子在颜色、透明度、大小、速度、加速度、自旋角度等维度变化做动画，来营造一种氛围感，比如下雪的动效，雪花飘舞就相当于一个个雪花粒子在做动画。 4 5粒子动画的效果通过Particle组件展现。 6 7 8> **说明：** 9> 10> 该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 11 12 13## 子组件 14 15无 16 17 18## 接口 19 20```typescript 21interface ParticleInterface { 22 < 23 PARTICLE extends ParticleType, 24 COLOR_UPDATER extends ParticleUpdater, 25 OPACITY_UPDATER extends ParticleUpdater, 26 SCALE_UPDATER extends ParticleUpdater, 27 ACC_SPEED_UPDATER extends ParticleUpdater, 28 ACC_ANGLE_UPDATER extends ParticleUpdater, 29 SPIN_UPDATER extends ParticleUpdater 30 >(value: { 31 particles: Array< 32 ParticleOptions< 33 PARTICLE, 34 COLOR_UPDATER, 35 OPACITY_UPDATER, 36 SCALE_UPDATER, 37 ACC_SPEED_UPDATER, 38 ACC_ANGLE_UPDATER, 39 SPIN_UPDATER 40 > 41 >; 42 }): ParticleAttribute; 43} 44``` 45 46**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 47 48**参数：** 49 50| 参数名 | 类型 | 必填 | 描述 | 51| -------- | -------- | -------- | -------- | 52| value | {<br/>particles:Array<[ParticleOptions](#particleoptions)<<br/>[PARTICLE](#particletype), <br/>[COLOR_UPDATER](#particleupdater),<br/>[OPACITY_UPDATER](#particleupdater),<br/>[SCALE_UPDATER](#particleupdater),<br/>[ACC_SPEED_UPDATER](#particleupdater),<br/> [ACC_ANGLE_UPDATER](#particleupdater),<br/>[SPIN_UPDATER](#particleupdater)<br/>>><br/>} | 是 | 粒子动画的集合。每一个的粒子动画（ParticleOptions）包含粒子发射，同时可配置粒子的颜色、透明度、大小、速度、加速度与旋转速度，旋转速度，详见[ParticleOptions](#particleoptions)属性说明。 53 54## 属性 55 56除支持[通用属性](ts-universal-attributes-size.md)外还支持以下属性： 57 58### disturbanceFields<sup>12+</sup> 59 60disturbanceFields(fields: Array<DisturbanceFieldOptions>) 61 62设置扰动场。 63 64**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 65 66**系统能力：** SystemCapability.ArkUI.ArkUI.Full 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| ------ | ------- | ---- | ---------------------------- | 72| fields | Array<[DisturbanceFieldOptions](#disturbancefieldoptions12)> | 是 | 扰动场数组。 | 73 74### emitter<sup>12+</sup> 75emitter(value: Array<EmitterProperty>) 76 77支持发射器位置动态更新 78 79**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 80 81**系统能力：** SystemCapability.ArkUI.ArkUI.Full 82 83**参数：** 84 85| 参数名 | 类型 | 必填 | 说明 | 86| ------ | ------- | ---- | ---------------------------- | 87| value | Array<[EmitterProperty](#emitterproperty12)> | 是 | 需要更新的emitter参数数组 | 88 89## 事件 90支持[通用事件](ts-universal-events-click.md) 91 92## ParticleOptions 93 94```typescript 95interface ParticleOptions< 96 PARTICLE extends ParticleType, 97 COLOR_UPDATER extends ParticleUpdater, 98 OPACITY_UPDATER extends ParticleUpdater, 99 SCALE_UPDATER extends ParticleUpdater, 100 ACC_SPEED_UPDATER extends ParticleUpdater, 101 ACC_ANGLE_UPDATER extends ParticleUpdater, 102 SPIN_UPDATER extends ParticleUpdater 103> { 104 emitter: EmitterOptions<PARTICLE>; 105 color?: ParticleColorPropertyOptions<COLOR_UPDATER>; 106 opacity?: ParticlePropertyOptions<number, OPACITY_UPDATER>; 107 scale?: ParticlePropertyOptions<number, SCALE_UPDATER>; 108 velocity?: { 109 speed: [number, number]; 110 angle: [number, number]; 111 }; 112 acceleration?: { 113 speed?: ParticlePropertyOptions<number, ACC_SPEED_UPDATER>; 114 angle?: ParticlePropertyOptions<number, ACC_ANGLE_UPDATER>; 115 }; 116 spin?: ParticlePropertyOptions<number, SPIN_UPDATER>; 117} 118``` 119 120**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 121 122**系统能力：** SystemCapability.ArkUI.ArkUI.Full 123 124| 名称 | 类型 | 必填 | 说明 | 125| -------- | -------- | -------- | -------- | 126| emitter | [EmitterOptions](#emitteroptions)<[PARTICLE](#particletype)> | 是 | 粒子发射器配置。 | 127| color | [ParticleColorPropertyOptions](#particlecolorpropertyoptions)<[COLOR_UPDATER](#particleupdater)> | 否 | 粒子颜色配置。<br/>**说明**：<br/>默认值：{ range:[Color.White,Color.White] } 。图片粒子不支持设置颜色。| 128| opacity | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [OPACITY_UPDATER](#particleupdater)> | 否 | 粒子透明度配置。<br/>默认值：{ range:[1.0,1.0] } | 129| scale | [ParticlePropertyOptions](#particlepropertyoptions)\<number, [SCALE_UPDATER](#particleupdater)> | 否 | 粒子大小配置。<br/>默认值：{ range:[1.0,1.0] } | 130| velocity | {<br/>speed: [number, number];<br/>angle: [number, number]<br/>} |否 | 粒子速度配置。<br/>**说明**：<br/>speed表示速度大小。angle表示速度的方向（单位为角度），以元素几何中心为坐标原点，水平方向为X轴，正数表示顺时针方向旋转角度。<br/>默认值：{ speed:[0.0,0.0],angle:[0.0,0.0] } | 131| acceleration | {<br/>speed?: [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_SPEED_UPDATER](#particleupdater)>;<br/>angle?: [ParticlePropertyOptions](#particlepropertyoptions)<number, [ACC_ANGLE_UPDATER](#particleupdater)><br/>} | 否 | 粒子加速度配置。 <br/>**说明**：<br/>speed表示加速度大小，angle表示加速度方向（单位为角度）。<br/>默认值：{ speed:{range:[0.0,0.0]},angle:{range:[0.0,0.0]} }| 132| spin | [ParticlePropertyOptions](#particlepropertyoptions)<number, [SPIN_UPDATER](#particleupdater)> | 否 | 粒子自旋角度配置。 <br/>默认值：{range:[0.0,0.0]}<br/>方向：正数表示顺时针旋转，负数表示逆时针旋转。| 133 134 135## EmitterOptions 136粒子发射器的配置 137 138```typescript 139interface EmitterOptions<PARTICLE extends ParticleType> { 140 particle: { 141 type: PARTICLE; 142 config: ParticleConfigs[PARTICLE]; 143 count: number; 144 lifetime?: number; 145 lifetimeRange?: number; 146 }; 147 emitRate?: number; 148 shape?: ParticleEmitterShape; 149 position?: [Dimension, Dimension]; 150 size?: [Dimension, Dimension]; 151} 152``` 153 154**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 155 156**系统能力：** SystemCapability.ArkUI.ArkUI.Full 157 158| 名称 | 类型 | 必填 | 说明 | 159| -------- | -------- | -------- | -------- | 160| particle | {<br>type: [PARTICLE](#particletype);<br>config: [ParticleConfigs](#particleconfigs);<br>count: number;<br>lifetime?: number;<br>lifeTimeRange?:number<sup>12+<sup><br>} | 是 | 粒子配置。<br>-type表示粒子类型，可以选择图片或者是点。<br/><br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br>-config表示对应类型的配置。<br>-config类型和type值有关联：<br>1、如果type为ParticleType.POINT，则config类型为[PointParticleParameters](#pointparticleparameters) 。<br>2、如果type为ParticleType.IMAGE，则config类型为[ImageParticleParameters](#imageparticleparameters) 。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br>-count表示发射的粒子总数，count取值>=-1,当count为-1表示粒子总数无限大。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br>-lifetime表示单个粒子的生命周期，默认值1000（即1000ms，1s）,lifetime>=-1,当lifetime为-1表示粒子生命周期无限大。当lifetime<-1，取默认值。<br/>**说明：**如果不需要动画一直播放，建议不要将生命周期设置为-1，可能对性能造成较大影响。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br>-lifeTimeRange表示粒子生命周期取值范围，设置lifeTimeRange后粒子的生命周期为 [lifetime-lifeTimeRange,lifeTime+lifeTimeRange]中间的一个随机整数。lifeTimeRange 默认值为0，取值范围为为0到正无穷。设置为负值时取默认值。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 161| emitRate | number | 否 | 发射器发射速率（即每秒发射粒子数）。 默认值：5，小于0时取默认值5。emitRate值超过5000时会极大影响性能，建议设置参数小于5000。| 162| shape | [ParticleEmitterShape](#particleemittershape) | 否 | 发射器形状。默认值：ParticleEmitterShape.RECTANGLE。 | 163| position | \[[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)\] | 否 | 发射器位置（距离组件左上角的位置。第一个参数为x方向上的相对偏移，第二个参数为y轴方向相对偏移。） <br>默认值：`[0.0, 0.0]`。| 164| size | \[[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)\] |否 | 发射窗口的大小。第一个参数为发射器宽，第二个参数为发射器高。<br>默认值`['100%','100%']`(即发射窗口占满Particle组件)。 | 165 166## ParticleConfigs 167 168```typescript 169interface ParticleConfigs { 170 [ParticleType.POINT]: PointParticleParameters; 171 [ParticleType.IMAGE]: ImageParticleParameters; 172} 173``` 174 175**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 176 177**系统能力：** SystemCapability.ArkUI.ArkUI.Full 178 179| 名称 | 类型 | 必填 | 说明 | 180| -------- | -------------- | -------- | -------- | 181| [ParticleType.POINT] | [PointParticleParameters](#pointparticleparameters) | 是 | 点状粒子配置。 | 182| [ParticleType.IMAGE] | [ImageParticleParameters](#imageparticleparameters) | 是 | 图片粒子配置。 | 183 184## PointParticleParameters 185```typescript 186interface PointParticleParameters { 187 radius: VP; 188} 189``` 190 191**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 192 193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 194 195| 名称 | 类型 | 必填 | 说明 | 196| -------- | -------------- | -------- | -------- | 197| radius | [VP](ts-types.md#vp10)| 是 | 粒子半径。 | 198 199## ImageParticleParameters 200```typescript 201interface ImageParticleParameters { 202 src: ResourceStr; 203 size: [Dimension, Dimension]; 204 objectFit?: ImageFit; 205} 206``` 207 208**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 209 210**系统能力：** SystemCapability.ArkUI.ArkUI.Full 211 212| 名称 | 类型 | 必填 | 说明 | 213| -------- | -------------- | -------- | -------- | 214| src | [ResourceStr](ts-types.md#resourcestr) | 是 | 图片路径。暂不支持svg图片类型。 | 215| size | \[[Dimension](ts-types.md#dimension10), [Dimension](ts-types.md#dimension10)\]| 是 | 图像尺寸。 | 216| objectFit| [ImageFit](ts-appendix-enums.md#imagefit)| 否 | 图片显示模式。 | 217 218## ParticleColorPropertyOptions 219 220```typescript 221interface ParticleColorPropertyOptions<UPDATER extends ParticleUpdater> { 222 range: [ResourceColor, ResourceColor]; 223 distributionType?: DistributionType; 224 updater?: { 225 type: UPDATER; 226 config: ParticleColorPropertyUpdaterConfigs[UPDATER]; 227 }; 228} 229``` 230**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 231 232**系统能力：** SystemCapability.ArkUI.ArkUI.Full 233 234| 名称 | 类型 | 必填 | 说明 | 235| -------- | -------- | -------- | -------- | 236| range | \[[ResourceColor](ts-types.md#resourcecolor), [ResourceColor](ts-types.md#resourcecolor)\] | 是 | 粒子初始颜色区间，粒子发射器生成粒子的初始颜色在range区间随机取值。<br>默认值：range:[Color.White,Color.White] <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 237| distributionType<sup>12+<sup> | [DistributionType](#distributiontype12) | 否 | 粒子初始颜色随机值分布，允许用户选择颜色随机值生成的分布类型，支持均匀分布或正态（高斯）分布。<br>默认值：DistributionType.UNIFORM<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 238| updater | {<br>type: [UPDATER](#particleupdater);<br>config: [ParticleColorPropertyUpdaterConfigs](#particlecolorpropertyupdaterconfigs)[UPDATER]<br>} | 否 | 颜色属性变化配置。颜色属性变化类型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开始，该接口支持在原子化服务中使用。| 239 240 241## ParticleColorPropertyUpdaterConfigs 242```typescript 243interface ParticleColorPropertyUpdaterConfigs { 244 [ParticleUpdater.NONE]: void; 245 [ParticleUpdater.RANDOM]: { 246 r: [number, number]; 247 g: [number, number]; 248 b: [number, number]; 249 a: [number, number]; 250 }; 251 [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<ResourceColor>>; 252} 253``` 254 255**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.ArkUI.ArkUI.Full 258 259| 名称 | 类型 | 必填 | 说明 | 260| -------- | -------- | -------- | -------- | 261|[ParticleUpdater.NONE]|void | 是 | 无变化。| 262| [ParticleUpdater.RANDOM] | {<br> r: [number, number];<br> g: [number, number];<br> b: [number, number];<br> a: [number, number];<br>} | 是 | 表示变化方式为均匀变化的时候，在区间内随机生成一个差值。r、g、b、a四个颜色通道每秒分别使用差值叠加当前颜色值，生成目标颜色值。实现颜色随机变化的效果。| 263[ParticleUpdater.CURVE]|Array<[ParticlePropertyAnimation](#particlepropertyanimation)\<[ResourceColor](ts-types.md#resourcecolor)\>> | 是 | 表示变化方式为曲线变化时，颜色变化的配置。数组类型表示当前属性可以设置多段动画，如0ms-3000ms，3000ms-5000ms，5000ms-8000ms分别设置动画。| 264 265## ParticlePropertyOptions 266```typescript 267interface ParticlePropertyOptions<TYPE, UPDATER extends ParticleUpdater> { 268 range: [TYPE, TYPE]; 269 updater?: { 270 type: UPDATER; 271 config: ParticlePropertyUpdaterConfigs<TYPE>[UPDATER]; 272 }; 273} 274``` 275 276**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 277 278**系统能力：** SystemCapability.ArkUI.ArkUI.Full 279 280| 名称 | 类型 | 必填 | 说明 | 281| -------- | -------- | -------- | -------- | 282| range | [TYPE, TYPE] | 是 | 粒子初始属性值区间，粒子发射器生成粒子的属性值在range区间随机取值。<br/>**说明**<br/>各项属性的非法输入取默认值，当最大值小于最小值的时候取默认区间。TYPE为number。<br/>不同属性的默认值不同：<br>1、opacity属性：range:[1.0,1.0]，取值范围0到1，默认值为0.0。<br/>2、scale属性：range:[1.0,1.0]，取值范围大于等于0，默认值为1.0。<br/>3、acceleration加速度speed属性：range:[0.0,0.0]，取值范围大于等于0，默认值为0.0。<br/>4、acceleration加速度angle属性：range:[0.0,0.0]，取值范围为(-∞, +∞) ，默认值为0.0。<br/>5、spin属性：range:[0.0,0.0]，默认值为0.0。 283| updater | {type: [UPDATER](#particleupdater);config: [ParticlePropertyUpdaterConfigs](#particlepropertyupdaterconfigs)[UPDATER]} | 否 | 属性变化配置。属性变化类型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。| 284 285 286## ParticlePropertyUpdaterConfigs 287```typescript 288interface ParticlePropertyUpdaterConfigs<T> { 289 [ParticleUpdater.NONE]: void; 290 [ParticleUpdater.RANDOM]: [T, T]; 291 [ParticleUpdater.CURVE]: Array<ParticlePropertyAnimation<T>>; 292} 293``` 294 295**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 296 297**系统能力：** SystemCapability.ArkUI.ArkUI.Full 298 299| 名称 | 类型 | 必填 | 说明 | 300| -------- | -------- | -------- | -------- | 301[[ParticleUpdater.NONE]|void | 是 | 无变化。| 302| [ParticleUpdater.RANDOM] | [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。| 303|[ParticleUpdater.CURVE]|Array<[ParticlePropertyAnimation](#particlepropertyanimation)\<T\>> | 是 | 表示变化方式为曲线变化时，属性变化的配置。数组类型表示当前属性可以设置多段动画，如0ms-3000ms，3000ms-5000ms，5000ms-8000ms分别设置动画。T为number。| 304 305 306 307## ParticlePropertyAnimation 308```typescript 309interface ParticlePropertyAnimation<T> { 310 from: T; 311 to: T; 312 startMillis: number; 313 endMillis: number; 314 curve?: Curve | ICurve; 315} 316``` 317 318**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 319 320**系统能力：** SystemCapability.ArkUI.ArkUI.Full 321 322| 名称 | 类型 | 必填 | 说明 | 323| -------- | -------- | -------- | -------- | 324|from| T | 是 | 属性起始值。非法输入取对应属性的默认值。| 325| to | T | 是 | 属性目标值。非法输入取对应属性的默认值。| 326|startMillis|number | 是 | 动画开始时间。| 327|endMillis|number | 是 | 动画结束时间。| 328|curve|[Curve](ts-appendix-enums.md#curve) \| [ICurve](../js-apis-curve.md#icurve)| 否 | 设置动画曲线。<br>默认值：Curve.Linear| 329 330 331## ParticleType 332```typescript 333enum ParticleType { 334 POINT = 'point', 335 IMAGE = 'image', 336} 337``` 338**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 339 340**系统能力：** SystemCapability.ArkUI.ArkUI.Full 341 342| 名称 | 描述 | 343| -------- | -------- | 344POINT |点状粒子| 345IMAGE | 图片粒子| 346 347 348 349## ParticleEmitterShape 350```typescript 351enum ParticleEmitterShape { 352 RECTANGLE = 'rectangle', 353 CIRCLE = 'circle', 354 ELLIPSE = 'ellipse', 355} 356``` 357 358**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 359 360**系统能力：** SystemCapability.ArkUI.ArkUI.Full 361 362| 名称 | 描述 | 363| -------- | -------- | 364RECTANGLE |粒子发射器为矩形| 365CIRCLE | 粒子发射器为圆形| 366ELLIPSE |粒子发射器为椭圆形| 367 368## DistributionType<sup>12+<sup> 369```typescript 370enum DistributionType { 371 UNIFORM = 0, 372 GAUSSIAN = 1, 373} 374``` 375**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 376 377**系统能力：** SystemCapability.ArkUI.ArkUI.Full 378 379| 名称 | 描述 | 380| -------- | -------- | 381| UNIFORM |初始颜色随机值分布为均匀分布。| 382| GAUSSIAN | 初始颜色随机值分布为高斯分布。| 383 384## ParticleUpdater 385```typescript 386enum ParticleUpdater { 387 NONE = 'none', 388 RANDOM = 'random', 389 CURVE = 'curve', 390} 391``` 392 393**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 394 395**系统能力：** SystemCapability.ArkUI.ArkUI.Full 396 397| 名称 | 描述 | 398| -------- | -------- | 399|NONE |无变化| 400|RANDOM | 随机变化| 401|CURVE |动画曲线变化| 402 403## DisturbanceFieldOptions<sup>12+</sup> 404 405**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 406 407**系统能力：** SystemCapability.ArkUI.ArkUI.Full 408 409| 名称 | 类型 | 必填 | 说明 | 410| ------ | ------- | ---- | ---------------------------- | 411| strength | number | 否 |场强，表示场从中心向外的排斥力的强度，默认值0。正数表示排斥力方向朝外，负数表示吸引力，方向朝内。 | 412| shape | [DisturbanceFieldShape](#disturbancefieldshape12) | 否 | 场的形状。<br/>默认为DisturbanceFieldShape.RECT。 | 413| size | [SizeT](../js-apis-arkui-graphics.md#sizett12)<number>| 否 |场的大小。<br/>默认值 {width:0，height:0}。 | 414| position | [PositionT](../js-apis-arkui-graphics.md#positiont12)<number> | 否 |场的位置。<br/>默认值{x:0，y:0}。 | 415| feather | number | 否 |羽化值，表示场从中心点到场边缘的衰减程度，取值范围0到100的整数，如果0则表示场是一个刚体，所有范围内的粒子都被排斥在外。羽化值越大场的缓和程度越大，场范围内出现越多靠近中心点的粒子。<br/>默认值为0。 | 416| noiseScale | number | 否 |噪声尺度，用于控制噪声图案的整体大小，取值大于等于0。<br/>默认值1。 | 417| noiseFrequency | number | 否 |噪声频率，频率越大噪声越细腻，取值大于等于0。<br/> 默认值1。 | 418| noiseAmplitude | number | 否 |噪声震幅，噪声的波动的范围，震幅越大噪音之间差异越大。取值大于等于0。<br/> 默认值1。 | 419 420## DisturbanceFieldShape<sup>12+</sup> 421 422**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 423 424**系统能力：** SystemCapability.ArkUI.ArkUI.Full 425 426| 名称 | 描述 | 427| --------| ----------| 428| RECT | 长方形。 | 429| CIRCLE | 圆。 | 430| ELLIPSE | 椭圆。 | 431 432## EmitterProperty<sup>12+</sup> 433 434**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 435 436**系统能力：** SystemCapability.ArkUI.ArkUI.Full 437 438| 名称 | 类型 | 必填 | 说明 | 439| ------ | ------- | ---- | ---------------------------- | 440| index | number | 是 |索引，取整，按初始化参数中发射器的数组索引指定对应的发射器。异常默认值为0。 | 441| emitRate | number | 否 | 发射器发射速率，即每秒发射粒子的数量。<br/>未传入时保持其当前的发射速率， 传入值小于0时取默认值5。emitRate值超过5000时会极大影响性能，建议设置参数小于5000。 | 442| position | [PositionT](../js-apis-arkui-graphics.md#positiont12)<number> | 否 |发射器位置的数组，只支持number类型。<br/>未传入时保持其当前的发射器位置。需传入两个有效参数，若其中一个为异常值，则position不生效。 | 443| size | [SizeT](../js-apis-arkui-graphics.md#sizett12)<number>| 否 |发射窗口的大小，只支持number类型。<br/>未传入时保持其当前发射窗口大小。需传入两个有效参数且都大于0，若其中一个为异常值，则size不生效。 | 444 445## 示例 446 447### 示例1 448 449描述粒子动画基础用法，通过圆形初始化粒子。 450 451```ts 452// xxx.ets 453@Entry 454@Component 455struct ParticleExample { 456 build() { 457 Stack() { 458 Text() 459 .width(300).height(300).backgroundColor(Color.Black) 460 Particle({particles:[ 461 { 462 emitter:{ 463 particle:{ 464 type:ParticleType.POINT,//粒子类型 465 config:{ 466 radius:10//圆点半径 467 }, 468 count: 500,//粒子总数 469 lifetime:10000,//粒子生命周期，单位ms 470 lifetimeRange:100//粒子生命周期取值范围，单位ms 471 }, 472 emitRate:10,//每秒发射粒子数 473 position:[0,0], 474 shape:ParticleEmitterShape.RECTANGLE//发射器形状 475 }, 476 color:{ 477 range:[Color.Red,Color.Yellow],//初始颜色范围 478 updater:{ 479 type:ParticleUpdater.CURVE,//变化方式为曲线变化 480 config:[ 481 { 482 from:Color.White,//变化起始值 483 to:Color.Pink,//变化终点值 484 startMillis:0,//开始时间 485 endMillis:3000,//结束时间 486 curve:Curve.EaseIn//变化曲线 487 }, 488 { 489 from:Color.Pink, 490 to:Color.Orange, 491 startMillis:3000, 492 endMillis:5000, 493 curve:Curve.EaseIn 494 }, 495 { 496 from:Color.Orange, 497 to:Color.Pink, 498 startMillis:5000, 499 endMillis:8000, 500 curve:Curve.EaseIn 501 }, 502 ] 503 } 504 }, 505 opacity:{ 506 range:[0.0,1.0],//粒子透明度的初始值从【0.0到1.0】随机产生 507 updater:{ 508 type:ParticleUpdater.CURVE, 509 config:[ 510 { 511 from:0.0, 512 to:1.0, 513 startMillis:0, 514 endMillis:3000, 515 curve:Curve.EaseIn 516 }, 517 { 518 from:1.0, 519 to:0.0, 520 startMillis:5000, 521 endMillis:10000, 522 curve:Curve.EaseIn 523 } 524 ] 525 } 526 }, 527 scale:{ 528 range:[0.0,0.0], 529 updater:{ 530 type:ParticleUpdater.CURVE, 531 config:[ 532 { 533 from:0.0, 534 to:0.5, 535 startMillis:0, 536 endMillis:3000, 537 curve: Curve.EaseIn 538 } 539 ] 540 } 541 }, 542 acceleration:{//加速度的配置，从大小和方向两个维度变化，speed表示加速度大小，angle表示加速度方向 543 speed:{ 544 range:[3,9], 545 updater:{ 546 type:ParticleUpdater.RANDOM,//Speed的变化方式是随机变化 547 config:[1,20] 548 } 549 }, 550 angle:{ 551 range:[90,90] 552 } 553 } 554 555 } 556 ] 557 }).width(300).height(300) 558 }.width("100%").height("100%").align(Alignment.Center) 559 } 560} 561``` 562 563 564 565### 示例2 566 567描述粒子动画基础用法，通过图片初始化粒子。 568 569```ts 570@Entry 571@Component 572struct ParticleExample { 573 @State 574 myCount : number = 100 575 flag : boolean = false; 576 build() { 577 Column(){ 578 Stack() { 579 Particle({particles:[ 580 { 581 emitter:{ 582 particle:{ 583 type:ParticleType.IMAGE, 584 config:{ 585 src:$r("app.media.book"), 586 size:[10,10] 587 }, 588 count: this.myCount, 589 lifetime:10000, 590 lifetimeRange:100 591 }, 592 emitRate:3, 593 shape:ParticleEmitterShape.CIRCLE 594 }, 595 color:{ 596 range:[Color.White,Color.White] 597 }, 598 opacity:{ 599 range:[1.0,1.0], 600 updater:{ 601 type:ParticleUpdater.CURVE, 602 config:[ 603 { 604 from:0, 605 to:1.0, 606 startMillis:0, 607 endMillis:6000 608 }, 609 { 610 from:1.0, 611 to:.0, 612 startMillis:6000, 613 endMillis:10000 614 } 615 ] 616 } 617 }, 618 scale:{ 619 range:[0.1,1.0], 620 updater:{ 621 type:ParticleUpdater.CURVE, 622 config:[ 623 { 624 from: 0, 625 to: 1.5, 626 startMillis: 0, 627 endMillis: 8000, 628 curve: Curve.EaseIn 629 } 630 631 ] 632 } 633 }, 634 acceleration:{ 635 speed:{ 636 range:[3,9], 637 updater:{ 638 type: ParticleUpdater.CURVE, 639 config:[ 640 { 641 from:10, 642 to:20, 643 startMillis:0, 644 endMillis:3000, 645 curve:Curve.EaseIn 646 }, 647 { 648 from:10, 649 to:2, 650 startMillis:3000, 651 endMillis:8000, 652 curve:Curve.EaseIn 653 } 654 ] 655 } 656 }, 657 angle:{ 658 range:[0,180], 659 updater:{ 660 type:ParticleUpdater.CURVE, 661 config:[{ 662 from:1, 663 to:2, 664 startMillis:0, 665 endMillis:1000, 666 curve:Curve.EaseIn 667 }, 668 { 669 from:50, 670 to:-50, 671 startMillis:1000, 672 endMillis:3000, 673 curve:Curve.EaseIn 674 }, 675 { 676 from:3, 677 to:5, 678 startMillis:3000, 679 endMillis:8000, 680 curve:Curve.EaseIn 681 } 682 ] 683 } 684 } 685 }, 686 spin:{ 687 range:[0.1,1.0], 688 updater:{ 689 type:ParticleUpdater.CURVE, 690 config:[ 691 { 692 from: 0, 693 to: 360, 694 startMillis: 0, 695 endMillis: 8000, 696 curve: Curve.EaseIn 697 } 698 ] 699 } 700 }, 701 } 702 ,{ 703 emitter:{ 704 particle:{ 705 type:ParticleType.IMAGE, 706 config:{ 707 src:$r('app.media.heart'), 708 size:[10,10] 709 }, 710 count: this.myCount, 711 lifetime:10000, 712 lifetimeRange:100 713 }, 714 emitRate:3, 715 shape:ParticleEmitterShape.CIRCLE 716 }, 717 color:{ 718 range:[Color.White,Color.White] 719 }, 720 opacity:{ 721 range:[1.0,1.0], 722 updater:{ 723 type:ParticleUpdater.CURVE, 724 config:[ 725 { 726 from:0, 727 to:1.0, 728 startMillis:0, 729 endMillis:6000 730 }, 731 { 732 from:1.0, 733 to:.0, 734 startMillis:6000, 735 endMillis:10000 736 } 737 ] 738 } 739 }, 740 scale:{ 741 range:[0.1,1.0], 742 updater:{ 743 type:ParticleUpdater.CURVE, 744 config:[ 745 { 746 from: 0, 747 to: 2.0, 748 startMillis: 0, 749 endMillis: 10000, 750 curve: Curve.EaseIn 751 } 752 753 ] 754 } 755 }, 756 acceleration:{ 757 speed:{ 758 range:[3,9], 759 updater:{ 760 type: ParticleUpdater.CURVE, 761 config:[ 762 { 763 from:10, 764 to:20, 765 startMillis:0, 766 endMillis:3000, 767 curve:Curve.EaseIn 768 }, 769 { 770 from:10, 771 to:2, 772 startMillis:3000, 773 endMillis:8000, 774 curve:Curve.EaseIn 775 } 776 ] 777 } 778 }, 779 angle:{ 780 range:[0,180], 781 updater:{ 782 type:ParticleUpdater.CURVE, 783 config:[{ 784 from:1, 785 to:2, 786 startMillis:0, 787 endMillis:1000, 788 curve:Curve.EaseIn 789 }, 790 { 791 from:50, 792 to:-50, 793 startMillis:0, 794 endMillis:3000, 795 curve:Curve.EaseIn 796 }, 797 { 798 from:3, 799 to:5, 800 startMillis:3000, 801 endMillis:10000, 802 curve:Curve.EaseIn 803 } 804 ] 805 } 806 } 807 }, 808 spin:{ 809 range:[0.1,1.0], 810 updater:{ 811 type:ParticleUpdater.CURVE, 812 config:[ 813 { 814 from: 0, 815 to: 360, 816 startMillis: 0, 817 endMillis: 10000, 818 curve: Curve.EaseIn 819 } 820 ] 821 } 822 }, 823 },{ 824 emitter:{ 825 particle:{ 826 type:ParticleType.IMAGE, 827 config:{ 828 src:$r('app.media.sun'), 829 size:[10,10] 830 }, 831 count: this.myCount, 832 lifetime:10000, 833 lifetimeRange:100 834 }, 835 emitRate:3, 836 shape:ParticleEmitterShape.CIRCLE 837 }, 838 color:{ 839 range:[Color.White,Color.White] 840 }, 841 opacity:{ 842 range:[1.0,1.0], 843 updater:{ 844 type:ParticleUpdater.CURVE, 845 config:[ 846 { 847 from:0, 848 to:1.0, 849 startMillis:0, 850 endMillis:6000 851 }, 852 { 853 from:1.0, 854 to:.0, 855 startMillis:6000, 856 endMillis:10000 857 } 858 ] 859 } 860 }, 861 scale:{ 862 range:[0.1,1.0], 863 updater:{ 864 type:ParticleUpdater.CURVE, 865 config:[ 866 { 867 from: 0, 868 to: 2.0, 869 startMillis: 0, 870 endMillis: 10000, 871 curve: Curve.EaseIn 872 } 873 874 ] 875 } 876 }, 877 acceleration:{ 878 speed:{ 879 range:[3,9], 880 updater:{ 881 type: ParticleUpdater.CURVE, 882 config:[ 883 { 884 from:10, 885 to:20, 886 startMillis:0, 887 endMillis:3000, 888 curve:Curve.EaseIn 889 }, 890 { 891 from:10, 892 to:2, 893 startMillis:3000, 894 endMillis:8000, 895 curve:Curve.EaseIn 896 } 897 ] 898 } 899 }, 900 angle:{ 901 range:[0,180], 902 updater:{ 903 type:ParticleUpdater.CURVE, 904 config:[{ 905 from:1, 906 to:2, 907 startMillis:0, 908 endMillis:1000, 909 curve:Curve.EaseIn 910 }, 911 { 912 from:50, 913 to:-50, 914 startMillis:1000, 915 endMillis:3000, 916 curve:Curve.EaseIn 917 }, 918 { 919 from:3, 920 to:5, 921 startMillis:3000, 922 endMillis:8000, 923 curve:Curve.EaseIn 924 } 925 ] 926 } 927 } 928 }, 929 spin:{ 930 range:[0.1,1.0], 931 updater:{ 932 type:ParticleUpdater.CURVE, 933 config:[ 934 { 935 from: 0, 936 to: 360, 937 startMillis: 0, 938 endMillis: 10000, 939 curve: Curve.EaseIn 940 } 941 ] 942 } 943 }, 944 } 945 ] 946 }).width(300).height(300) 947 948 }.width(500).height(500).align(Alignment.Center) 949 }.width("100%").height("100%") 950 951 } 952} 953``` 954 955 956### 示例3 957 958粒子扰动场的干扰下运动轨迹发生变化。 959``` 960@Entry 961@Component 962struct ParticleExample { 963 build() { 964 Stack() { 965 Text() 966 .width(300).height(300).backgroundColor(Color.Black) 967 Particle({particles:[ 968 { 969 emitter:{ 970 particle:{ 971 type:ParticleType.POINT,//粒子类型 972 config:{ 973 radius:10//圆点半径 974 }, 975 count: 500,//粒子总数 976 lifetime:10000//粒子生命周期，单位ms 977 }, 978 emitRate:10,//每秒发射粒子数 979 position:[0,0], 980 shape:ParticleEmitterShape.RECTANGLE//发射器形状 981 }, 982 color:{ 983 range:[Color.Red,Color.Yellow],//初始颜色范围 984 updater:{ 985 type:ParticleUpdater.CURVE,//变化方式为曲线变化 986 config:[ 987 { 988 from:Color.White,//变化起始值 989 to:Color.Pink,//变化终点值 990 startMillis:0,//开始时间 991 endMillis:3000,//结束时间 992 curve:Curve.EaseIn//变化曲线 993 }, 994 { 995 from:Color.Pink, 996 to:Color.Orange, 997 startMillis:3000, 998 endMillis:5000, 999 curve:Curve.EaseIn 1000 }, 1001 { 1002 from:Color.Orange, 1003 to:Color.Pink, 1004 startMillis:5000, 1005 endMillis:8000, 1006 curve:Curve.EaseIn 1007 }, 1008 ] 1009 } 1010 }, 1011 opacity:{ 1012 range:[0.0,1.0],//粒子透明度的初始值从[0.0,1.0]随机产生 1013 updater:{ 1014 type:ParticleUpdater.CURVE, 1015 config:[ 1016 { 1017 from:0.0, 1018 to:1.0, 1019 startMillis:0, 1020 endMillis:3000, 1021 curve:Curve.EaseIn 1022 }, 1023 { 1024 from:1.0, 1025 to:0.0, 1026 startMillis:5000, 1027 endMillis:10000, 1028 curve:Curve.EaseIn 1029 } 1030 ] 1031 } 1032 }, 1033 scale:{ 1034 range:[0.0,0.0], 1035 updater:{ 1036 type:ParticleUpdater.CURVE, 1037 config:[ 1038 { 1039 from:0.0, 1040 to:0.5, 1041 startMillis:0, 1042 endMillis:3000, 1043 curve: Curve.EaseIn 1044 } 1045 ] 1046 } 1047 }, 1048 acceleration:{//加速度的配置，从大小和方向两个维度变化，speed表示加速度大小，angle表示加速度方向 1049 speed:{ 1050 range:[3,9], 1051 updater:{ 1052 type:ParticleUpdater.RANDOM, 1053 config:[1,20] 1054 } 1055 }, 1056 angle:{ 1057 range:[90,90] 1058 } 1059 } 1060 1061 } 1062 ] 1063 }).width(300).height(300).disturbanceFields([{ 1064 strength:10, 1065 shape:DisturbanceFieldShape.RECT, 1066 size:{width:100,height:100}, 1067 position:{x:100,y:100}, 1068 feather:15, 1069 noiseScale:10, 1070 noiseFrequency:15, 1071 noiseAmplitude:5 1072 }]) 1073 }.width("100%").height("100%").align(Alignment.Center) 1074 } 1075} 1076 1077``` 1078 1079 1080### 示例4 1081通过emitter()调整粒子发射器的位置。 1082```ts 1083@Entry 1084@Component 1085struct ParticleExample { 1086 @State emitterProperties: Array<EmitterProperty> = [ 1087 { 1088 index: 0, 1089 emitRate: 100, 1090 position: { x: 60, y: 80 }, 1091 size: { width: 200, height: 200 } 1092 } 1093 ] 1094 1095 build() { 1096 Stack() { 1097 Text() 1098 .width(300).height(300).backgroundColor(Color.Black) 1099 Particle({ particles: [ 1100 { 1101 emitter: { 1102 particle: { 1103 type: ParticleType.POINT, // 粒子类型 1104 config: { 1105 radius: 5// 圆点半径 1106 }, 1107 count: 400, // 粒子总数 1108 lifetime: -1// 粒子的生命周期，-1表示粒子生命周期无限大 1109 }, 1110 emitRate: 10, // 每秒发射粒子数 1111 position: [0, 0], // 粒子发射位置 1112 shape: ParticleEmitterShape.CIRCLE// 发射器形状 1113 }, 1114 color: { 1115 range: [Color.Red, Color.Yellow], // 初始颜色范围 1116 updater: { 1117 type: ParticleUpdater.CURVE, // 变化方式为曲线变化 1118 config: [ 1119 { 1120 from: Color.White, 1121 to: Color.Pink, 1122 startMillis: 0, 1123 endMillis: 3000, 1124 curve: Curve.EaseIn 1125 }, 1126 { 1127 from: Color.Pink, 1128 to: Color.Orange, 1129 startMillis: 3000, 1130 endMillis: 5000, 1131 curve: Curve.EaseIn 1132 }, 1133 { 1134 from: Color.Orange, 1135 to: Color.Pink, 1136 startMillis: 5000, 1137 endMillis: 8000, 1138 curve: Curve.EaseIn 1139 }, 1140 ] 1141 } 1142 }, 1143 }, 1144 ] 1145 }) 1146 .width(300) 1147 .height(300) 1148 .emitter(this.emitterProperties) 1149 }.width("100%").height("100%").align(Alignment.Center) 1150 } 1151} 1152``` 1153
