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```ts 105filter.waterRipple(0.5, 2, 0.5, 0.5, uiEffect.WaterRippleMode.SMALL2SMALL) 106``` 107 108### flyInFlyOutEffect 109flyInFlyOutEffect(degree: number, flyMode: FlyMode): Filter 110 111将飞入飞出形变效果添加至组件上。 112 113**系统能力：** SystemCapability.Graphics.Drawing 114 115**系统接口：** 此接口为系统接口。 116 117**参数：** 118| 参数名 | 类型 | 必填 | 说明 | 119| ------------- | --------------------- | ---- | ------------------------- | 120| degree | number | 是 | 表示控制飞入飞出形变的程度，取值范围为[0, 1]。<br/>越靠近1，变形程度越明显。<br/>超出取值范围形变不会出现效果。| 121| flyMode | [FlyMode](#flymode) | 是 | 飞入飞出的场景模式。<br/>BOTTOM表示从设备底部飞入飞出形变场景。<br/>TOP表示从设备顶部飞入飞出形变场景。 | 122 123 124**返回值：** 125 126| 类型 | 说明 | 127| ----------------- | --------------------------------- | 128| [Filter](#filter) | 返回挂载了飞入飞出形变效果的Filter。 | 129 130**示例：** 131 132```ts 133filter.flyInFlyOutEffect(0.5, uiEffect.FlyMode.TOP) 134``` 135 136### distort<sup>13+</sup> 137distort(distortionK: number): Filter 138 139将透镜畸变效果添加至组件上。 140 141**系统能力：** SystemCapability.Graphics.Drawing 142 143**系统接口：** 此接口为系统接口。 144 145**参数：** 146| 参数名 | 类型 | 必填 | 说明 | 147| ------------- | --------------------- | ---- | ------------------------- | 148| distortionK | number | 是 | 畸变系数，表示透镜畸变的程度，取值范围为[-1, 1]。畸变系数设置小于-1的值时，按值为-1处理；设置大于1的值时，按值为1处理。| 149 150 151如上图是对图片组件分别设置畸变参数为-1，0，0.5，1的绘制结果。畸变参数小于0时，效果为桶形畸变；大于0时，效果为枕形畸变；越接近0时，畸变程度越小，等于0时，没有畸变效果。 152 153**返回值：** 154 155| 类型 | 说明 | 156| ----------------- | --------------------------------- | 157| [Filter](#filter) | 返回挂载了透镜畸变效果的Filter。 | 158 159**错误码：** 160 161以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 162 163| 错误码ID | 错误信息 | 164| ------- | --------------------------------------------| 165| 202 | Permission verification failed. A non-system application calls a system API. | 166 167**示例：** 168 169```ts 170filter.distort(-0.5) 171``` 172 173## TileMode 174像素填充模式枚举。 175 176**系统能力：** SystemCapability.Graphics.Drawing 177 178**系统接口：** 此接口为系统接口。 179 180| 名称 | 值 | 说明 | 181| ------ | - | ---- | 182| CLAMP | 0 | 截断。 | 183| REPEAT | 1 | 重复。 | 184| MIRROR | 2 | 镜像。 | 185| DECAL | 3 | 透明。 | 186 187## WaterRippleMode 188水波纹场景模式枚举。 189 190**系统能力：** SystemCapability.Graphics.Drawing 191 192**系统接口：** 此接口为系统接口。 193 194| 名称 | 值 | 说明 | 195| ------ | - | ---- | 196| SMALL2MEDIUM_RECV | 0 | 手机碰2in1设备（接收端）。 | 197| SMALL2MEDIUM_SEND | 1 | 手机碰2in1设备（发送端）。 | 198| SMALL2SMALL | 2 | 手机碰手机。 | 199 200## FlyMode 201飞入飞出形变场景模式枚举。 202 203**系统能力：** SystemCapability.Graphics.Drawing 204 205**系统接口：** 此接口为系统接口。 206 207| 名称 | 值 | 说明 | 208| ------ | - | ---- | 209| BOTTOM | 0 | 从底部进行飞入飞出形变。 | 210| TOP | 1 | 从顶部进行飞入飞出形变。 | 211 212## VisualEffect 213VisualEffect效果类，用于将相应的效果添加到指定的组件上。在调用VisualEffect的方法前，需要先通过[createEffect](js-apis-uiEffect.md#uieffectcreateeffect)创建一个VisualEffect实例。 214 215### backgroundColorBlender 216backgroundColorBlender(blender: BrightnessBlender): VisualEffect 217 218将混合器添加至组件上以改变组件背景颜色，具体的更改效果由输入决定，目前仅支持提亮混合器。 219 220**系统能力：** SystemCapability.Graphics.Drawing 221 222**系统接口：** 此接口为系统接口。 223 224**参数：** 225| 参数名 | 类型 | 必填 | 说明 | 226| ------- | ---------------------------------------- | ---- | ------------------------- | 227| blender | [BrightnessBlender](#brightnessblender) | 是 | 用于混合背景颜色的blender。 | 228 229**返回值：** 230 231| 类型 | 说明 | 232| ----------------------------- | ------------------------------------------------- | 233| [VisualEffect](#visualeffect) | 返回添加了背景颜色更改效果的VisualEffect。 | 234 235**示例：** 236 237```ts 238let blender : uiEffect.BrightnessBlender = 239 uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0, 240 positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0}) 241visualEffect.backgroundColorBlender(blender) 242``` 243 244## Blender<sup>13+</sup> 245 246type Blender = BrightnessBlender 247 248混合器类型，用于描述混合效果。 249 250**系统能力：** SystemCapability.Graphics.Drawing 251 252**系统接口：** 此接口为系统接口。 253 254| 类型 | 说明 | 255| ----------------------------- | ------------------------------------------------- | 256| [BrightnessBlender](#brightnessblender) | 具有提亮效果的混合器。 | 257 258## BrightnessBlender 259提亮混合器，用于将提亮效果添加到指定的组件上。在调用BrightnessBlender前，需要先通过[createBrightnessBlender](#uieffectcreatebrightnessblender)创建一个BrightnessBlender实例。 260 261**系统能力：** SystemCapability.Graphics.Drawing 262 263**系统接口：** 此接口为系统接口。 264 265| 名称 | 类型 | 只读 | 可选 | 说明 | 266| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 267| cubicRate | number | 否 | 否 | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。 | 268| quadraticRate | number | 否 | 否 | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。 | 269| linearRate | number | 否 | 否 | 灰度调整的线性系数。<br/>取值范围[-20, 20]。 | 270| degree | number | 否 | 否 | 灰度调整的比例。<br/>取值范围[-20, 20]。 | 271| saturation | number | 否 | 否 | 提亮的基准饱和度。<br/>取值范围[0, 20]。 | 272| positiveCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 | 273| negativeCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 | 274| fraction | number | 否 | 否 | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。 | 275 276## BrightnessBlenderParam 277BrightnessBlender参数列表。 278 279**系统能力：** SystemCapability.Graphics.Drawing 280 281**系统接口：** 此接口为系统接口。 282 283| 名称 | 类型 | 只读 | 可选 | 说明 | 284| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- | 285| cubicRate | number | 否 | 否 | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。 | 286| quadraticRate | number | 否 | 否 | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。 | 287| linearRate | number | 否 | 否 | 灰度调整的线性系数。<br/>取值范围[-20, 20]。 | 288| degree | number | 否 | 否 | 灰度调整的比例。<br/>取值范围[-20, 20]。 | 289| saturation | number | 否 | 否 | 提亮的基准饱和度。<br/>取值范围[0, 20]。 | 290| positiveCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 | 291| negativeCoefficient | [number, number, number] | 否 | 否 | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 | 292| fraction | number | 否 | 否 | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。 |
