1# @ohos.graphics.uiEffect (效果级联)(系统接口) 2 3<!--Kit: ArkGraphics 2D--> 4<!--Subsystem: Graphics--> 5<!--Owner: @hanamaru--> 6<!--Designer: @comicchang--> 7<!--Tester: @gcw_fsLqk7gL--> 8<!--Adviser: @ge-yafang--> 9 10本模块提供组件效果的一些基础能力，包括模糊、边缘像素扩展、提亮等。效果被分为Filter和VisualEffect大类，同类效果可以级联在一个效果大类的实例下。在实际开发中，模糊可用于背景虚化，提亮可用于亮屏显示等。 11 12- [Filter](#filter)：用于添加指定Filter效果到组件上。 13- [VisualEffect](#visualeffect)：用于添加指定VisualEffect效果到组件上。 14 15> **说明：** 16> 17> - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 18> - 页面仅包含本模块的系统接口，其他公开接口参见[ohos.graphics.uiEffect (效果级联)](js-apis-uiEffect.md)。 19 20## 导入模块 21 22```ts 23import { uiEffect } from "@kit.ArkGraphics2D"; 24``` 25## uiEffect.createBrightnessBlender 26createBrightnessBlender(param: BrightnessBlenderParam): BrightnessBlender 27 28创建BrightnessBlender实例用于给组件添加提亮效果。 29 30**系统能力：** SystemCapability.Graphics.Drawing 31 32**系统接口：** 此接口为系统接口。 33 34**参数：** 35| 参数名 | 类型 | 必填 | 说明 | 36| ------ | ------------------------------------------------- | ---- | --------------------------- | 37| param | [BrightnessBlenderParam](#brightnessblenderparam) | 是 | 实现提亮效果的参数。 | 38 39**返回值：** 40 41| 类型 | 说明 | 42| ---------------------------------------- | ----------------------- | 43| [BrightnessBlender](#brightnessblender) | 返回设置了提亮效果参数的BrightnessBlender。 | 44 45**示例：** 46 47```ts 48let blender : uiEffect.BrightnessBlender = 49 uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 50 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 51``` 52 53## uiEffect.createHdrBrightnessBlender<sup>20+</sup> 54createHdrBrightnessBlender(param: BrightnessBlenderParam): HdrBrightnessBlender 55 56创建[HdrBrightnessBlender](#hdrbrightnessblender20)实例用于给组件添加支持HDR的提亮效果。 57 58**系统能力：** SystemCapability.Graphics.Drawing 59 60**系统接口：** 此接口为系统接口。 61 62**参数：** 63| 参数名 | 类型 | 必填 | 说明 | 64| ------ | ------------------------------------------------- | ---- | --------------------------- | 65| param | [BrightnessBlenderParam](#brightnessblenderparam) | 是 | 实现提亮效果的参数。 | 66 67**返回值：** 68 69| 类型 | 说明 | 70| ---------------------------------------- | ----------------------- | 71| [HdrBrightnessBlender](#hdrbrightnessblender20) | 返回具有提亮效果的混合器（支持HDR）。 | 72 73**示例：** 74 75```ts 76import { uiEffect } from "@kit.ArkGraphics2D" 77 78let blender : uiEffect.HdrBrightnessBlender = 79 uiEffect.createHdrBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 80 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 81 82@Entry 83@Component 84struct example { 85 build() { 86 RelativeContainer() { 87 Image($r("app.media.screenshot")) 88 .width("100%") 89 .height("100%") 90 .advancedBlendMode(blender) 91 } 92 } 93} 94``` 95 96## Filter 97Filter效果类，用于将相应的效果添加到指定的组件上。在调用Filter的方法前，需要先通过[createFilter](js-apis-uiEffect.md#uieffectcreatefilter)创建一个Filter实例。 98 99### pixelStretch 100pixelStretch(stretchSizes: Array\<number\>, tileMode: TileMode): Filter 101 102将边缘像素扩展效果添加至组件上。 103 104**系统能力：** SystemCapability.Graphics.Drawing 105 106**系统接口：** 此接口为系统接口。 107 108**参数：** 109| 参数名 | 类型 | 必填 | 说明 | 110| ------------- | --------------------- | ---- | ------------------------- | 111| stretchSizes | Array\<number\> | 是 | 上下左右四个方向边缘像素扩展的百分比比例，取值范围为[-1, 1]。<br/>正值表示向外扩展，上下左右四个方向分别用指定原图比例的边缘像素填充。负值表示内缩，但是最终图像大小不变。<br/>注意四个方向对应的参数需统一为非正值或非负值。| 112| tileMode | [TileMode](#tilemode) | 是 | 边缘像素扩展的像素填充模式。 | 113 114 115**返回值：** 116 117| 类型 | 说明 | 118| ----------------- | --------------------------------- | 119| [Filter](#filter) | 返回挂载了边缘像素扩展效果的Filter。 | 120 121**示例：** 122 123```ts 124filter.pixelStretch([0.2, 0.2, 0.2, 0.2], uiEffect.TileMode.CLAMP) 125``` 126 127### waterRipple 128waterRipple(progress: number, waveCount: number, x: number, y: number, rippleMode: WaterRippleMode): Filter 129 130将水波纹效果添加至组件上。 131 132**系统能力：** SystemCapability.Graphics.Drawing 133 134**系统接口：** 此接口为系统接口。 135 136**参数：** 137| 参数名 | 类型 | 必填 | 说明 | 138| ------------- | --------------------- | ---- | ------------------------- | 139| progress | number | 是 | 表示水波纹的进度，取值范围为[0, 1]。<br/>水波纹进度越趋向于1，水波纹展示越完全。<br/>超出取值范围水波纹不会出现效果。| 140| waveCount | number | 是 | 水波纹波动时波纹的个数，取值范围为[1, 3]。<br/>水波纹的个数只能取整数，如果为浮点数或超出取值范围，水波纹不会出现效果。 | 141| x | number | 是 | 水波纹中心在屏幕中第一次出现的x轴位置。<br/>水波纹对屏幕进行归一化处理，左上角的坐标为（0, 0），右上角坐标为（1, 0）。<br/>当x取值为负值时，代表在屏幕左侧。| 142| y | number | 是 | 水波纹中心在屏幕中第一次出现的y轴位置。<br/>水波纹对屏幕进行归一化处理，左上角的坐标为（0, 0），左下角坐标为（0, 1）。<br/>当y取值为负值时，代表在屏幕上方。 | 143| rippleMode | [WaterRippleMode](#waterripplemode) | 是 | 水波纹的场景模式。| 144 145 146**返回值：** 147 148| 类型 | 说明 | 149| ----------------- | --------------------------------- | 150| [Filter](#filter) | 返回挂载了水波纹效果的Filter。 | 151 152**错误码：** 153 154以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 155 156| 错误码ID | 错误信息 | 157| ------- | -------------------------------- | 158| 202 | Permission verification failed. A non-system application calls a system API. | 159 160**示例：** 161 162```ts 163filter.waterRipple(0.5, 2, 0.5, 0.5, uiEffect.WaterRippleMode.SMALL2SMALL) 164``` 165 166### flyInFlyOutEffect 167flyInFlyOutEffect(degree: number, flyMode: FlyMode): Filter 168 169将飞入飞出形变效果添加至组件上。 170 171**系统能力：** SystemCapability.Graphics.Drawing 172 173**系统接口：** 此接口为系统接口。 174 175**参数：** 176| 参数名 | 类型 | 必填 | 说明 | 177| ------------- | --------------------- | ---- | ------------------------- | 178| degree | number | 是 | 表示控制飞入飞出形变的程度，取值范围为[0, 1]。<br/>越靠近1，变形程度越明显。<br/>超出取值范围形变不会出现效果。| 179| flyMode | [FlyMode](#flymode) | 是 | 飞入飞出的场景模式。<br/>BOTTOM表示从设备底部飞入飞出形变场景。<br/>TOP表示从设备顶部飞入飞出形变场景。 | 180 181 182**返回值：** 183 184| 类型 | 说明 | 185| ----------------- | --------------------------------- | 186| [Filter](#filter) | 返回挂载了飞入飞出形变效果的Filter。 | 187 188**错误码：** 189 190以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 191 192| 错误码ID | 错误信息 | 193| ------- | -------------------------------- | 194| 202 | Permission verification failed. A non-system application calls a system API. | 195 196**示例：** 197 198```ts 199filter.flyInFlyOutEffect(0.5, uiEffect.FlyMode.TOP) 200``` 201 202### distort<sup>13+</sup> 203distort(distortionK: number): Filter 204 205将透镜畸变效果添加至组件上。 206 207**系统能力：** SystemCapability.Graphics.Drawing 208 209**系统接口：** 此接口为系统接口。 210 211**参数：** 212| 参数名 | 类型 | 必填 | 说明 | 213| ------------- | --------------------- | ---- | ------------------------- | 214| distortionK | number | 是 | 畸变系数，表示透镜畸变的程度，取值范围为[-1, 1]。畸变系数设置小于-1的值时，按值为-1处理；设置大于1的值时，按值为1处理。| 215 216 217如上图是对图片组件分别设置畸变参数为-1，0，0.5，1的绘制结果。畸变参数小于0时，效果为桶形畸变；大于0时，效果为枕形畸变；越接近0时，畸变程度越小，等于0时，没有畸变效果。 218 219**返回值：** 220 221| 类型 | 说明 | 222| ----------------- | --------------------------------- | 223| [Filter](#filter) | 返回挂载了透镜畸变效果的Filter。 | 224 225**错误码：** 226 227以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 228 229| 错误码ID | 错误信息 | 230| ------- | --------------------------------------------| 231| 202 | Permission verification failed. A non-system application calls a system API. | 232 233**示例：** 234 235```ts 236filter.distort(-0.5) 237``` 238 239 240### radiusGradientBlur<sup>19+</sup> 241radiusGradientBlur(value: number, options: LinearGradientBlurOptions): Filter 242 243为组件内容添加半径线性渐变模糊效果。 244 245**系统能力：** SystemCapability.Graphics.Drawing 246 247**系统接口：** 此接口为系统接口。 248 249**参数：** 250| 参数名 | 类型 | 必填 | 说明 | 251| ------------- | --------------------- | ---- | ------------------------- | 252| value | number | 是 | 模糊半径，模糊半径越大越模糊。取值范围为[0, 128]。模糊半径设置为0时不模糊；模糊半径设置小于0的值时，按值为0处理；设置大于128的值时，按值为128处理。| 253| options | [LinearGradientBlurOptions](../apis-arkui/arkui-ts/ts-universal-attributes-image-effect.md#lineargradientbluroptions12对象说明) | 是 | 线性渐变参数，包含两个部分fractionStops和direction。| 254 255**返回值：** 256 257| 类型 | 说明 | 258| ----------------- | --------------------------------- | 259| [Filter](#filter) | 返回挂载了半径线性渐变模糊效果的Filter。 | 260 261**错误码：** 262 263以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 264 265| 错误码ID | 错误信息 | 266| ------- | --------------------------------------------| 267| 202 | Permission verification failed. A non-system application calls a system API. | 268 269**示例：** 270 271```ts 272import { uiEffect } from "@kit.ArkGraphics2D" 273 274@Entry 275@Component 276struct RadiusGradientBlurExample { 277 @State blurRadiusExample: number = 64 278 @State linearGradientBlurOptionsExample: LinearGradientBlurOptions = 279 {fractionStops: [[0.0, 0.0], [1.0, 1.0]], direction: GradientDirection.Bottom} 280 281 build() { 282 Column() { 283 Image($rawfile('test.png')) 284 .compositingFilter(uiEffect.createFilter().radiusGradientBlur(this.blurRadiusExample, 285 this.linearGradientBlurOptionsExample)) 286 } 287 } 288} 289``` 290 291### bezierWarp<sup>20+</sup> 292bezierWarp(controlPoints: Array<common2D.Point>): Filter 293 294将贝塞尔曲线变形的效果添加至组件上。该效果通过在图层边界上创建封闭的贝塞尔曲线，实现对图像的精准扭曲和形状调整。贝塞尔曲线共有四段，首尾顺次相连，每段包含一个顶点和两个切点。 295 296**系统能力：** SystemCapability.Graphics.Drawing 297 298**系统接口：** 此接口为系统接口。 299 300**参数：** 301| 参数名 | 类型 | 必填 | 说明 | 302| ------------- | --------------------- | ---- | ------------------------- | 303| controlPoints | Array<[common2D.Point](js-apis-graphics-common2D.md#point12)>| 是 | 12个贝塞尔形变控制点，更改控制点的位置可改变形成边缘的曲线的形状，从而扭曲图像。控制点坐标为0-1坐标系，且坐标值可大于1或小于0。| 304 305**返回值：** 306 307| 类型 | 说明 | 308| ----------------- | --------------------------------- | 309| [Filter](#filter) | 返回挂载了贝塞尔曲线变形效果的Filter。 | 310 311**错误码：** 312 313以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 314 315| 错误码ID | 错误信息 | 316| ------- | --------------------------------------------| 317| 202 | Permission verification failed. A non-system application calls a system API. | 318 319**示例：** 320 321```ts 322import uiEffect from '@ohos.graphics.uiEffect' 323import {common2D} from '@kit.ArkGraphics2D' 324@Entry 325@Component 326struct BezierWarpExample { 327 @State valueBezier: Array<common2D.Point> = [ 328 {x: 0, y: 0}, {x: 1/3, y: 0}, {x: 2/3, y: 0}, // top edge 329 {x: 0.5, y: 0}, {x: 0.5, y: 1/3}, {x: 1, y: 2/3}, // right edge 330 {x: 1, y: 1}, {x: 2/3, y: 1}, {x: 1/3, y: 1}, // bottom edge 331 {x: 0, y: 1}, {x: 0, y: 2/3}, {x: 0, y: 1/3}] // left edge 332 333 build() { 334 Column() { 335 Image('test.jpg') 336 .foregroundFilter(uiEffect.createFilter().bezierWarp(this.valueBezier)) 337 } 338 } 339} 340``` 341 342### colorGradient<sup>20+</sup> 343colorGradient(colors: Array\<Color>, positions: Array\<common2D.Point>, strengths: Array\<number>, alphaMask?: Mask): Filter 344 345为组件内容添加颜色渐变效果。 346 347**系统能力：** SystemCapability.Graphics.Drawing 348 349**系统接口：** 此接口为系统接口。 350 351**参数：** 352| 参数名 | 类型 | 必填 | 说明 | 353| ------------- | --------------------- | ---- | ------------------------- | 354| colors | Array\<[Color](#color20)> | 是 | 颜色数组，多个颜色的渐变。数组长度取值范围[0, 12], 每一个颜色值取值范围为大于等于0。数组长度等于0或大于12时无效果，colors、positions和strengths的数组长度不相等时无效果。| 355| positions | Array\<[common2D.Point](js-apis-graphics-common2D.md#point12)> | 是 | 位置数组，颜色对应的分布位置。数组长度取值范围[0, 12]。数组长度等于0或大于12时无效果，colors、positions和strengths的数组长度不相等时无效果。| 356| strengths | Array\<number> | 是 | 强度数组，颜色对应的扩散强度。数组长度取值范围[0, 12], 每一个强度值取值范围为大于等于0。数组长度等于0或大于12时无效果，colors、positions和strengths的数组长度不相等时无效果。| 357| alphaMask | [Mask](#mask20) | 否 | 遮罩alpha，颜色对应的alpha显示遮罩。不设置时，默认组件内容全部有颜色渐变效果。| 358 359**返回值：** 360 361| 类型 | 说明 | 362| ----------------- | --------------------------------- | 363| [Filter](#filter) | 返回挂载了颜色渐变效果的Filter。 | 364 365**错误码：** 366 367以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 368 369| 错误码ID | 错误信息 | 370| ------- | --------------------------------------------| 371| 202 | Permission verification failed. A non-system application calls a system API. | 372 373**示例：** 374 375```ts 376import { common2D, uiEffect } from "@kit.ArkGraphics2D" 377 378@Entry 379@Component 380struct ColorGradientExample { 381 @State colorsExample: Array<uiEffect.Color> = [ 382 {red: 1.0, green: 0.8, blue: 0.5, alpha: 0.8}, 383 {red: 1.0, green: 1.5, blue: 0.5, alpha: 1.0} 384 ] 385 386 @State positionsExample: Array<common2D.Point> = [ 387 {x: 0.2, y: 0.2}, 388 {x: 0.8, y: 0.6}] 389 390 @State strengthsExample: Array<number> = [0.3, 0.3] 391 392 build() { 393 Column() { 394 Row() 395 .width("100%") 396 .height("100%") 397 .backgroundFilter(uiEffect.createFilter().colorGradient(this.colorsExample, this.positionsExample, this.strengthsExample)) 398 } 399 } 400} 401``` 402 403### contentLight<sup>20+</sup> 404contentLight(lightPosition: common2D.Point3d, lightColor: common2D.Color, lightIntensity: number, displacementMap?: Mask): Filter 405 406为组件内容添加3D光照效果。 407 408**系统能力：** SystemCapability.Graphics.Drawing 409 410**系统接口：** 此接口为系统接口。 411 412**参数：** 413| 参数名 | 类型 | 必填 | 说明 | 414| ------------- | --------------------- | ---- | ------------------------- | 415| lightPosition | [common2D.Point3d](js-apis-graphics-common2D.md#point3d12) | 是 | 光源在组件空间的位置，[-1, -1, 0]为组件左上角，[1, 1, 0]为组件的右下角，z轴分量越大光源离组件平面越远，可照射区域越大。<br/> x分量取值范围[-10, 10]，y分量取值范围[-10, 10]，z分量取值范围[0, 10]，超出范围会自动截断。 | 416| lightColor | [common2D.Color](js-apis-graphics-common2D.md#color) | 是 | 光源颜色，各元素取值范围为[0, 1]，超出范围会自动截断。 | 417| lightIntensity | number | 是 | 光源强度，取值范围[0, 1]，数值越大光源亮度越大，超出范围会自动截断。| 418| displacementMap | [Mask](#mask20) | 否 | 该参数暂不生效。 | 419 420**返回值：** 421 422| 类型 | 说明 | 423| ----------------- | --------------------------------- | 424| [filter](#filter) | 返回了具有内容光照效果的filter。 | 425 426**错误码：** 427 428以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 429 430| 错误码ID | 错误信息 | 431| ------- | --------------------------------------------| 432| 202 | Permission verification failed. A non-system application calls a system API. | 433 434**示例：** 435 436```ts 437import { common2D, uiEffect } from '@kit.ArkGraphics2D' 438@Entry 439@Component 440struct Index { 441 @State point2:common2D.Point3d = { 442 x:0,y:0,z:2 443 } 444 @State color2:common2D.Color = { 445 red:1,green:1,blue:1,alpha:1 446 } 447 @State lightIntentsity2:number = 1 448 449 build() { 450 Column() { 451 Stack() { 452 Image($r('app.media.man')) 453 .width('646px') 454 .height('900px') 455 .borderRadius(10) 456 .foregroundFilter(uiEffect.createFilter().contentLight(this.point2, this.color2, this.lightIntentsity2)) 457 } 458 .width('100%') 459 .height('55%') 460 } 461 .height('100%') 462 .width('100%') 463 .justifyContent(FlexAlign.Center) 464 .backgroundColor('#555') 465 } 466} 467``` 468 469### edgeLight<sup>20+</sup> 470edgeLight(alpha: number, color?: Color, mask?: Mask, bloom?: boolean): Filter 471 472为组件内容检测边缘，并添加边缘高亮效果。 473 474**系统能力：** SystemCapability.Graphics.Drawing 475 476**系统接口：** 此接口为系统接口。 477 478**参数：** 479| 参数名 | 类型 | 必填 | 说明 | 480| ------------- | --------------------- | ---- | ------------------------- | 481| alpha | number | 是 | 指定描边高光透明度，越大描边越明显。取值范围为[0, 1]。设置为0时无描边；设置小于0的值时，按值为0处理；设置大于1的值时，按值为1处理。| 482| color | [Color](#color20) | 否 | 指定描边高光颜色，不设置时，将默认使用组件内容的原始颜色。如果有值，使用指定颜色。设置不为null时，Color中的alpha不发挥作用，仅使用rgb。| 483| mask | [Mask](#mask20) | 否 | 指定描边高光强度。不设置时，默认组件内容全部有描边高光效果。| 484| bloom | boolean | 否 | 指定描边是否发光。设置为true时，有描边和发光效果；设置为false时，只有描边效果无发光效果；不设置时，默认为true。小于16*16的图片默认只有描边效果，无发光效果，此参数失去作用。 | 485 486**返回值：** 487 488| 类型 | 说明 | 489| ----------------- | --------------------------------- | 490| [Filter](#filter) | 返回挂载了描边高光效果的Filter。 | 491 492**错误码：** 493 494以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 495 496| 错误码ID | 错误信息 | 497| ------- | --------------------------------------------| 498| 202 | Permission verification failed. A non-system application calls a system API. | 499 500**示例：** 501 502```ts 503import { uiEffect } from "@kit.ArkGraphics2D" 504 505@Entry 506@Component 507struct EdgeLightExample { 508 @State colorExample: uiEffect.Color = {red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0} 509 510 @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.5, 0.5) 511 512 build() { 513 Stack() { 514 Image($rawfile('test.png')) 515 Row() 516 .width("100%") 517 .height("100%") 518 .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, this.colorExample, this.maskExample, false)) 519 } 520 } 521} 522``` 523 524### displacementDistort<sup>20+</sup> 525displacementDistort(displacementMap: Mask, factor?: [number, number]): Filter 526 527为组件内容添加扭曲效果。 528 529**系统能力：** SystemCapability.Graphics.Drawing 530 531**系统接口：** 此接口为系统接口。 532 533**参数：** 534| 参数名 | 类型 | 必填 | 说明 | 535| ------------- | --------------------- | ---- | ------------------------- | 536| mask | [Mask](#mask20) | 是 | 指定扭曲程度。与factor相乘后共同决定扭曲程度。| 537| factor | [number, number] | 否 | 指定水平、竖直方向扭曲程度系数，系数的绝对值越大，扭曲程度越明显，建议取值范围为[-10.0, 10.0]。不设置时，默认值为1.0。设置为0时，无扭曲效果。与mask相乘后共同决定扭曲程度。 | 538 539**返回值：** 540 541| 类型 | 说明 | 542| ----------------- | --------------------------------- | 543| [Filter](#filter) | 返回挂载了扭曲效果的Filter。 | 544 545**错误码：** 546 547以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 548 549| 错误码ID | 错误信息 | 550| ------- | --------------------------------------------| 551| 202 | Permission verification failed. A non-system application calls a system API. | 552 553**示例：** 554 555```ts 556import { uiEffect } from "@kit.ArkGraphics2D" 557 558@Entry 559@Component 560struct DisplacementDistortExample { 561 @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.3, 0.0) 562 563 build() { 564 Stack() { 565 Image($rawfile('test.png')) 566 Row() 567 .width("100%") 568 .height("100%") 569 .backgroundFilter(uiEffect.createFilter().displacementDistort(this.maskExample, [5.0, 5.0])) 570 } 571 } 572} 573``` 574 575### maskDispersion<sup>20+</sup> 576maskDispersion(dispersionMask: Mask, alpha: number, rFactor?: [number, number], gFactor?: [number, number], bFactor?: [number, number]): Filter 577 578为组件内容添加由置换贴图控制的色散效果。 579 580**系统能力：** SystemCapability.Graphics.Drawing 581 582**系统接口：** 此接口为系统接口。 583 584**参数：** 585| 参数名 | 类型 | 必填 | 说明 | 586| ------------- | --------------------- | ---- | ------------------------- | 587| dispersionMask | [Mask](#mask20) | 是 | 置换贴图，用于控制色散的强度、方向和透明度。建议使用PixelMapMask类型的置换贴图。| 588| alpha | number | 是 | 色散整体透明度，透明度越小效果越透明。取值范围为[0, 1.0]。透明度设置为0时色散效果不生效；透明度设置小于0的值时，按值为0处理；设置大于1.0的值时，按值为1.0处理。| 589| rFactor | [number, number] | 否 | X/Y方向上R通道的色散基础偏移，偏移越大红色色散效果越明显。每个方向上的取值范围为[-1.0, 1.0]。偏移设置小于-1.0的值时，按值为-1.0处理；设置大于1.0的值时，按值为1.0处理。| 590| gFactor | [number, number] | 否 | X/Y方向上G通道的色散基础偏移，偏移越大绿色色散效果越明显。取值范围同rFactor。| 591| bFactor | [number, number] | 否 | X/Y方向上B通道的色散基础偏移，偏移越大蓝色色散效果越明显。取值范围同rFactor。| 592 593**返回值：** 594 595| 类型 | 说明 | 596| ----------------- | --------------------------------- | 597| [Filter](#filter) | 返回挂载了由置换贴图控制的色散效果的Filter。 | 598 599**错误码：** 600 601以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 602 603| 错误码ID | 错误信息 | 604| ------- | --------------------------------------------| 605| 202 | Permission verification failed. A non-system application calls a system API. | 606 607**示例：** 608 609```ts 610import {image} from '@kit.ImageKit' 611import {common2D, uiEffect} from '@kit.ArkGraphics2D' 612import {common} from '@kit.AbilityKit' 613 614@Entry 615@Component 616struct MaskDispersion { 617 @State pixelMap_: PixelMap | null = null 618 @State src: common2D.Rect = { left: 0, top: 0, right: 1.0, bottom: 1.0 } 619 @State dst: common2D.Rect = { left: 0, top: 0, right: 1.0, bottom: 1.0 } 620 @State fillColor: uiEffect.Color = { red: 0, green: 0, blue: 0, alpha: 0 } 621 622 onPageShow(): void { 623 let context = this.getUIContext().getHostContext() as common.UIAbilityContext 624 context.resourceManager.getMediaContent($r("app.media.mask_alpha")).then(val => { 625 let buffer = val.buffer.slice(0, val.buffer.byteLength) 626 let imageSource = image.createImageSource(buffer); 627 imageSource.createPixelMap().then(pixelMap => { 628 this.pixelMap_ = pixelMap 629 }) 630 }) 631 } 632 633 build() { 634 Stack() { 635 Image($rawfile('test.png')) 636 Row() 637 .width("100%") 638 .height("100%") 639 .backgroundFilter(uiEffect.createFilter().maskDispersion( 640 uiEffect.Mask.createPixelMapMask(this.pixelMap_, this.src, this.dst, this.fillColor), 641 1.0, 642 [0.5, -0.5], 643 [0.0, 0.0], 644 [-0.5, 0.5])) 645 } 646 } 647} 648``` 649 650### hdrBrightnessRatio<sup>20+</sup> 651hdrBrightnessRatio(ratio: number): Filter 652 653为组件内容添加HDR（高动态范围成像）提亮效果。不建议嵌套使用，强行嵌套使用可能造成过曝现象。 654 655提亮效果需要开启HDR渲染管线才能生效，某些场景下即使尝试触发HDR渲染管线也无法开启HDR，例如：设备硬件规格不支持HDR。 656 657设备当前支持最大提亮倍数为设备当前的最大亮度除以设备SDR参考白亮度得到的值。 658 659**系统能力：** SystemCapability.Graphics.Drawing 660 661**系统接口：** 此接口为系统接口。 662 663**参数：** 664| 参数名 | 类型 | 必填 | 说明 | 665| ------------- | --------------------- | ---- | ------------------------- | 666| ratio | number | 是 | 提亮倍数，取值范围为[1.0, 设备当前支持最大提亮倍数]。设置小于1.0的值时，按值为1.0处理；当值等于1.0时，不做任何处理；当值大于1.0时，会尝试触发HDR渲染管线，设置大于设备当前支持最大提亮倍数的值时，按值为设备当前支持最大提亮倍数处理。| 667 668**返回值：** 669 670| 类型 | 说明 | 671| ----------------- | --------------------------------- | 672| [Filter](#filter) | 返回挂载了HDR提亮效果的Filter。 | 673 674**错误码：** 675 676以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 677 678| 错误码ID | 错误信息 | 679| ------- | --------------------------------------------| 680| 202 | Permission verification failed. A non-system application calls a system API. | 681 682**示例：** 683 684```ts 685filter.hdrBrightnessRatio(2.0) 686``` 687 688### maskTransition<sup>20+</sup> 689maskTransition(alphaMask: Mask, factor?: number, inverse?: boolean): Filter 690 691为组件内容提供基于[Mask](#mask20)的转场效果。 692 693不建议在屏幕尺寸发生改变的过程中使用此效果，如：旋转屏幕，折叠屏开合屏幕等。 694 695**系统能力：** SystemCapability.Graphics.Drawing 696 697**系统接口：** 此接口为系统接口。 698 699**参数：** 700| 参数名 | 类型 | 必填 | 说明 | 701| ------------- | --------------------- | ---- | ------------------------- | 702| alphaMask | [Mask](#mask20) | 是 | 通过遮罩指定转场效果的作用区域。| 703| factor | number | 否 | 转场过渡系数，取值范围为[0.0, 1.0]，默认值为1.0。factor值越大画面越接近转场后页面，超出范围自动截断到[0.0, 1.0]。 | 704| inverse | boolean | 否 | 是否启用反向转场，true表示启用，false表示不启用，默认值为false。 | 705 706**返回值：** 707 708| 类型 | 说明 | 709| ----------------- | --------------------------------- | 710| [Filter](#filter) | 返回挂载了转场效果的Filter。 | 711 712**错误码：** 713 714以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 715 716| 错误码ID | 错误信息 | 717| ------- | --------------------------------------------| 718| 202 | Permission verification failed. A non-system application calls a system API. | 719 720**示例：** 721 722```ts 723import { uiEffect, common2D } from "@kit.ArkGraphics2D"; 724 725@Entry 726@Component 727struct Index { 728 context = this.getUIContext() 729 @State alpha: number = 0 730 @State enterNewPage:boolean = false 731 @State rippleMaskCenter: common2D.Point = {x:0.5, y:0.5} 732 @State rippleMaskRadius: number = 0.1 733 build() { 734 Stack() { 735 //转场前页面 736 Image($r("app.media.before")).width("100%").height("100%") 737 if (this.enterNewPage){ 738 //转场后页面 739 Column().width("100%").height("100%").backgroundImage($r("app.media.after")) 740 .backgroundFilter(uiEffect.createFilter() 741 .maskTransition( 742 uiEffect.Mask.createRadialGradientMask(this.rippleMaskCenter, this.rippleMaskRadius,this.rippleMaskRadius, [[1, 0], [1, 1]]), 743 this.alpha)) 744 .onAppear(() => { 745 this.context.animateTo({ duration: 1000 }, () => { 746 this.rippleMaskRadius = 1.3 747 }) 748 this.context.animateTo({ duration: 800 }, () => { 749 this.alpha = 1 750 }) 751 }) 752 } 753 }.borderWidth(2) 754 .onClick(()=>{ 755 this.enterNewPage=!this.enterNewPage; 756 if (this.enterNewPage) { 757 this.alpha=0; 758 this.rippleMaskRadius=0.1; 759 } 760 }) 761 } 762} 763``` 764 765### directionLight<sup>20+</sup> 766directionLight(direction: common2D.Point3d, color: Color, intensity: number, mask?: Mask, factor?: number): Filter 767 768为组件内容提供基于[Mask](#mask20)和平行光的光照效果。 769 770**系统能力：** SystemCapability.Graphics.Drawing 771 772**系统接口：** 此接口为系统接口。 773 774**参数：** 775| 参数名 | 类型 | 必填 | 说明 | 776| ------------- | --------------------- | ---- | ------------------------- | 777| direction | [common2D.Point3d](js-apis-graphics-common2D.md#point3d12) | 是 | 方向光的入射方向。| 778| color | [Color](#color20) | 是 | 光照颜色。| 779| intensity | number | 是 | 光照强度，非负数。| 780| mask | [Mask](#mask20) | 否 | 置换贴图，用于描述二维图像表面的三维细节，通过法线或高度图增强局部细节和光照反射效果，若输入为高度图，须与factor参数配合使用。默认为空，表现为全局无细节的平面光照效果。| 781| factor | number | 否 | 采样缩放系数。默认值为null，mask作为法线图采样；非默认值时，mask作为高度图采样，实际高度值为mask的采样值与factor的乘积。| 782 783**返回值：** 784 785| 类型 | 说明 | 786| ----------------- | --------------------------------- | 787| [Filter](#filter) | 返回挂载了由置换贴图控制的光照效果的Filter。 | 788 789**错误码：** 790 791以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 792 793| 错误码ID | 错误信息 | 794| ------- | --------------------------------------------| 795| 202 | Permission verification failed. A non-system application calls a system API. | 796 797**示例：** 798 799```ts 800import { uiEffect, common2D } from "@kit.ArkGraphics2D"; 801 802@Entry 803@Component 804struct Index { 805 @State rippleMaskCenter: common2D.Point = {x:0.5, y:0.5} 806 @State rippleMaskRadius: number = 0.0 807 @State rippleMaskWidth: number = 0.0 808 @State color: Color = Color.Transparent 809 810 build() { 811 Column() { 812 RelativeContainer() { 813 Image($r("app.media.back")).width("100%").height("100%") 814 Stack() 815 .width("100%") 816 .height("100%") 817 .backgroundColor(this.color) 818 .backgroundFilter(uiEffect.createFilter() 819 .directionLight( 820 {x:0, y:0, z:-1}, {red:2.0, green:2.0, blue:2.0, alpha:1.0}, 0.5, 821 uiEffect.Mask.createRippleMask(this.rippleMaskCenter, this.rippleMaskRadius, this.rippleMaskWidth, 0.0) 822 )) 823 .onClick(() => { 824 animateTo({duration: 1000}, () => { 825 this.rippleMaskWidth = 1.0; 826 }) 827 }) 828 } 829 }.alignItems(HorizontalAlign.Center).borderWidth(2) 830 } 831} 832``` 833 834### variableRadiusBlur<sup>20+</sup> 835variableRadiusBlur(radius: number, radiusMap: Mask): Filter 836 837为组件内容提供基于[Mask](#mask20)的渐变模糊效果。 838 839**系统能力：** SystemCapability.Graphics.Drawing 840 841**系统接口：** 此接口为系统接口。 842 843**参数：** 844| 参数名 | 类型 | 必填 | 说明 | 845| ------------- | --------------------- | ---- | ------------------------- | 846| radius | number | 是 | 最大模糊半径，该值越大越模糊。取值范围为[0, 128]。模糊半径设置为0时不模糊；模糊半径设置小于0的值时，按值为0处理；设置大于128的值时，按值为128处理。| 847| radiusMap | [Mask](#mask20) | 是 | 代表模糊程度的Mask对象。| 848 849**返回值：** 850 851| 类型 | 说明 | 852| ----------------- | --------------------------------- | 853| [Filter](#filter) | 返回当前效果的Filter对象。 | 854 855**错误码：** 856 857以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 858 859| 错误码ID | 错误信息 | 860| ------- | --------------------------------------------| 861| 202 | Permission verification failed. A non-system application calls a system API. | 862 863**示例：** 864 865```ts 866import { uiEffect } from "@kit.ArkGraphics2D"; 867 868@Entry 869@Component 870struct VariableRadiusBlurExample { 871 @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.1) 872 873 build() { 874 Stack() { 875 Image($rawfile('test.png')) 876 Row() 877 .width("100%") 878 .height("100%") 879 .backgroundFilter(uiEffect.createFilter().variableRadiusBlur(64, this.maskExample)) 880 } 881 } 882} 883``` 884 885## TileMode 886像素填充模式枚举。 887 888**系统能力：** SystemCapability.Graphics.Drawing 889 890**系统接口：** 此接口为系统接口。 891 892| 名称 | 值 | 说明 | 893| ------ | - | ---- | 894| CLAMP | 0 | 截断。 | 895| REPEAT | 1 | 重复。 | 896| MIRROR | 2 | 镜像。 | 897| DECAL | 3 | 透明。 | 898 899## WaterRippleMode 900水波纹场景模式枚举。 901 902**系统能力：** SystemCapability.Graphics.Drawing 903 904**系统接口：** 此接口为系统接口。 905 906| 名称 | 值 | 说明 | 907| ------ | - | ---- | 908| SMALL2MEDIUM_RECV | 0 | 手机碰2in1设备（接收端）。 | 909| SMALL2MEDIUM_SEND | 1 | 手机碰2in1设备（发送端）。 | 910| SMALL2SMALL | 2 | 手机碰手机。 | 911| MINI_RECV<sup>17+</sup> | 3 | 2in1设备与其它设备共享（键鼠共享场景）。 | 912 913## FlyMode 914飞入飞出形变场景模式枚举。 915 916**系统能力：** SystemCapability.Graphics.Drawing 917 918**系统接口：** 此接口为系统接口。 919 920| 名称 | 值 | 说明 | 921| ------ | - | ---- | 922| BOTTOM | 0 | 从底部进行飞入飞出形变。 | 923| TOP | 1 | 从顶部进行飞入飞出形变。 | 924 925## VisualEffect 926VisualEffect效果类，用于将相应的效果添加到指定的组件上。在调用VisualEffect的方法前，需要先通过[createEffect](js-apis-uiEffect.md#uieffectcreateeffect)创建一个VisualEffect实例。 927 928### backgroundColorBlender 929backgroundColorBlender(blender: BrightnessBlender): VisualEffect 930 931将混合器添加至组件上以改变组件背景颜色，具体的更改效果由输入决定，目前仅支持提亮混合器。 932 933**系统能力：** SystemCapability.Graphics.Drawing 934 935**系统接口：** 此接口为系统接口。 936 937**参数：** 938| 参数名 | 类型 | 必填 | 说明 | 939| ------- | ---------------------------------------- | ---- | ------------------------- | 940| blender | [BrightnessBlender](#brightnessblender) | 是 | 用于混合背景颜色的blender。 | 941 942**返回值：** 943 944| 类型 | 说明 | 945| ----------------------------- | ------------------------------------------------- | 946| [VisualEffect](#visualeffect) | 返回添加了背景颜色更改效果的VisualEffect。 | 947 948**示例：** 949 950```ts 951let blender : uiEffect.BrightnessBlender = 952 uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 953 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 954visualEffect.backgroundColorBlender(blender) 955``` 956 957### borderLight<sup>20+</sup> 958borderLight(lightPosition: common2D.Point3d, lightColor: common2D.Color, lightIntensity: number, borderWidth: number): VisualEffect 959 960为圆角矩形组件边框添加3D光照效果。 961 962**系统能力：** SystemCapability.Graphics.Drawing 963 964**系统接口：** 此接口为系统接口。 965 966**参数：** 967| 参数名 | 类型 | 必填 | 说明 | 968| ------------- | --------------------- | ---- | ------------------------- | 969| lightPosition | [common2D.Point3d](js-apis-graphics-common2D.md#point3d12) | 是 | 光源在组件空间的3D位置，[-1, -1, 0]为组件左上角，[1, 1, 0]为组件的右下角，z轴分量越大，光源离组件平面越远，可照射区域越大。<br/> x轴分量取值范围[-10, 10]，y轴分量取值范围[-10, 10]，z轴分量取值范围[0, 10]，超出范围会自动截断。 | 970| lightColor | [common2D.Color](js-apis-graphics-common2D.md#color) | 是 | 光源颜色，各元素取值范围为[0, 1]，超出范围会自动截断。 | 971| lightIntensity | number | 是 | 光源强度，取值范围[0, 1]，数值越大光源亮度越大，超出范围会自动截断。| 972| borderWidth | number | 是 | 组件边框的受光宽度，取值范围为[0.0, 30.0]，超出范围会自动截断。设置为0.0时，组件边框无光照效果，数值越大，光可照亮的区域越宽。 | 973 974**返回值：** 975 976| 类型 | 说明 | 977| ----------------- | --------------------------------- | 978| [VisualEffect](#visualeffect) | 返回了具有边框光照效果的VisualEffect。 | 979 980**错误码：** 981 982以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 983 984| 错误码ID | 错误信息 | 985| ------- | --------------------------------------------| 986| 202 | Permission verification failed. A non-system application calls a system API. | 987 988**示例：** 989```ts 990import { common2D, uiEffect } from '@kit.ArkGraphics2D' 991 992@Entry 993@Component 994struct Index { 995 @State point1:common2D.Point3d = { 996 x:0,y:0,z:2 997 } 998 @State color1:common2D.Color = { 999 red:1,green:1,blue:1,alpha:1 1000 } 1001 @State lightIntentsity1:number = 1 1002 @State bordrwidth:number = 20 1003 1004 build() { 1005 Column() { 1006 Stack() { 1007 Image($r('app.media.man')) 1008 .width('646px') 1009 .height('900px') 1010 .borderRadius(10) 1011 Column() 1012 .width('646px') 1013 .height('900px') 1014 .borderRadius(10) 1015 .visualEffect(uiEffect.createEffect().borderLight(this.point1, this.color1, this.lightIntentsity1, 1016 this.bordrwidth)) 1017 } 1018 .width('100%') 1019 .height('55%') 1020 } 1021 .height('100%') 1022 .width('100%') 1023 .justifyContent(FlexAlign.Center) 1024 .backgroundColor('#555') 1025 } 1026} 1027``` 1028 1029## Blender<sup>13+</sup> 1030 1031type Blender = BrightnessBlender | HdrBrightnessBlender 1032 1033混合器类型，用于描述混合效果。 1034 1035**系统能力：** SystemCapability.Graphics.Drawing 1036 1037**系统接口：** 此接口为系统接口。 1038 1039| 类型 | 说明 | 1040| ----------------------------- | ------------------------------------------------- | 1041| [BrightnessBlender](#brightnessblender) | 具有提亮效果的混合器。 | 1042| [HdrBrightnessBlender](#hdrbrightnessblender20)<sup>20+</sup> | 具有提亮效果的混合器（支持HDR）。 | 1043 1044## BrightnessBlender 1045提亮混合器，用于将提亮效果添加到指定的组件上。在调用BrightnessBlender前，需要先通过[createBrightnessBlender](#uieffectcreatebrightnessblender)创建一个BrightnessBlender实例。 1046 1047**系统能力：** SystemCapability.Graphics.Drawing 1048 1049**系统接口：** 此接口为系统接口。 1050 1051| 名称 | 类型 | 只读 | 可选 | 说明 | 1052| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 1053| cubicRate | number | 否 | 否 | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。 | 1054| quadraticRate | number | 否 | 否 | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。 | 1055| linearRate | number | 否 | 否 | 灰度调整的线性系数。<br/>取值范围[-20, 20]。 | 1056| degree | number | 否 | 否 | 灰度调整的比例。<br/>取值范围[-20, 20]。 | 1057| saturation | number | 否 | 否 | 提亮的基准饱和度。<br/>取值范围[0, 20]。 | 1058| positiveCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 | 1059| negativeCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 | 1060| fraction | number | 否 | 否 | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。 | 1061 1062## HdrBrightnessBlender<sup>20+</sup> 1063支持HDR的提亮混合器（继承自[BrightnessBlender](#brightnessblender)），用于将提亮效果添加到指定的组件上。在调用HdrBrightnessBlender前，需要先通过[createHdrBrightnessBlender](#uieffectcreatehdrbrightnessblender20)创建一个HdrBrightnessBlender实例。 1064 1065该混合器参数可参考[BrightnessBlender](#brightnessblender)。 1066 1067**系统能力：** SystemCapability.Graphics.Drawing 1068 1069**系统接口：** 此接口为系统接口。 1070 1071## Color<sup>20+</sup> 1072 1073RGBA格式的颜色描述。 1074 1075**系统能力：** SystemCapability.Graphics.Drawing 1076 1077| 名称 | 类型 | 只读 | 可选 | 说明 | 1078| ----- | ------ | ---- | ---- | ---------------------------------------- | 1079| red | number | 是 | 是 | 颜色的R分量（红色）。值大于等于0，当值小于0时无效。 | 1080| green | number | 是 | 是 | 颜色的G分量（绿色）。值大于等于0，当值小于0时无效。| 1081| blue | number | 是 | 是 | 颜色的B分量（蓝色）。值大于等于0，当值小于0时无效。 | 1082| alpha | number | 是 | 是 | 颜色的A分量（透明度）。值大于等于0，当值小于0时无效。 | 1083 1084## Mask<sup>20+</sup> 1085Mask效果类，作为[Filter](#filter)以及[VisualEffect](#visualeffect)的输入使用。 1086 1087### createRippleMask<sup>20+</sup> 1088static createRippleMask(center: common2D.Point, radius: number, width: number, offset?: number): Mask 1089 1090通过输入波环圆心的位置、半径和宽度创建波环遮罩效果Mask实例，具体的效果由输入的参数决定。 1091 1092**系统能力：** SystemCapability.Graphics.Drawing 1093 1094**系统接口：** 此接口为系统接口。 1095 1096**参数：** 1097| 参数名 | 类型 | 必填 | 说明 | 1098| ------- | ---------------------------------------- | ---- | ------------------------- | 1099| center | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 设置波环圆心在组件上的位置，[0, 0]为组件左上角，[1, 1]为组件的右下角。<br/>取值范围[-10, 10]，超出边界会在实现时自动截断。 | 1100| radius | number | 是 | 设置波环的半径，半径为1等于组件的高度。<br/>取值范围[0, 10]，超出边界会在实现时自动截断。 | 1101| width | number | 是 | 设置波环的宽度。<br/>取值范围[0, 10]，超出边界会在实现时自动截断。 | 1102| offset | number | 否 | 设置波峰位置的偏移。<br/>默认值为0，表示波峰在波环的正中心；<br/>-1.0表示波峰在波环的最内侧；<br/>1.0表示波峰在波环的最外侧。<br/>取值范围[-1, 1]，超出边界会在实现时自动截断。 | 1103 1104**返回值：** 1105 1106| 类型 | 说明 | 1107| ----------------------------- | ------------------------------------------------- | 1108| [Mask](#mask20) | 返回具有波环遮罩效果的Mask。 | 1109 1110**错误码：** 1111 1112以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1113 1114| 错误码ID | 错误信息 | 1115| ------- | --------------------------------------------| 1116| 202 | Permission verification failed. A non-system application calls a system API. | 1117 1118**示例：** 1119 1120```ts 1121 let mask = uiEffect.Mask.createRippleMask({x:0.5, y:1.0}, 0.5, 0.3, 0.0); 1122``` 1123 1124### createPixelMapMask<sup>20+</sup> 1125static createPixelMapMask(pixelMap: image.PixelMap, srcRect: common2D.Rect, dstRect: common2D.Rect, fillColor?: Color): Mask 1126 1127通过输入的[pixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)pixelMap的待绘制区域、挂载节点的绘制区域和绘制区域外填充的颜色创建具有缩放效果的Mask实例，具体的效果由输入的参数决定。 1128 1129**系统能力：** SystemCapability.Graphics.Drawing 1130 1131**系统接口：** 此接口为系统接口。 1132 1133**参数：** 1134| 参数名 | 类型 | 必填 | 说明 | 1135| ------- | ---------------------------------------- | ---- | ------------------------- | 1136| pixelMap | [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见[图片开发指导](../../media/image/image-overview.md)。 | 1137| srcRect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | 是 | pixelMap的待绘制区域。图片最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。right需大于left，bottom需大于top。 | 1138| dstRect | [common2D.Rect](js-apis-graphics-common2D.md#rect) | 是 | pixelMap在mask挂载的节点上的绘制区域。节点最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。right需大于left，bottom需大于top。 | 1139| fillColor | [Color](#color20) | 否 | 节点上在pixelMap绘制区域之外的区域填充的颜色，各元素取值范围为[0, 1]，默认透明色，小于0的转为0，大于1的转为1。 | 1140 1141**返回值：** 1142 1143| 类型 | 说明 | 1144| ----------------------------- | ------------------------------------------------- | 1145| [Mask](#mask20) | 返回具有pixelMap缩放效果的Mask。 | 1146 1147**错误码：** 1148 1149以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1150 1151| 错误码ID | 错误信息 | 1152| ------- | --------------------------------------------| 1153| 202 | Permission verification failed. A non-system application calls a system API. | 1154 1155**示例：** 1156 1157```ts 1158import { image } from "@kit.ImageKit"; 1159import { uiEffect, common2D } from "@kit.ArkGraphics2D"; 1160import { BusinessError } from '@kit.BasicServicesKit' 1161 1162const color = new ArrayBuffer(96); 1163let opts : image.InitializationOptions = { 1164 editable: true, 1165 pixelFormat: 3, 1166 size: { 1167 height: 4, 1168 width: 6 1169 } 1170} 1171image.createPixelMap(color, opts).then((pixelMap) => { 1172 let srcRect : common2D.Rect = { 1173 left: 0, 1174 top: 0, 1175 right: 1, 1176 bottom: 1 1177 } 1178 let dstRect : common2D.Rect = { 1179 left: 0, 1180 top: 0, 1181 right: 1, 1182 bottom: 1 1183 } 1184 let fillColor : uiEffect.Color = { 1185 red: 0, 1186 green: 0, 1187 blue: 0, 1188 alpha: 1 1189 } 1190 let mask = uiEffect.Mask.createPixelMapMask(pixelMap, srcRect, dstRect, fillColor); 1191}).catch((error: BusinessError)=>{ 1192 console.error('Failed to create pixelmap. code is ${error.code}, message is ${error.message}'); 1193}) 1194``` 1195### createRadialGradientMask<sup>20+</sup> 1196static createRadialGradientMask(center: common2D.Point, radiusX: number, radiusY: number, values: Array<[number, number]>): Mask 1197 1198通过输入椭圆中心点的位置、长短轴和形状参数创建椭圆遮罩效果[Mask](#mask20)实例，具体的效果由输入的参数决定。 1199 1200**系统能力：** SystemCapability.Graphics.Drawing 1201 1202**系统接口：** 此接口为系统接口。 1203 1204**参数：** 1205| 参数名 | 类型 | 必填 | 说明 | 1206| ------- | ---------------------------------------- | ---- | ------------------------- | 1207| center | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 设置椭圆的中心点，[0, 0]为组件左上角，[1, 1]为组件的右下角。<br/>取值范围[-10, 10]，可取浮点数，超出边界会在实现时自动截断。 | 1208| radiusX | number | 是 | 设置椭圆的长轴，半径为1等于组件的高度。<br/>取值范围[0, 10]，可取浮点数，超出边界会在实现时自动截断。 | 1209| radiusY | number | 是 | 设置椭圆的短轴，半径为1等于组件的高度。<br/>取值范围[0, 10]，可取浮点数，超出边界会在实现时自动截断。 | 1210| values | Array<[number, number]> | 是 | 数组中保存的二元数组表示梯度：[RGBA颜色, 位置]。RGBA颜色四通道使用相同的值，可看作一个灰度值；位置表示沿径向方向向外时RGBA颜色对应的分布位置；RGBA颜色与位置的取值范围均为[0, 1]，可取浮点数，小于0的转为0，大于1的转为1。<br/>位置参数值须严格递增，Array数组中二元数组个数必须大于等于2，二元数组中的元素不能为空，否则该椭圆分布效果不生效。 | 1211 1212**返回值：** 1213 1214| 类型 | 说明 | 1215| ----------------------------- | ------------------------------------------------- | 1216| [Mask](#mask20) | 返回椭圆形状的径向分布效果的灰度Mask。 | 1217 1218**错误码：** 1219 1220以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1221 1222| 错误码ID | 错误信息 | 1223| ------- | --------------------------------------------| 1224| 202 | Permission verification failed. A non-system application calls a system API. | 1225 1226**示例：** 1227 1228```ts 1229import uiEffect from '@ohos.graphics.uiEffect' 1230// values: [[1.0, 0.5], [1.0, 1.0]] => color0: 1.0; color1: 1.0; position0: 0.5; position1: 1.0 1231let mask = uiEffect.Mask.createRadialGradientMask({x: 0.0, y: 0.0}, 0.5, 0.5, [[1.0, 0.5], [1.0, 1.0]]); 1232@Entry 1233@Component 1234struct RadialGradientMaskExample { 1235 build() { 1236 Stack() { 1237 Image('test.jpg') 1238 Column() 1239 .width('100%') 1240 .height('100%') 1241 // Mask作为Filter的入参实现对应的效果，该效果中Mask是在屏幕左上角的四分之一圆环 1242 .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, null, mask)) 1243 } 1244 } 1245} 1246``` 1247### createWaveGradientMask<sup>20+</sup> 1248static createWaveGradientMask(center: common2D.Point, width: number, propagationRadius: number, blurRadius: number, turbulenceStrength?: number): Mask 1249 1250输入波源中心位置、单波参数创建单波遮罩效果[Mask](#mask20)实例。 1251 1252**系统能力：** SystemCapability.Graphics.Drawing 1253 1254**系统接口：** 此接口为系统接口。 1255 1256**参数：** 1257| 参数名 | 类型 | 必填 | 说明 | 1258| ------- | ---------------------------------------- | ---- | ------------------------- | 1259| center | [common2D.Point](js-apis-graphics-common2D.md#point12) | 是 | 设置单波波源的中心点，[0, 0]为组件左上角，[1, 1]为组件的右下角。<br/>取值范围[-10, 10]，可取浮点数，超出边界会在实现时自动截断。 | 1260| width | number | 是 | 设置单波圆环的宽度。<br/>取值范围[0, 5]，可取浮点数，超出边界会在实现时自动截断。 | 1261| propagationRadius | number | 是 | 设置单波圆环的扩散外径。<br/>取值范围[0, 10]，可取浮点数，超出边界会在实现时自动截断。 | 1262| blurRadius | number | 是 | 设置单波圆环的模糊外径，模糊半径为0则是实边圆环，否则是虚边圆环。<br/>取值范围[0, 5]，可取浮点数，超出边界会在实现时自动截断。 | 1263| turbulenceStrength | number | 否 | 设置单波圆环的湍流强度，默认值为0，强度为0则是规则圆环，否则圆环边缘会湍流扭曲。<br/>取值范围[-1, 1]，可取浮点数，超出边界会在实现时自动截断。 | 1264 1265**返回值：** 1266 1267| 类型 | 说明 | 1268| ----------------------------- | ------------------------------------------------- | 1269| [Mask](#mask20) | 返回单个水波形状的灰度Mask。 | 1270 1271**错误码：** 1272 1273以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1274 1275| 错误码ID | 错误信息 | 1276| ------- | --------------------------------------------| 1277| 202 | Permission verification failed. A non-system application calls a system API. | 1278 1279**示例：** 1280 1281```ts 1282import { uiEffect } from "@kit.ArkGraphics2D"; 1283// center: [0.5, 0.5]；width: 0.01; propagationRadius: 0.5; blurRadius: 0.1; turbulenceStrength: 0.1 1284let mask = uiEffect.Mask.createWaveGradientMask({x: 0.5, y: 0.5}, 0.01, 0.5, 0.1, 0.1); 1285@Entry 1286@Component 1287struct WaveGradientMaskExample { 1288 build() { 1289 Stack() { 1290 Image('test.jpg') 1291 Column() 1292 .width('100%') 1293 .height('100%') 1294 // 将Mask作为Filter的参数，实现屏幕中心向四周扩散的水波形状效果。 1295 .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, null, mask)) 1296 } 1297 } 1298} 1299``` 1300## BrightnessBlenderParam 1301BrightnessBlender参数列表。 1302 1303**系统能力：** SystemCapability.Graphics.Drawing 1304 1305**系统接口：** 此接口为系统接口。 1306 1307| 名称 | 类型 | 只读 | 可选 | 说明 | 1308| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 1309| cubicRate | number | 否 | 否 | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。 | 1310| quadraticRate | number | 否 | 否 | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。 | 1311| linearRate | number | 否 | 否 | 灰度调整的线性系数。<br/>取值范围[-20, 20]。 | 1312| degree | number | 否 | 否 | 灰度调整的比例。<br/>取值范围[-20, 20]。 | 1313| saturation | number | 否 | 否 | 提亮的基准饱和度。<br/>取值范围[0, 20]。 | 1314| positiveCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 | 1315| negativeCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 | 1316| fraction | number | 否 | 否 | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。 |
