@ohos.graphics.uiEffect (效果级联)(系统接口)

本模块提供组件效果的一些基础能力，包括模糊、边缘像素扩展、提亮等。效果被分为Filter和VisualEffect大类，同类效果可以级联在一个效果大类的实例下。在实际开发中，模糊可用于背景虚化，提亮可用于亮屏显示等。

Filter：用于添加指定Filter效果到组件上。
VisualEffect：用于添加指定VisualEffect效果到组件上。

说明：

本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

页面仅包含本模块的系统接口，其他公开接口参见ohos.graphics.uiEffect (效果级联)。

导入模块

import { uiEffect } from "@kit.ArkGraphics2D";

uiEffect.createBrightnessBlender

createBrightnessBlender(param: BrightnessBlenderParam): BrightnessBlender

创建BrightnessBlender实例用于给组件添加提亮效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
param	BrightnessBlenderParam	是	实现提亮效果的参数。

返回值：

类型	说明
BrightnessBlender	返回设置了提亮效果参数的BrightnessBlender。

示例：

let blender : uiEffect.BrightnessBlender =
  uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})

uiEffect.createHdrBrightnessBlender²⁰⁺

createHdrBrightnessBlender(param: BrightnessBlenderParam): HdrBrightnessBlender

创建HdrBrightnessBlender实例用于给组件添加支持HDR的提亮效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
param	BrightnessBlenderParam	是	实现提亮效果的参数。

返回值：

类型	说明
HdrBrightnessBlender	返回具有提亮效果的混合器（支持HDR）。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from "@kit.ArkGraphics2D"

let blender : uiEffect.HdrBrightnessBlender =
  uiEffect.createHdrBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})

@Entry
@Component
struct example {
  build() {
    RelativeContainer() {
      Image($r("app.media.screenshot"))
        .width("100%")
        .height("100%")
        .advancedBlendMode(blender)
    }
  }
}

uiEffect.createHdrDarkenBlender

createHdrDarkenBlender(hdrBrightnessRatio: number, grayscaleFactor?: [number, number, number]): HdrDarkenBlender

创建HdrDarkenBlender实例用于HDR图层的压暗混合效果。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
hdrBrightnessRatio	number	是	HDR的提亮倍数。取值范围[1.0, 设备当前支持最大提亮倍数]。设置小于1.0的值时，按值为1.0处理；当值等于1.0时，为组件原本亮度；设置大于设备当前支持最大提亮倍数的值时，按值为设备当前支持最大提亮倍数处理，支持最大提亮倍数 = 设备最大亮度 / 设备默认亮度。设备最大亮度通过hdc命令获取：param get const.display.brightness.max 设备默认亮度通过hdc命令获取：param get const.display.brightness.default
grayscaleFactor	[number, number, number]	否	将RGB颜色转换为灰度值，该公式可根据色域切换。三个分量均无边界限制。默认值为标准灰度权重[0.299, 0.587, 0.114]。

返回值：

类型	说明
HdrDarkenBlender	返回HDR压暗混合器，用于将压暗效果添加到指定的组件上。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
401	CreateHdrDarkenBlender failed, parameter is null or undefined.

示例：

let blender : uiEffect.HdrDarkenBlender = 
  uiEffect.createHdrDarkenBlender(1.3, [0.299, 0.587, 0.114]) 
@Entry 
@Component 
struct example { 
  build() { 
    RelativeContainer() { 
      Stack(){ 
          Text("TextWord") 
          Image($r("app.media.screenshot")) 
            .width("100%") 
            .height("100%") 
            .advancedBlendMode(blender) 
      } 
    } 
  } 
}

Filter

Filter效果类，用于将相应的效果添加到指定的组件上。在调用Filter的方法前，需要先通过createFilter创建一个Filter实例。

pixelStretch

pixelStretch(stretchSizes: Array<number>, tileMode: TileMode): Filter

将边缘像素扩展效果添加至组件上。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
stretchSizes	Array<number>	是	上下左右四个方向边缘像素扩展的百分比比例，取值范围为[-1, 1]。正值表示向外扩展，上下左右四个方向分别用指定原图比例的边缘像素填充。负值表示内缩，但是最终图像大小不变。注意四个方向对应的参数需统一为非正值或非负值。
tileMode	TileMode	是	边缘像素扩展的像素填充模式。

返回值：

类型	说明
Filter	返回挂载了边缘像素扩展效果的Filter。

示例：

filter.pixelStretch([0.2, 0.2, 0.2, 0.2], uiEffect.TileMode.CLAMP)

waterRipple

waterRipple(progress: number, waveCount: number, x: number, y: number, rippleMode: WaterRippleMode): Filter

将水波纹效果添加至组件上。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
progress	number	是	表示水波纹的进度，取值范围为[0, 1]。水波纹进度越趋向于1，水波纹展示越完全。超出取值范围水波纹不会出现效果。
waveCount	number	是	水波纹波动时波纹的个数，取值范围为[1, 3]。水波纹的个数只能取整数，如果为浮点数或超出取值范围，水波纹不会出现效果。
x	number	是	水波纹中心在屏幕中第一次出现的x轴位置。水波纹对屏幕进行归一化处理，左上角的坐标为（0, 0），右上角坐标为（1, 0）。当x取值为负值时，代表在屏幕左侧。
y	number	是	水波纹中心在屏幕中第一次出现的y轴位置。水波纹对屏幕进行归一化处理，左上角的坐标为（0, 0），左下角坐标为（0, 1）。当y取值为负值时，代表在屏幕上方。
rippleMode	WaterRippleMode	是	水波纹的场景模式。

返回值：

类型	说明
Filter	返回挂载了水波纹效果的Filter。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

filter.waterRipple(0.5, 2, 0.5, 0.5, uiEffect.WaterRippleMode.SMALL2SMALL)

flyInFlyOutEffect

flyInFlyOutEffect(degree: number, flyMode: FlyMode): Filter

将飞入飞出形变效果添加至组件上。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
degree	number	是	表示控制飞入飞出形变的程度，取值范围为[0, 1]。越靠近1，变形程度越明显。超出取值范围形变不会出现效果。
flyMode	FlyMode	是	飞入飞出的场景模式。 BOTTOM表示从设备底部飞入飞出形变场景。 TOP表示从设备顶部飞入飞出形变场景。

返回值：

类型	说明
Filter	返回挂载了飞入飞出形变效果的Filter。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

filter.flyInFlyOutEffect(0.5, uiEffect.FlyMode.TOP)

distort¹³⁺

distort(distortionK: number): Filter

将透镜畸变效果添加至组件上。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
distortionK	number	是	畸变系数，表示透镜畸变的程度，取值范围为[-1, 1]。畸变系数设置小于-1的值时，按值为-1处理；设置大于1的值时，按值为1处理。

如上图是对图片组件分别设置畸变参数为-1，0，0.5，1的绘制结果。畸变参数小于0时，效果为桶形畸变；大于0时，效果为枕形畸变；越接近0时，畸变程度越小，等于0时，没有畸变效果。

返回值：

类型	说明
Filter	返回挂载了透镜畸变效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

filter.distort(-0.5)

radiusGradientBlur¹⁹⁺

radiusGradientBlur(value: number, options: LinearGradientBlurOptions): Filter

为组件内容添加半径线性渐变模糊效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
value	number	是	模糊半径，单位为px，模糊半径越大越模糊。取值范围为[0, 128]。模糊半径设置为0时不模糊；模糊半径设置小于0的值时，按值为0处理；设置大于128的值时，按值为128处理。
options	LinearGradientBlurOptions	是	线性渐变参数，包含两个部分fractionStops和direction。

返回值：

类型	说明
Filter	返回挂载了半径线性渐变模糊效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct RadiusGradientBlurExample {
  @State blurRadiusExample: number = 64
  @State linearGradientBlurOptionsExample: LinearGradientBlurOptions =
    {fractionStops: [[0.0, 0.0], [1.0, 1.0]], direction: GradientDirection.Bottom}

  build() {
    Column() {
      Image($rawfile('test.png'))
        .compositingFilter(uiEffect.createFilter().radiusGradientBlur(this.blurRadiusExample,
          this.linearGradientBlurOptionsExample))
    }
  }
}

bezierWarp²⁰⁺

bezierWarp(controlPoints: Array<common2D.Point>): Filter

将贝塞尔曲线变形的效果添加至组件上。该效果通过在图层边界上创建封闭的贝塞尔曲线，实现对图像的精准扭曲和形状调整。贝塞尔曲线共有四段，首尾顺次相连，每段包含一个顶点和两个切点。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
controlPoints	Array<common2D.Point>	是	12个贝塞尔形变控制点，更改控制点的位置可改变形成边缘的曲线的形状，从而扭曲图像。控制点坐标为0-1坐标系，且坐标值可大于1或小于0。

返回值：

类型	说明
Filter	返回挂载了贝塞尔曲线变形效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { common2D, uiEffect } from '@kit.ArkGraphics2D'

@Entry
@Component
struct BezierWarpExample {
  @State valueBezier: Array<common2D.Point> = [
    { x: 0, y: 0 }, { x: 1 / 3, y: 0 }, { x: 2 / 3, y: 0 }, // top edge
    { x: 0.5, y: 0 }, { x: 0.5, y: 1 / 3 }, { x: 1, y: 2 / 3 }, // right edge
    { x: 1, y: 1 }, { x: 2 / 3, y: 1 }, { x: 1 / 3, y: 1 }, // bottom edge
    { x: 0, y: 1 }, { x: 0, y: 2 / 3 }, { x: 0, y: 1 / 3 }] // left edge

  build() {
    Column() {
      Image($rawfile('test.jpg'))
        .foregroundFilter(uiEffect.createFilter().bezierWarp(this.valueBezier))
    }
  }
}

colorGradient²⁰⁺

colorGradient(colors: Array<Color>, positions: Array<common2D.Point>, strengths: Array<number>, alphaMask?: Mask): Filter

为组件内容添加颜色渐变效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
colors	Array<Color>	是	颜色数组，多个颜色的渐变。数组长度取值范围[0, 12], 每一个颜色值取值范围为大于等于0。数组长度等于0或大于12时无效果，colors、positions和strengths的数组长度不相等时无效果。
positions	Array<common2D.Point>	是	位置数组，颜色对应的分布位置。数组长度取值范围[0, 12]。数组长度等于0或大于12时无效果，colors、positions和strengths的数组长度不相等时无效果。
strengths	Array<number>	是	强度数组，颜色对应的扩散强度。数组长度取值范围[0, 12], 每一个强度值取值范围为大于等于0。数组长度等于0或大于12时无效果，colors、positions和strengths的数组长度不相等时无效果。
alphaMask	Mask	否	遮罩alpha，颜色对应的alpha显示遮罩。不设置时，默认组件内容全部有颜色渐变效果。

返回值：

类型	说明
Filter	返回挂载了颜色渐变效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { common2D, uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct ColorGradientExample {
  @State colorsExample: Array<uiEffect.Color> = [
    {red: 1.0, green: 0.8, blue: 0.5, alpha: 0.8},
    {red: 1.0, green: 1.5, blue: 0.5, alpha: 1.0}
  ]

  @State positionsExample: Array<common2D.Point> = [
    {x: 0.2, y: 0.2},
    {x: 0.8, y: 0.6}]

  @State strengthsExample: Array<number> = [0.3, 0.3]

  build() {
    Column() {
      Row()
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().colorGradient(this.colorsExample, this.positionsExample, this.strengthsExample))
    }
  }
}

contentLight²⁰⁺

contentLight(lightPosition: common2D.Point3d, lightColor: common2D.Color, lightIntensity: number, displacementMap?: Mask): Filter

为组件内容添加3D光照效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
lightPosition	common2D.Point3d	是	光源在组件空间的位置，[-1, -1, 0]为组件左上角，[1, 1, 0]为组件的右下角，z轴分量越大光源离组件平面越远，可照射区域越大。 x分量取值范围[-10, 10]，y分量取值范围[-10, 10]，z分量取值范围[0, 10]，超出范围会自动截断。
lightColor	common2D.Color	是	光源颜色，各元素取值范围为[0, 1]，超出范围会自动截断。
lightIntensity	number	是	光源强度，取值范围[0, 1]，数值越大光源亮度越大，超出范围会自动截断。
displacementMap	Mask	否	该参数暂不生效。

返回值：

类型	说明
filter	返回了具有内容光照效果的filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { common2D, uiEffect } from '@kit.ArkGraphics2D'

@Entry
@Component
struct Index {
  @State point2: common2D.Point3d = {
    x: 0, y: 0, z: 2
  }
  @State color2: common2D.Color = {
    red: 1,
    green: 1,
    blue: 1,
    alpha: 1
  }
  @State lightIntensity2: number = 1

  build() {
    Column() {
      Stack() {
        Image($r('app.media.man'))
          .width('646px')
          .height('900px')
          .borderRadius(10)
          .foregroundFilter(uiEffect.createFilter().contentLight(this.point2, this.color2, this.lightIntensity2))
      }
      .width('100%')
      .height('55%')
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#555')
  }
}

edgeLight²⁰⁺

edgeLight(alpha: number, color?: Color, mask?: Mask, bloom?: boolean): Filter

为组件内容检测边缘，并添加边缘高亮效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
alpha	number	是	指定描边高光透明度，越大描边越明显。取值范围为[0, 1]。设置为0时无描边；设置小于0的值时，按值为0处理；设置大于1的值时，按值为1处理。
color	Color	否	指定描边高光颜色，不设置时，将默认使用组件内容的原始颜色。如果有值，使用指定颜色。设置不为null时，Color中的alpha不发挥作用，仅使用rgb。
mask	Mask	否	指定描边高光强度。不设置时，默认组件内容全部有描边高光效果。
bloom	boolean	否	指定描边是否发光。设置为true时，有描边和发光效果；设置为false时，只有描边效果无发光效果；不设置时，默认为true。小于16*16的图片默认只有描边效果，无发光效果，此参数失去作用。

返回值：

类型	说明
Filter	返回挂载了描边高光效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct EdgeLightExample {
  @State colorExample: uiEffect.Color = {red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0}
  
  @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.5, 0.5)
  
  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()  
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, this.colorExample, this.maskExample, false))
    }
  }
}

displacementDistort²⁰⁺

displacementDistort(displacementMap: Mask, factor?: [number, number]): Filter

为组件内容添加扭曲效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
displacementMap	Mask	是	指定扭曲程度。与factor相乘后共同决定扭曲程度。
factor	[number, number]	否	指定水平、竖直方向扭曲程度系数，系数的绝对值越大，扭曲程度越明显，建议取值范围为[-10.0, 10.0]。不设置时，默认值为1.0。设置为0时，无扭曲效果。与mask相乘后共同决定扭曲程度。

返回值：

类型	说明
Filter	返回挂载了扭曲效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct DisplacementDistortExample {
  @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.3, 0.0)
  
  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()  
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().displacementDistort(this.maskExample, [5.0, 5.0]))
    }
  }
}

maskDispersion²⁰⁺

maskDispersion(dispersionMask: Mask, alpha: number, rFactor?: [number, number], gFactor?: [number, number], bFactor?: [number, number]): Filter

为组件内容添加由置换贴图控制的色散效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
dispersionMask	Mask	是	置换贴图，用于控制色散的强度、方向和透明度。建议使用PixelMapMask类型的置换贴图。
alpha	number	是	色散整体透明度，透明度越小效果越透明。取值范围为[0, 1.0]。透明度设置为0时色散效果不生效；透明度设置小于0的值时，按值为0处理；设置大于1.0的值时，按值为1.0处理。
rFactor	[number, number]	否	X/Y方向上R通道的色散基础偏移，偏移越大红色色散效果越明显。每个方向上的取值范围为[-1.0, 1.0]。偏移设置小于-1.0的值时，按值为-1.0处理；设置大于1.0的值时，按值为1.0处理。
gFactor	[number, number]	否	X/Y方向上G通道的色散基础偏移，偏移越大绿色色散效果越明显。取值范围同rFactor。
bFactor	[number, number]	否	X/Y方向上B通道的色散基础偏移，偏移越大蓝色色散效果越明显。取值范围同rFactor。

返回值：

类型	说明
Filter	返回挂载了由置换贴图控制的色散效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import {image} from '@kit.ImageKit'
import {common2D, uiEffect} from '@kit.ArkGraphics2D'
import {common} from '@kit.AbilityKit'

@Entry
@Component
struct MaskDispersion {
  @State pixelMap_: PixelMap | null = null
  @State src: common2D.Rect = { left: 0, top: 0, right: 1.0, bottom: 1.0 }
  @State dst: common2D.Rect = { left: 0, top: 0, right: 1.0, bottom: 1.0 }
  @State fillColor: uiEffect.Color = { red: 0, green: 0, blue: 0, alpha: 0 }

  onPageShow(): void {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext
    context.resourceManager.getMediaByName("mask_alpha").then(val => {
      let buffer = val.buffer.slice(0, val.buffer.byteLength)
      let imageSource = image.createImageSource(buffer);
      imageSource.createPixelMap().then(pixelMap => {
        this.pixelMap_ = pixelMap
      })
    })
  }
  
  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()  
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().maskDispersion(
          uiEffect.Mask.createPixelMapMask(this.pixelMap_, this.src, this.dst, this.fillColor),
          1.0,
          [0.5, -0.5],
          [0.0, 0.0],
          [-0.5, 0.5]))
    }
  }
}

maskTransition²⁰⁺

maskTransition(alphaMask: Mask, factor?: number, inverse?: boolean): Filter

为组件内容提供基于Mask的转场效果。

不建议在屏幕尺寸发生改变的过程中使用此效果，如：旋转屏幕，折叠屏开合屏幕等。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
alphaMask	Mask	是	通过遮罩指定转场效果的作用区域。
factor	number	否	转场过渡系数，取值范围为[0.0, 1.0]，默认值为1.0。factor值越大画面越接近转场后页面，超出范围自动截断到[0.0, 1.0]。
inverse	boolean	否	是否启用反向转场，true表示启用，false表示不启用，默认值为false。

返回值：

类型	说明
Filter	返回挂载了转场效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect, common2D } from "@kit.ArkGraphics2D";

@Entry
@Component
struct Index {
  context = this.getUIContext()
  @State alpha: number = 0
  @State enterNewPage:boolean = false
  @State rippleMaskCenter: common2D.Point = {x:0.5, y:0.5}
  @State rippleMaskRadius: number = 0.1
  build() {
    Stack() {
      // 转场前页面
      Image($r("app.media.before")).width("100%").height("100%")
        if (this.enterNewPage){
          // 转场后页面
          Column().width("100%").height("100%").backgroundImage($r("app.media.after"))
            .backgroundFilter(uiEffect.createFilter()
              .maskTransition(
                uiEffect.Mask.createRadialGradientMask(this.rippleMaskCenter, this.rippleMaskRadius,this.rippleMaskRadius, [[1, 0], [1, 1]]),
                this.alpha))
            .onAppear(() => {
              this.context.animateTo({ duration: 1000 }, () => {
                this.rippleMaskRadius = 1.3
              })
              this.context.animateTo({ duration: 800 }, () => {
                this.alpha = 1
              })
            })
        }
    }.borderWidth(2)
    .onClick(()=>{
      this.enterNewPage=!this.enterNewPage;
      if (this.enterNewPage) {
        this.alpha=0;
        this.rippleMaskRadius=0.1;
      }
    })
  }
}

directionLight²⁰⁺

directionLight(direction: common2D.Point3d, color: Color, intensity: number, mask?: Mask, factor?: number): Filter

为组件内容提供基于Mask和平行光的光照效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
direction	common2D.Point3d	是	方向光的入射方向。
color	Color	是	光照颜色。
intensity	number	是	光照强度，非负数。
mask	Mask	否	置换贴图，用于描述二维图像表面的三维细节，通过法线或高度图增强局部细节和光照反射效果，若输入为高度图，须与factor参数配合使用。默认为空，表现为全局无细节的平面光照效果。
factor	number	否	采样缩放系数。默认值为null，mask作为法线图采样；非默认值时，mask作为高度图采样，实际高度值为mask的采样值与factor的乘积。

返回值：

类型	说明
Filter	返回挂载了由置换贴图控制的光照效果的Filter。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect, common2D } from "@kit.ArkGraphics2D";

@Entry
@Component
struct Index {
  @State rippleMaskCenter: common2D.Point = {x:0.5, y:0.5}
  @State rippleMaskRadius: number = 0.0
  @State rippleMaskWidth: number = 0.0
  @State color: Color = Color.Transparent

  build() {
    Column() {
      RelativeContainer() {
        Image($r("app.media.back")).width("100%").height("100%")
        Stack()
          .width("100%")
          .height("100%")
          .backgroundColor(this.color)
          .backgroundFilter(uiEffect.createFilter()
            .directionLight(
              {x:0, y:0, z:-1}, {red:2.0, green:2.0, blue:2.0, alpha:1.0}, 0.5,
              uiEffect.Mask.createRippleMask(this.rippleMaskCenter, this.rippleMaskRadius, this.rippleMaskWidth, 0.0)
              ))
          .onClick(() => {
            this.getUIContext().animateTo({duration: 1000}, () => {
              this.rippleMaskWidth = 1.0;
            })
          })
      }
    }.alignItems(HorizontalAlign.Center).borderWidth(2)
  }
}

variableRadiusBlur²⁰⁺

variableRadiusBlur(radius: number, radiusMap: Mask): Filter

为组件内容提供基于Mask的渐变模糊效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
radius	number	是	最大模糊半径，单位为px，该值越大越模糊。取值范围为[0, 128]。模糊半径设置为0时不模糊；模糊半径设置小于0的值时，按值为0处理；设置大于128的值时，按值为128处理。
radiusMap	Mask	是	代表模糊程度的Mask对象。

返回值：

类型	说明
Filter	返回当前效果的Filter对象。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from "@kit.ArkGraphics2D";

@Entry
@Component
struct VariableRadiusBlurExample {
  @State maskExample: uiEffect.Mask = uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.1)

  build() {
    Stack() {
      Image($rawfile('test.png'))
      Row()
        .width("100%")
        .height("100%")
        .backgroundFilter(uiEffect.createFilter().variableRadiusBlur(64, this.maskExample))
    }
  }
}

heatDistortion

heatDistortion(param: HeatDistortionEffectParam): Filter

应用热浪扭曲效果到图像，模拟热空气流动产生的视觉扭曲。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
param	HeatDistortionEffectParam	是	热浪扭曲效果的参数。

返回值：

类型	说明
Filter	返回添加了热浪扭曲效果的Filter。

示例：

import { uiEffect } from '@kit.ArkGraphics2D';

@Entry
@Component
struct HeatDistortionExample {
  @State intensity: number = 0.8;
  @State noiseScale: number = 2.0;
  @State riseWeight: number = 0.5;
  @State progress: number = 0.3;

  build() {
    Stack() {
      Image($r('app.media.test'))
        .width('100%')
        .height('100%')
        .foregroundFilter(uiEffect.createFilter().heatDistortion({
          intensity: this.intensity,
          noiseScale: this.noiseScale,
          riseWeight: this.riseWeight,
          progress: this.progress
        }))
    }
    .width('100%')
    .height('100%')
  }
}

blurBubblesRise

blurBubblesRise(param: BlurBubblesRiseEffectParam): Filter

应用模糊气泡上升效果到图像，模拟气泡在液体中上升的梦幻模糊扭曲效果。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Graphics.Drawing

参数：

参数名	类型	必填	说明
param	BlurBubblesRiseEffectParam	是	模糊气泡上升效果的参数。

返回值：

类型	说明
Filter	返回添加了模糊气泡上升效果的Filter。

示例：

import { uiEffect } from '@kit.ArkGraphics2D';
import { image } from '@kit.ImageKit';

@Entry
@Component
struct BlurBubblesRiseExample {
  private context: Context | undefined = this.getUIContext().getHostContext();
  @State blurIntensity: number = 0.8;
  @State mixStrength: number = 0.6;
  @State progress: number = 0.5;
  @State maskImage: image.PixelMap | null = null;

  aboutToAppear() {
    if (this.context) {
      this.getImagePixelMap(this.context)
    }
  }

  getImagePixelMap(context: Context) {
    let resourceMgr = context.resourceManager;
    resourceMgr?.getMediaContent($r('app.media.drawBlurMask').id)
      .then((val: Uint8Array) => {
        let buffer: ArrayBuffer = val.buffer.slice(0, val.buffer.byteLength)
        let imageSource: image.ImageSource = image.createImageSource(buffer);
        imageSource.createPixelMap().then((pixelmap: image.PixelMap) => {
          this.maskImage = pixelmap as PixelMap;
        })
      })
  }

  build() {
    Stack() {
      Image($r('app.media.test'))
        .width('100%')
        .height('100%')
        .foregroundFilter(uiEffect.createFilter().blurBubblesRise({
          blurIntensity: this.blurIntensity,
          mixStrength: this.mixStrength,
          progress: this.progress,
          maskImage: this.maskImage
        }))
    }
    .width('100%')
    .height('100%')
  }
}

TileMode

像素填充模式枚举。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

名称	值	说明
CLAMP	0	截断。
REPEAT	1	重复。
MIRROR	2	镜像。
DECAL	3	透明。

WaterRippleMode

水波纹场景模式枚举。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

名称	值	说明
SMALL2MEDIUM_RECV	0	手机碰2in1设备（接收端）。
SMALL2MEDIUM_SEND	1	手机碰2in1设备（发送端）。
SMALL2SMALL	2	手机碰手机。
MINI_RECV¹⁷⁺	3	2in1设备与其它设备共享（键鼠共享场景）。

FlyMode

飞入飞出形变场景模式枚举。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

名称	值	说明
BOTTOM	0	从底部进行飞入飞出形变。
TOP	1	从顶部进行飞入飞出形变。

VisualEffect

VisualEffect效果类，用于将相应的效果添加到指定的组件上。在调用VisualEffect的方法前，需要先通过createEffect创建一个VisualEffect实例。

backgroundColorBlender

backgroundColorBlender(blender: BrightnessBlender): VisualEffect

将混合器添加至组件上以改变组件背景颜色，具体的更改效果由输入决定，目前仅支持提亮混合器。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
blender	BrightnessBlender	是	用于混合背景颜色的blender。

返回值：

类型	说明
VisualEffect	返回添加了背景颜色更改效果的VisualEffect。

示例：

let blender : uiEffect.BrightnessBlender =
  uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})
visualEffect.backgroundColorBlender(blender)

borderLight²⁰⁺

borderLight(lightPosition: common2D.Point3d, lightColor: common2D.Color, lightIntensity: number, borderWidth: number): VisualEffect

为圆角矩形组件边框添加3D光照效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
lightPosition	common2D.Point3d	是	光源在组件空间的3D位置，[-1, -1, 0]为组件左上角，[1, 1, 0]为组件的右下角，z轴分量越大，光源离组件平面越远，可照射区域越大。 x轴分量取值范围[-10, 10]，y轴分量取值范围[-10, 10]，z轴分量取值范围[0, 10]，超出范围会自动截断。
lightColor	common2D.Color	是	光源颜色，各元素取值范围为[0, 1]，超出范围会自动截断。
lightIntensity	number	是	光源强度，取值范围[0, 1]，数值越大光源亮度越大，超出范围会自动截断。
borderWidth	number	是	组件边框的受光宽度，取值范围为[0.0, 30.0]，超出范围会自动截断。设置为0.0时，组件边框无光照效果，数值越大，光可照亮的区域越宽。

返回值：

类型	说明
VisualEffect	返回了具有边框光照效果的VisualEffect。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { common2D, uiEffect } from '@kit.ArkGraphics2D'

@Entry
@Component
struct Index {
  @State point1:common2D.Point3d = {
    x:0,y:0,z:2
  }
  @State color1:common2D.Color = {
    red:1,green:1,blue:1,alpha:1
  }
  @State lightIntensity1:number = 1
  @State borderWidth:number = 20

  build() {
    Column() {
      Stack() {
        Image($r('app.media.man'))
          .width('646px')
          .height('900px')
          .borderRadius(10)
        Column()
          .width('646px')
          .height('900px')
          .borderRadius(10)
          .visualEffect(uiEffect.createEffect().borderLight(this.point1, this.color1, this.lightIntensity1,
            this.borderWidth))
      }
      .width('100%')
      .height('55%')
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#555')
  }
}

colorGradient²⁰⁺

colorGradient(colors: Array<Color>, positions: Array<common2D.Point>, strengths: Array<number>, alphaMask?: Mask): VisualEffect

此方法为组件添加颜色渐变效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
colors	Array<Color>	是	颜色数组，用于实现多颜色渐变。数组长度范围0到12，每个颜色值大于等于0。数组长度为0或大于12，或colors、positions和strengths的数组长度不一致，则无颜色渐变效果。
positions	Array<common2D.Point>	是	位置数组，颜色对应的位置。数组长度范围为0到12。数组长度为0或大于12，或colors、positions和strengths的数组长度不一致，则无颜色渐变效果。
strengths	Array<number>	是	强度数组，表示颜色对应的强度。数组长度范围为0到12，每一个强度值大于等于0。数组长度为0或大于12，或colors、positions和strengths的数组长度不一致时，则无颜色渐变效果。
alphaMask	Mask	否	遮罩alpha，颜色对应的alpha遮罩。不设置时，颜色渐变效果的透明度完全由colors参数决定。

返回值：

类型	说明
VisualEffect	返回具有颜色渐变效果的VisualEffect。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { common2D, uiEffect } from "@kit.ArkGraphics2D"

@Entry
@Component
struct ColorGradientExample {
  build() {
    Stack() {
      Stack() {}
      .visualEffect(uiEffect.createEffect()
        .colorGradient(
          [
            {red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0},
            {red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0},
            {red: 0.0, green: 0.0, blue: 1.0, alpha: 1.0},
            {red: 1.0, green: 1.0, blue: 1.0, alpha: 1.0},
          ],
          [
            {x: 0.1, y: 0.1},
            {x: 0.1, y: 0.9},
            {x: 0.9, y: 0.1},
            {x: 0.9, y: 0.9},
          ],
          [12.4, 7.8, 7.8, 10.0],
          uiEffect.Mask.createRippleMask({x: 0.5, y: 0.5}, 0.2, 0.1)
        )
      )
      .width("1024px")
      .height("1024px")
    }
    .width("100%")
    .height("100%")
  }
}

liquidMaterial²²⁺

liquidMaterial(param: LiquidMaterialEffectParam, useEffectMask: Mask, distortMask?: Mask, brightnessParam?: BrightnessParam): VisualEffect

此方法为组件添加材质效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
param	LiquidMaterialEffectParam	是	材质所需相关变量，用于控制材质显示，包含材质开关、折射系数、反射系数和扰动系数。
useEffectMask	Mask	是	声明是否使用模糊缓存。使用createUseEffectMask(true)创建的Mask实例使用模糊缓存；使用createUseEffectMask(false)创建的Mask实例不使用模糊缓存。
distortMask	Mask	否	材质扰动效果需要的扰动纹理，由使用pixelMap创建Mask实例时的图片纹理决定。当材质的扰动系数不为0时，需要为材质扰动预先设置一张纹理，否则无扰动效果。当材质的扰动系数为0或者此参数不填时，无扰动效果。
brightnessParam	BrightnessParam	否	为材质增加提亮效果。默认不添加提亮效果。

返回值：

类型	说明
VisualEffect	返回具有材质效果的VisualEffect。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from '@kit.ArkGraphics2D';

@Entry
@Component
struct Index {
  @State distortProgress: number = 0.;
  @State rippleProgress: number = 0.;
  @State distortFactor: number = 0.;
  @State materialFactor: number = 1.;
  @State refractionFactor: number = 1.;
  @State reflectionFactor: number = 1.;
  @State tintColorR: number = 1.;
  @State tintColorG: number = 1.;
  @State tintColorB: number = 1.;
  @State tintColorA: number = 1.;

  private GetMaterialVisualEffect(): uiEffect.VisualEffect {
    let effect: uiEffect.VisualEffect = uiEffect.createEffect();
    effect.liquidMaterial({
      enable: true,
      distortProgress : this.distortProgress,
      rippleProgress: this.rippleProgress,
      distortFactor: this.distortFactor,
      materialFactor : this.materialFactor,
      refractionFactor : this.refractionFactor,
      reflectionFactor: this.reflectionFactor,
      tintColor : [this.tintColorR, this.tintColorG, this.tintColorB, this.tintColorA],
      ripplePosition: undefined,
    },
      uiEffect.Mask.createUseEffectMask(true),
      );
    return effect;
  }

  build() {
    Stack() {
      EffectComponent() {
        Column()
          .position({ x: 200 + 'px', y: 200 + 'px' })
          .height(553 + 'px')
          .width(553 + 'px')
          .borderRadius(12)
          .visualEffect(this.GetMaterialVisualEffect())
      }
      .backgroundEffect({
        radius: 15,
      }, { disableSystemAdaptation: true })
      .width("100%").height("100%").align(Alignment.Center)
    }
    .backgroundImage($r('app.media.bg6'), ImageRepeat.NoRepeat)
    .width("100%").height("100%").align(Alignment.Center)
  }
}

Blender¹³⁺

type Blender = BrightnessBlender | HdrBrightnessBlender | HdrDarkenBlender

混合器类型，用于描述混合效果。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

类型	说明
BrightnessBlender	具有提亮效果的混合器。
HdrBrightnessBlender²⁰⁺	具有提亮效果的混合器（支持HDR）。
HdrDarkenBlender	具有压暗效果的混合器（支持HDR）。起始版本： 26.0.0

BrightnessBlender

提亮混合器，用于将提亮效果添加到指定的组件上。在调用BrightnessBlender前，需要先通过createBrightnessBlender创建一个BrightnessBlender实例。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

名称	类型	只读	可选	说明
cubicRate	number	否	否	灰度调整的三阶系数。取值范围[-20, 20]。
quadraticRate	number	否	否	灰度调整的二阶系数。取值范围[-20, 20]。
linearRate	number	否	否	灰度调整的线性系数。取值范围[-20, 20]。
degree	number	否	否	灰度调整的比例。取值范围[-20, 20]。
saturation	number	否	否	提亮的基准饱和度。取值范围[0, 20]。
positiveCoefficient	[number, number, number]	否	否	基于基准饱和度的RGB正向调整参数。每个number的取值范围[-20, 20]。
negativeCoefficient	[number, number, number]	否	否	基于基准饱和度的RGB负向调整参数。每个number的取值范围[-20, 20]。
fraction	number	否	否	提亮效果的混合比例。取值范围[0, 1]，超出边界会在实现时自动截断。

HdrBrightnessBlender²⁰⁺

支持HDR的提亮混合器（继承自BrightnessBlender），用于将提亮效果添加到指定的组件上。在调用HdrBrightnessBlender前，需要先通过createHdrBrightnessBlender创建一个HdrBrightnessBlender实例。

该混合器参数可参考BrightnessBlender。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

HdrDarkenBlender

支持HDR的压暗混合器，用于将压暗效果添加到指定的组件上。在调用HdrDarkenBlender前，需要先通过createHdrDarkenBlender创建一个HdrDarkenBlender实例。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

名称	类型	只读	可选	说明
hdrBrightnessRatio	number	否	否	HDR的提亮倍数。取值范围[1.0, 设备当前支持最大提亮倍数]。设置小于1.0的值时，按值为1.0处理；当值等于1.0时，为组件原本亮度；设置大于设备当前支持最大提亮倍数的值时，按值为设备当前支持最大提亮倍数处理，支持最大提亮倍数 = 设备最大亮度 / 设备默认亮度。设备最大亮度通过hdc命令获取：param get const.display.brightness.max 设备默认亮度通过hdc命令获取：param get const.display.brightness.default
grayscaleFactor	[number, number, number]	否	是	将RGB颜色转换为灰度值，该公式可根据色域切换。三个分量均无边界限制。默认值为标准灰度权重[0.299, 0.587, 0.114]。

Color²⁰⁺

RGBA格式的颜色描述。

系统能力： SystemCapability.Graphics.Drawing

名称	类型	只读	可选	说明
red	number	是	是	颜色的R分量（红色）。值大于等于0，当值小于0时无效。
green	number	是	是	颜色的G分量（绿色）。值大于等于0，当值小于0时无效。
blue	number	是	是	颜色的B分量（蓝色）。值大于等于0，当值小于0时无效。
alpha	number	是	是	颜色的A分量（透明度）。值大于等于0，当值小于0时无效。

LiquidMaterialEffectParam²²⁺

材质的各项参数及其用途的详细说明。

系统能力： SystemCapability.Graphics.Drawing

名称	类型	只读	可选	说明
enable	boolean	否	否	是否开启材质效果。 true表示开启材质效果，false表示关闭材质效果。
distortProgress	number	否	否	扰动效果进度。取值范围[0, 1]，小于0时取值为0，大于1时取值为1。0表示开始扰动，1表示结束扰动。
distortFactor	number	否	否	扰动效果系数。值大于等于0，值小于0时表示无扰动效果。
rippleProgress	number	否	否	水波效果进度。值大于等于0，值小于0时表示无水波效果。
ripplePosition	Array<[number, number]>	否	是	水波效果作用的位置。数组中每个位置包含x和y两个维度，最多支持10个位置坐标传入。传入超出10个位置坐标则整体无效。
refractionFactor	number	否	否	折射效果系数。取值范围[0, 10]，小于0时取值为0，大于10时取值为10。值为0表示无折射效果，值越大折射强度越高。
reflectionFactor	number	否	否	反射系数。取值范围[0, 10]，小于0时取值为0，大于10时取值为10。值为0表示无反射效果，值越大反射强度越高。
materialFactor	number	否	否	材质系数。取值范围[0, 1]，小于0时取值为0，大于1时取值为1。值为0表示无材质效果，使用叠加颜色填充，值越大材质效果越明显。
tintColor	[number, number, number, number]	否	否	材质叠加的颜色，四个变量分别对应RGBA。取值范围[0, 1]，小于0时取值为0，大于1时取值为1。

BrightnessParam²²⁺

材质提亮参数的详细说明。

系统能力： SystemCapability.Graphics.Drawing

名称	类型	只读	可选	说明
rate	number	否	否	灰度调整线性系数。取值范围[-1, 1]，小于-1时取值为-1，大于1时取值为1，值越大，灰度调整效果越强。
lightUpDegree	number	否	否	灰度调整比例。取值范围[-1, 1]，小于-1时取值为-1，大于1时取值为1，值越大，灰度调整效果越强。
cubicCoeff	number	否	否	灰度调整三阶系数。取值范围[-1, 1]，小于-1时取值为-1，大于1时取值为1，值越大，灰度调整效果越强。
quadCoeff	number	否	否	灰度调整二阶系数。取值范围[-1, 1]，小于-1时取值为-1，大于1时取值为1，值越大，灰度调整效果越强。
saturation	number	否	否	提亮基准饱和度。取值范围[0, 1]，小于0时取值为0，大于1时取值为1，值越大基准饱和度越高。
posRgb	[number, number, number]	否	否	基于基准饱和度的正向调整系数。取值范围[-1, 1]，小于-1时取值为-1，大于1时取值为1，值越大饱和度越高。
negRgb	[number, number, number]	否	否	基于基准饱和度的负向调整系数。取值范围[-1, 1]，小于-1时取值为-1，大于1时取值为1，值越大饱和度越低。
fraction	number	否	否	提亮效果混合比例。取值范围[0, 1]，小于0时取值为0，大于1时取值为1，值越大，提亮效果越弱。

Mask²⁰⁺

Mask效果类，作为Filter以及VisualEffect的输入使用。

createRippleMask²⁰⁺

static createRippleMask(center: common2D.Point, radius: number, width: number, offset?: number): Mask

通过输入波环圆心的位置、半径和宽度创建波环遮罩效果Mask实例，具体的效果由输入的参数决定。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
center	common2D.Point	是	设置波环圆心在组件上的位置，[0, 0]为组件左上角，[1, 1]为组件的右下角。取值范围[-10, 10]，超出边界会在实现时自动截断。
radius	number	是	设置波环的半径，半径为1等于组件的高度。取值范围[0, 10]，超出边界会在实现时自动截断。
width	number	是	设置波环的宽度。取值范围[0, 10]，超出边界会在实现时自动截断。
offset	number	否	设置波峰位置的偏移。默认值为0，表示波峰在波环的正中心； -1.0表示波峰在波环的最内侧； 1.0表示波峰在波环的最外侧。取值范围[-1, 1]，超出边界会在实现时自动截断。

返回值：

类型	说明
Mask	返回具有波环遮罩效果的Mask。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

  let mask = uiEffect.Mask.createRippleMask({x:0.5, y:1.0}, 0.5, 0.3, 0.0);

createPixelMapMask²⁰⁺

static createPixelMapMask(pixelMap: image.PixelMap, srcRect: common2D.Rect, dstRect: common2D.Rect, fillColor?: Color): Mask

通过输入的pixelMappixelMap的待绘制区域、挂载节点的绘制区域和绘制区域外填充的颜色创建具有缩放效果的Mask实例，具体的效果由输入的参数决定。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
pixelMap	image.PixelMap	是	image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见图片开发指导。
srcRect	common2D.Rect	是	pixelMap的待绘制区域。图片最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。right需大于left，bottom需大于top。
dstRect	common2D.Rect	是	pixelMap在mask挂载的节点上的绘制区域。节点最左侧和最上侧对应位置0，最右侧和最下侧对应位置1。right需大于left，bottom需大于top。
fillColor	Color	否	节点上在pixelMap绘制区域之外的区域填充的颜色，各元素取值范围为[0, 1]，默认透明色，小于0的转为0，大于1的转为1。

返回值：

类型	说明
Mask	返回具有pixelMap缩放效果的Mask。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { image } from "@kit.ImageKit";
import { uiEffect, common2D } from "@kit.ArkGraphics2D";
import { BusinessError } from '@kit.BasicServicesKit'

const color = new ArrayBuffer(96);
let opts : image.InitializationOptions = {
  editable: true,
  pixelFormat: 3,
  size: {
    height: 4,
    width: 6
  }
}
image.createPixelMap(color, opts).then((pixelMap) => {
  let srcRect : common2D.Rect = {
    left: 0,
    top: 0,
    right: 1,
    bottom: 1
  }
  let dstRect : common2D.Rect = {
    left: 0,
    top: 0,
    right: 1,
    bottom: 1
  }
  let fillColor : uiEffect.Color = {
    red: 0,
    green: 0,
    blue: 0,
    alpha: 1
  }
  let mask = uiEffect.Mask.createPixelMapMask(pixelMap, srcRect, dstRect, fillColor);
}).catch((error: BusinessError)=>{
  console.error(`Failed to create pixelmap. code is ${error.code}, message is ${error.message}`);
})

createPixelMapMask²²⁺

static createPixelMapMask(pixelMap: image.PixelMap): Mask

通过输入的pixelMap创建Mask实例。该接口不会对传入的pixelMap进行缩放处理。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
pixelMap	image.PixelMap	是	image模块创建的PixelMap实例。可通过图片解码或直接创建获得，具体可见图片开发指导。

返回值：

类型	说明
Mask	返回具有pixelMap的Mask。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from '@kit.ArkGraphics2D';
import { image } from '@kit.ImageKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  @State distortProgress: number = 0.;
  @State rippleProgress: number = 0.;
  @State distortFactor: number = 0.;
  @State materialFactor: number = 1.;
  @State refractionFactor: number = 1.;
  @State reflectionFactor: number = 1.;
  @State tintColorR: number = 1.;
  @State tintColorG: number = 1.;
  @State tintColorB: number = 1.;
  @State tintColorA: number = 1.;
  @State pixelMapDistort: image.PixelMap | undefined = this.getPixelMap();

  private getPixelMap(): image.PixelMap | undefined {
    try {
      let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
      // this path should be created in local
      const path: string = context.resourceDir + "/perlin_worley_noise_3d_64.bmp";
      const imageSource: image.ImageSource = image.createImageSource(path);
      if (!imageSource) {
        return undefined;
      }
      const pixelMap: image.PixelMap = imageSource.createPixelMapSync();
      imageSource.release();
      return pixelMap;
    } catch (err) {
      return undefined;
    }
  }

  private GetMaterialVisualEffect(): uiEffect.VisualEffect {
    let effect: uiEffect.VisualEffect = uiEffect.createEffect();
    effect.liquidMaterial({
      enable: true,
      distortProgress : this.distortProgress,
      rippleProgress: this.rippleProgress,
      distortFactor: this.distortFactor,
      materialFactor : this.materialFactor,
      refractionFactor : this.refractionFactor,
      reflectionFactor: this.reflectionFactor,
      tintColor : [this.tintColorR, this.tintColorG, this.tintColorB, this.tintColorA],
      ripplePosition: undefined,
    },
      uiEffect.Mask.createUseEffectMask(true),
      uiEffect.Mask.createPixelMapMask(this.pixelMapDistort), // createImageMask使用示例
      );
    return effect;
  }

  build() {
    Stack() {
      EffectComponent() {
        Column()
          .position({ x: 200 + 'px', y: 200 + 'px' })
          .height(553 + 'px')
          .width(553 + 'px')
          .borderRadius(12)
          .visualEffect(this.GetMaterialVisualEffect())
      }
      .backgroundEffect({
        radius: 15,
      }, { disableSystemAdaptation: true })
      .width("100%").height("100%").align(Alignment.Center)
    }
    .backgroundImage($r('app.media.bg6'), ImageRepeat.NoRepeat) // the image should be created in local
    .width("100%").height("100%").align(Alignment.Center)
  }
}

createRadialGradientMask²⁰⁺

static createRadialGradientMask(center: common2D.Point, radiusX: number, radiusY: number, values: Array<[number, number]>): Mask

通过输入椭圆中心点的位置、长短轴和形状参数创建椭圆遮罩效果Mask实例，具体的效果由输入的参数决定。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
center	common2D.Point	是	设置椭圆的中心点，[0, 0]为组件左上角，[1, 1]为组件的右下角。取值范围[-10, 10]，可取浮点数，超出边界会在实现时自动截断。
radiusX	number	是	设置椭圆的长轴，半径为1等于组件的高度。取值范围[0, 10]，可取浮点数，超出边界会在实现时自动截断。
radiusY	number	是	设置椭圆的短轴，半径为1等于组件的高度。取值范围[0, 10]，可取浮点数，超出边界会在实现时自动截断。
values	Array<[number, number]>	是	数组中保存的二元数组表示梯度：[RGBA颜色, 位置]。RGBA颜色四通道使用相同的值，可看作一个灰度值；位置表示沿径向方向向外时RGBA颜色对应的分布位置；RGBA颜色与位置的取值范围均为[0, 1]，可取浮点数，小于0的转为0，大于1的转为1。位置参数值须严格递增，Array数组中二元数组个数必须大于等于2，二元数组中的元素不能为空，否则该椭圆分布效果不生效。

返回值：

类型	说明
Mask	返回椭圆形状的径向分布效果的灰度Mask。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from '@kit.ArkGraphics2D'
// values: [[1.0, 0.5], [1.0, 1.0]] => color0: 1.0; color1: 1.0; position0: 0.5; position1: 1.0
let mask = uiEffect.Mask.createRadialGradientMask({x: 0.0, y: 0.0}, 0.5, 0.5, [[1.0, 0.5], [1.0, 1.0]]);
@Entry
@Component
struct RadialGradientMaskExample {
  build() {
    Stack() {
      Image($rawfile('test.jpg'))
      Column()
        .width('100%')
        .height('100%')
        // Mask作为Filter的入参实现对应的效果，该效果中Mask是在屏幕左上角的四分之一圆环
        .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, null, mask))
    }
  }
}

createWaveGradientMask²⁰⁺

static createWaveGradientMask(center: common2D.Point, width: number, propagationRadius: number, blurRadius: number, turbulenceStrength?: number): Mask

输入波源中心位置、单波参数创建单波遮罩效果Mask实例。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
center	common2D.Point	是	设置单波波源的中心点，[0, 0]为组件左上角，[1, 1]为组件的右下角。取值范围[-10, 10]，可取浮点数，超出边界会在实现时自动截断。
width	number	是	设置单波圆环的宽度。取值范围[0, 5]，可取浮点数，超出边界会在实现时自动截断。
propagationRadius	number	是	设置单波圆环的扩散外径。取值范围[0, 10]，可取浮点数，超出边界会在实现时自动截断。
blurRadius	number	是	设置单波圆环的模糊外径，模糊半径为0则是实边圆环，否则是虚边圆环。取值范围[0, 5]，可取浮点数，超出边界会在实现时自动截断。
turbulenceStrength	number	否	设置单波圆环的湍流强度，默认值为0，强度为0则是规则圆环，否则圆环边缘会湍流扭曲。取值范围[-1, 1]，可取浮点数，超出边界会在实现时自动截断。

返回值：

类型	说明
Mask	返回单个水波形状的灰度Mask。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from "@kit.ArkGraphics2D";
// center: [0.5, 0.5]；width: 0.01; propagationRadius: 0.5; blurRadius: 0.1; turbulenceStrength: 0.1
let mask = uiEffect.Mask.createWaveGradientMask({x: 0.5, y: 0.5}, 0.01, 0.5, 0.1, 0.1);
@Entry
@Component
struct WaveGradientMaskExample {
  build() {
    Stack() {
      Image($rawfile('test.jpg'))
      Column()
        .width('100%')
        .height('100%')
        // 将Mask作为Filter的参数，实现屏幕中心向四周扩散的水波形状效果。
        .backgroundFilter(uiEffect.createFilter().edgeLight(1.0, null, mask))
    }
  }
}

createUseEffectMask²²⁺

static createUseEffectMask(useEffect: boolean): Mask

创建并设置Mask实例是否使用模糊缓存。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

参数：

参数名	类型	必填	说明
useEffect	boolean	是	标记是否使用模糊缓存。值为true，表示使用，会正常显示模糊效果；值为false，表示不使用，不显示模糊效果。

返回值：

类型	说明
Mask	返回是否使用模糊缓存标记的Mask。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission verification failed. A non-system application calls a system API.

示例：

import { uiEffect } from '@kit.ArkGraphics2D';

@Entry
@Component
struct Index {
  @State distortProgress: number = 0.;
  @State rippleProgress: number = 0.;
  @State distortFactor: number = 0.;
  @State materialFactor: number = 1.;
  @State refractionFactor: number = 1.;
  @State reflectionFactor: number = 1.;
  @State tintColorR: number = 1.;
  @State tintColorG: number = 1.;
  @State tintColorB: number = 1.;
  @State tintColorA: number = 1.;

  private GetMaterialVisualEffect(): uiEffect.VisualEffect {
    let effect: uiEffect.VisualEffect = uiEffect.createEffect();
    effect.liquidMaterial({
        enable: true,
        distortProgress : this.distortProgress,
        rippleProgress: this.rippleProgress,
        distortFactor: this.distortFactor,
        materialFactor : this.materialFactor,
        refractionFactor : this.refractionFactor,
        reflectionFactor: this.reflectionFactor,
        tintColor : [this.tintColorR, this.tintColorG, this.tintColorB, this.tintColorA],
        ripplePosition: undefined,
      },
      uiEffect.Mask.createUseEffectMask(true), // useEffectMask使用示例
    );
    return effect;
  }

  build() {
    Stack() {
      EffectComponent() {
        Column()
          .position({ x: 200 + 'px', y: 200 + 'px' })
          .height(553 + 'px')
          .width(553 + 'px')
          .borderRadius(12)
          .visualEffect(this.GetMaterialVisualEffect())
      }
      .backgroundEffect({
        radius: 15,
      }, { disableSystemAdaptation: true })
      .width("100%").height("100%").align(Alignment.Center)
    }
    .backgroundImage($r('app.media.bg6'), ImageRepeat.NoRepeat)
    .width("100%").height("100%").align(Alignment.Center)
  }
}

BrightnessBlenderParam

BrightnessBlender参数列表。

系统能力： SystemCapability.Graphics.Drawing

系统接口： 此接口为系统接口。

名称	类型	只读	可选	说明
cubicRate	number	否	否	灰度调整的三阶系数。取值范围[-20, 20]。
quadraticRate	number	否	否	灰度调整的二阶系数。取值范围[-20, 20]。
linearRate	number	否	否	灰度调整的线性系数。取值范围[-20, 20]。
degree	number	否	否	灰度调整的比例。取值范围[-20, 20]。
saturation	number	否	否	提亮的基准饱和度。取值范围[0, 20]。
positiveCoefficient	[number, number, number]	否	否	基于基准饱和度的RGB正向调整参数。每个number的取值范围[-20, 20]。
negativeCoefficient	[number, number, number]	否	否	基于基准饱和度的RGB负向调整参数。每个number的取值范围[-20, 20]。
fraction	number	否	否	提亮效果的混合比例。取值范围[0, 1]，超出边界会在实现时自动截断。

HeatDistortionEffectParam

热浪扭曲效果的参数。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Graphics.Drawing

名称	类型	只读	可选	说明
intensity	number	否	否	热浪扭曲的强度。取值范围[0, 1]，超出边界会在实现时自动截断。 0表示无扭曲，1表示最大扭曲程度。
noiseScale	number	否	否	热浪扭曲的噪声缩放，控制噪声纹理的细度。取值范围[0.1, 5.0]，超出边界会在实现时自动截断。值越大，噪声纹理越细腻。
riseWeight	number	否	否	热浪扭曲的上升权重，控制气泡的上升速度。取值范围[0, 1]，超出边界会在实现时自动截断。值越大，向上运动越明显。
progress	number	否	否	热浪扭曲的动画进度。取值范围[0, 1]，超出边界会在实现时自动截断。 0对应动画开始，1对应动画结束。

BlurBubblesRiseEffectParam

模糊气泡上升效果的参数。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.Graphics.Drawing

名称	类型	只读	可选	说明
blurIntensity	number	否	否	模糊气泡上升效果的高斯模糊强度。取值范围[0, 1]，超出边界会在实现时自动截断。 0表示无模糊，1表示最大模糊程度。
mixStrength	number	否	否	原图与模糊图的混合强度。取值范围[0, 1]，超出边界会在实现时自动截断。 0对应原图，1对应模糊后的图像。
progress	number	否	否	模糊气泡上升效果的动画进度。取值范围[0, 1]，超出边界会在实现时自动截断。 0对应动画开始，1对应动画结束。
maskImage	image.PixelMap	否	否	模糊气泡上升效果的遮罩图像，控制模糊气泡区域。被遮罩的区域有模糊效果，未遮罩的区域无模糊效果。

@ohos.graphics.uiEffect (效果级联)(系统接口)

导入模块

uiEffect.createBrightnessBlender

uiEffect.createHdrBrightnessBlender20+

uiEffect.createHdrDarkenBlender

Filter

pixelStretch

waterRipple

flyInFlyOutEffect

distort13+

radiusGradientBlur19+

bezierWarp20+

colorGradient20+

contentLight20+

edgeLight20+

displacementDistort20+

maskDispersion20+

maskTransition20+

directionLight20+

variableRadiusBlur20+

heatDistortion

blurBubblesRise

TileMode

WaterRippleMode

FlyMode

VisualEffect

backgroundColorBlender

borderLight20+

colorGradient20+

liquidMaterial22+

Blender13+

BrightnessBlender

HdrBrightnessBlender20+

HdrDarkenBlender

Color20+

LiquidMaterialEffectParam22+

BrightnessParam22+

Mask20+

createRippleMask20+

createPixelMapMask20+

createPixelMapMask22+

createRadialGradientMask20+

createWaveGradientMask20+

createUseEffectMask22+

BrightnessBlenderParam

HeatDistortionEffectParam

BlurBubblesRiseEffectParam

uiEffect.createHdrBrightnessBlender²⁰⁺

distort¹³⁺

radiusGradientBlur¹⁹⁺

bezierWarp²⁰⁺

colorGradient²⁰⁺

contentLight²⁰⁺

edgeLight²⁰⁺

displacementDistort²⁰⁺

maskDispersion²⁰⁺

maskTransition²⁰⁺

directionLight²⁰⁺

variableRadiusBlur²⁰⁺

borderLight²⁰⁺

colorGradient²⁰⁺

liquidMaterial²²⁺

Blender¹³⁺

HdrBrightnessBlender²⁰⁺

Color²⁰⁺

LiquidMaterialEffectParam²²⁺

BrightnessParam²²⁺

Mask²⁰⁺

createRippleMask²⁰⁺

createPixelMapMask²⁰⁺

createPixelMapMask²²⁺

createRadialGradientMask²⁰⁺

createWaveGradientMask²⁰⁺

createUseEffectMask²²⁺