1# @ohos.graphics.uiEffect (效果级联)(系统接口) 2 3本模块提供组件效果的一些基础能力，包括模糊、边缘像素扩展、提亮等。效果被分为Filter和VisualEffect大类，同类效果可以级联在一个效果大类的实例下。在实际开发中，模糊可用于背景虚化，提亮可用于亮屏显示等。 4 5- [Filter](#filter)：用于添加指定Filter效果到组件上。 6- [VisualEffect](#visualeffect)：用于添加指定VisualEffect效果到组件上。 7 8> **说明：** 9> 10> - 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 11> - 页面仅包含本模块的系统接口，其他公开接口参见[ohos.graphics.uiEffect (效果级联)](js-apis-uiEffect.md)。 12 13## 导入模块 14 15```ts 16import { uiEffect } from "@kit.ArkGraphics2D"; 17``` 18## uiEffect.createBrightnessBlender 19createBrightnessBlender(param: BrightnessBlenderParam): BrightnessBlender 20 21创建BrightnessBlender实例用于给组件添加提亮效果。 22 23**系统能力：** SystemCapability.Graphics.Drawing 24 25**系统接口：** 此接口为系统接口。 26 27**参数：** 28| 参数名 | 类型 | 必填 | 说明 | 29| ------ | ------------------------------------------------- | ---- | --------------------------- | 30| param | [BrightnessBlenderParam](#brightnessblenderparam) | 是 | 实现提亮效果的参数。 | 31 32**返回值：** 33 34| 类型 | 说明 | 35| ---------------------------------------- | ----------------------- | 36| [BrightnessBlender ](#brightnessblender) | 返回设置了提亮效果参数的BrightnessBlender。 | 37 38**示例：** 39 40```ts 41let blender : uiEffect.BrightnessBlender = 42 uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 43 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 44``` 45 46## Filter 47Filter效果类，用于将相应的效果添加到指定的组件上。在调用Filter的方法前，需要先通过[createFilter](js-apis-uiEffect.md#uieffectcreatefilter)创建一个Filter实例。 48 49### pixelStretch 50pixelStretch(stretchSizes: Array\<number\>, tileMode: TileMode): Filter 51 52将边缘像素扩展效果添加至组件上。 53 54**系统能力：** SystemCapability.Graphics.Drawing 55 56**系统接口：** 此接口为系统接口。 57 58**参数：** 59| 参数名 | 类型 | 必填 | 说明 | 60| ------------- | --------------------- | ---- | ------------------------- | 61| stretchSizes | Array\<number\> | 是 | 上下左右四个方向边缘像素扩展的百分比比例，取值范围为[-1, 1]。<br/>正值表示向外扩展，上下左右四个方向分别用指定原图比例的边缘像素填充。负值表示内缩，但是最终图像大小不变。<br/>注意四个方向对应的参数需统一为非正值或非负值。| 62| tileMode | [TileMode](#tilemode) | 是 | 边缘像素扩展的像素填充模式。 | 63 64 65**返回值：** 66 67| 类型 | 说明 | 68| ----------------- | --------------------------------- | 69| [Filter](#filter) | 返回挂载了边缘像素扩展效果的Filter。 | 70 71**示例：** 72 73```ts 74filter.pixelStretch([0.2, 0.2, 0.2, 0.2], uiEffect.TileMode.CLAMP) 75``` 76 77### waterRipple 78waterRipple(progress: number, waveCount: number, x: number, y: number, rippleMode: WaterRippleMode): Filter 79 80将水波纹效果添加至组件上。 81 82**系统能力：** SystemCapability.Graphics.Drawing 83 84**系统接口：** 此接口为系统接口。 85 86**参数：** 87| 参数名 | 类型 | 必填 | 说明 | 88| ------------- | --------------------- | ---- | ------------------------- | 89| progress | number | 是 | 表示水波纹的进度，取值范围为[0, 1]。<br/>水波纹进度越趋向于1，水波纹展示越完全。<br/>超出取值范围水波纹不会出现效果。| 90| waveCount | number | 是 | 水波纹波动时波纹的个数，取值范围为[1, 3]。<br/>水波纹的个数只能取整数，如果为浮点数或超出取值范围，水波纹不会出现效果。 | 91| x | number | 是 | 水波纹中心在屏幕中第一次出现的x轴位置。<br/>水波纹对屏幕进行归一化处理，左上角的坐标为（0, 0），右上角坐标为（1, 0）。<br/>当x取值为负值时，代表在屏幕左侧。| 92| y | number | 是 | 水波纹中心在屏幕中第一次出现的y轴位置。<br/>水波纹对屏幕进行归一化处理，左上角的坐标为（0, 0），左下角坐标为（0, 1）。<br/>当y取值为负值时，代表在屏幕上方。 | 93| rippleMode | [WaterRippleMode](#waterripplemode) | 是 | 水波纹的场景模式。| 94 95 96**返回值：** 97 98| 类型 | 说明 | 99| ----------------- | --------------------------------- | 100| [Filter](#filter) | 返回挂载了水波纹效果的Filter。 | 101 102**错误码：** 103 104以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 105 106| 错误码ID | 错误信息 | 107| ------- | -------------------------------- | 108| 202 | Permission verification failed. A non-system application calls a system API. | 109 110**示例：** 111 112```ts 113filter.waterRipple(0.5, 2, 0.5, 0.5, uiEffect.WaterRippleMode.SMALL2SMALL) 114``` 115 116### flyInFlyOutEffect 117flyInFlyOutEffect(degree: number, flyMode: FlyMode): Filter 118 119将飞入飞出形变效果添加至组件上。 120 121**系统能力：** SystemCapability.Graphics.Drawing 122 123**系统接口：** 此接口为系统接口。 124 125**参数：** 126| 参数名 | 类型 | 必填 | 说明 | 127| ------------- | --------------------- | ---- | ------------------------- | 128| degree | number | 是 | 表示控制飞入飞出形变的程度，取值范围为[0, 1]。<br/>越靠近1，变形程度越明显。<br/>超出取值范围形变不会出现效果。| 129| flyMode | [FlyMode](#flymode) | 是 | 飞入飞出的场景模式。<br/>BOTTOM表示从设备底部飞入飞出形变场景。<br/>TOP表示从设备顶部飞入飞出形变场景。 | 130 131 132**返回值：** 133 134| 类型 | 说明 | 135| ----------------- | --------------------------------- | 136| [Filter](#filter) | 返回挂载了飞入飞出形变效果的Filter。 | 137 138**错误码：** 139 140以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 141 142| 错误码ID | 错误信息 | 143| ------- | -------------------------------- | 144| 202 | Permission verification failed. A non-system application calls a system API. | 145 146**示例：** 147 148```ts 149filter.flyInFlyOutEffect(0.5, uiEffect.FlyMode.TOP) 150``` 151 152### distort<sup>13+</sup> 153distort(distortionK: number): Filter 154 155将透镜畸变效果添加至组件上。 156 157**系统能力：** SystemCapability.Graphics.Drawing 158 159**系统接口：** 此接口为系统接口。 160 161**参数：** 162| 参数名 | 类型 | 必填 | 说明 | 163| ------------- | --------------------- | ---- | ------------------------- | 164| distortionK | number | 是 | 畸变系数，表示透镜畸变的程度，取值范围为[-1, 1]。畸变系数设置小于-1的值时，按值为-1处理；设置大于1的值时，按值为1处理。| 165 166 167如上图是对图片组件分别设置畸变参数为-1，0，0.5，1的绘制结果。畸变参数小于0时，效果为桶形畸变；大于0时，效果为枕形畸变；越接近0时，畸变程度越小，等于0时，没有畸变效果。 168 169**返回值：** 170 171| 类型 | 说明 | 172| ----------------- | --------------------------------- | 173| [Filter](#filter) | 返回挂载了透镜畸变效果的Filter。 | 174 175**错误码：** 176 177以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 178 179| 错误码ID | 错误信息 | 180| ------- | --------------------------------------------| 181| 202 | Permission verification failed. A non-system application calls a system API. | 182 183**示例：** 184 185```ts 186filter.distort(-0.5) 187``` 188 189## TileMode 190像素填充模式枚举。 191 192**系统能力：** SystemCapability.Graphics.Drawing 193 194**系统接口：** 此接口为系统接口。 195 196| 名称 | 值 | 说明 | 197| ------ | - | ---- | 198| CLAMP | 0 | 截断。 | 199| REPEAT | 1 | 重复。 | 200| MIRROR | 2 | 镜像。 | 201| DECAL | 3 | 透明。 | 202 203## WaterRippleMode 204水波纹场景模式枚举。 205 206**系统能力：** SystemCapability.Graphics.Drawing 207 208**系统接口：** 此接口为系统接口。 209 210| 名称 | 值 | 说明 | 211| ------ | - | ---- | 212| SMALL2MEDIUM_RECV | 0 | 手机碰2in1设备（接收端）。 | 213| SMALL2MEDIUM_SEND | 1 | 手机碰2in1设备（发送端）。 | 214| SMALL2SMALL | 2 | 手机碰手机。 | 215 216## FlyMode 217飞入飞出形变场景模式枚举。 218 219**系统能力：** SystemCapability.Graphics.Drawing 220 221**系统接口：** 此接口为系统接口。 222 223| 名称 | 值 | 说明 | 224| ------ | - | ---- | 225| BOTTOM | 0 | 从底部进行飞入飞出形变。 | 226| TOP | 1 | 从顶部进行飞入飞出形变。 | 227 228## VisualEffect 229VisualEffect效果类，用于将相应的效果添加到指定的组件上。在调用VisualEffect的方法前，需要先通过[createEffect](js-apis-uiEffect.md#uieffectcreateeffect)创建一个VisualEffect实例。 230 231### backgroundColorBlender 232backgroundColorBlender(blender: BrightnessBlender): VisualEffect 233 234将混合器添加至组件上以改变组件背景颜色，具体的更改效果由输入决定，目前仅支持提亮混合器。 235 236**系统能力：** SystemCapability.Graphics.Drawing 237 238**系统接口：** 此接口为系统接口。 239 240**参数：** 241| 参数名 | 类型 | 必填 | 说明 | 242| ------- | ---------------------------------------- | ---- | ------------------------- | 243| blender | [BrightnessBlender](#brightnessblender) | 是 | 用于混合背景颜色的blender。 | 244 245**返回值：** 246 247| 类型 | 说明 | 248| ----------------------------- | ------------------------------------------------- | 249| [VisualEffect](#visualeffect) | 返回添加了背景颜色更改效果的VisualEffect。 | 250 251**示例：** 252 253```ts 254let blender : uiEffect.BrightnessBlender = 255 uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 256 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 257visualEffect.backgroundColorBlender(blender) 258``` 259 260## Blender<sup>13+</sup> 261 262type Blender = BrightnessBlender 263 264混合器类型，用于描述混合效果。 265 266**系统能力：** SystemCapability.Graphics.Drawing 267 268**系统接口：** 此接口为系统接口。 269 270| 类型 | 说明 | 271| ----------------------------- | ------------------------------------------------- | 272| [BrightnessBlender](#brightnessblender) | 具有提亮效果的混合器。 | 273 274## BrightnessBlender 275提亮混合器，用于将提亮效果添加到指定的组件上。在调用BrightnessBlender前，需要先通过[createBrightnessBlender](#uieffectcreatebrightnessblender)创建一个BrightnessBlender实例。 276 277**系统能力：** SystemCapability.Graphics.Drawing 278 279**系统接口：** 此接口为系统接口。 280 281| 名称 | 类型 | 只读 | 可选 | 说明 | 282| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 283| cubicRate | number | 否 | 否 | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。 | 284| quadraticRate | number | 否 | 否 | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。 | 285| linearRate | number | 否 | 否 | 灰度调整的线性系数。<br/>取值范围[-20, 20]。 | 286| degree | number | 否 | 否 | 灰度调整的比例。<br/>取值范围[-20, 20]。 | 287| saturation | number | 否 | 否 | 提亮的基准饱和度。<br/>取值范围[0, 20]。 | 288| positiveCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 | 289| negativeCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 | 290| fraction | number | 否 | 否 | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。 | 291 292## BrightnessBlenderParam 293BrightnessBlender参数列表。 294 295**系统能力：** SystemCapability.Graphics.Drawing 296 297**系统接口：** 此接口为系统接口。 298 299| 名称 | 类型 | 只读 | 可选 | 说明 | 300| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 301| cubicRate | number | 否 | 否 | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。 | 302| quadraticRate | number | 否 | 否 | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。 | 303| linearRate | number | 否 | 否 | 灰度调整的线性系数。<br/>取值范围[-20, 20]。 | 304| degree | number | 否 | 否 | 灰度调整的比例。<br/>取值范围[-20, 20]。 | 305| saturation | number | 否 | 否 | 提亮的基准饱和度。<br/>取值范围[0, 20]。 | 306| positiveCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 | 307| negativeCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 | 308| fraction | number | 否 | 否 | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。 |
