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## TileMode
137像素填充模式枚举。
138
139**系统能力：** SystemCapability.Graphics.Drawing
140
141**系统接口：** 此接口为系统接口。
142
143| 名称   | 值 | 说明 |
144| ------ | - | ---- |
145| CLAMP  | 0 | 截断。 |
146| REPEAT | 1 | 重复。 |
147| MIRROR | 2 | 镜像。 |
148| DECAL  | 3 | 透明。 |
149
150## WaterRippleMode
151水波纹场景模式枚举。
152
153**系统能力：** SystemCapability.Graphics.Drawing
154
155**系统接口：** 此接口为系统接口。
156
157| 名称   | 值 | 说明 |
158| ------ | - | ---- |
159| SMALL2MEDIUM_RECV  | 0 | 手机碰2in1设备（接收端）。 |
160| SMALL2MEDIUM_SEND  | 1 | 手机碰2in1设备（发送端）。 |
161| SMALL2SMALL | 2 | 手机碰手机。 |
162
163## FlyMode
164飞入飞出形变场景模式枚举。
165
166**系统能力：** SystemCapability.Graphics.Drawing
167
168**系统接口：** 此接口为系统接口。
169
170| 名称   | 值 | 说明 |
171| ------ | - | ---- |
172| BOTTOM  | 0 | 从底部进行飞入飞出形变。 |
173| TOP  | 1 | 从顶部进行飞入飞出形变。 |
174
175## VisualEffect
176VisualEffect效果类，用于将相应的效果添加到指定的组件上。在调用VisualEffect的方法前，需要先通过[createEffect](js-apis-uiEffect.md#uieffectcreateeffect)创建一个VisualEffect实例。
177
178### backgroundColorBlender
179backgroundColorBlender(blender: BrightnessBlender): VisualEffect
180
181将混合器添加至组件上以改变组件背景颜色，具体的更改效果由输入决定，目前仅支持提亮混合器。
182
183**系统能力：** SystemCapability.Graphics.Drawing
184
185**系统接口：** 此接口为系统接口。
186
187**参数：**
188| 参数名  | 类型                                      | 必填 | 说明                       |
189| ------- | ---------------------------------------- | ---- | ------------------------- |
190| blender | [BrightnessBlender](#brightnessblender) | 是   | 用于混合背景颜色的blender。 |
191
192**返回值：**
193
194| 类型                          | 说明                                               |
195| ----------------------------- | ------------------------------------------------- |
196| [VisualEffect](#visualeffect) | 返回添加了背景颜色更改效果的VisualEffect。 |
197
198**示例：**
199
200```ts
201let blender : uiEffect.BrightnessBlender =
202  uiEffect.createBrightnessBlender({cubicRate:1.0, quadraticRate:1.0, linearRate:1.0, degree:1.0, saturation:1.0,
203    positiveCoefficient:[2.3, 4.5, 2.0], negativeCoefficient:[0.5, 2.0, 0.5], fraction:0.0})
204visualEffect.backgroundColorBlender(blender)
205```
206
207## Blender<sup>13+</sup>
208
209type Blender = BrightnessBlender
210
211混合器类型，用于描述混合效果。
212
213**系统能力：** SystemCapability.Graphics.Drawing
214
215**系统接口：** 此接口为系统接口。
216
217| 类型                          | 说明                                               |
218| ----------------------------- | ------------------------------------------------- |
219| [BrightnessBlender](#brightnessblender) | 具有提亮效果的混合器。 |
220
221## BrightnessBlender
222提亮混合器，用于将提亮效果添加到指定的组件上。在调用BrightnessBlender前，需要先通过[createBrightnessBlender](#uieffectcreatebrightnessblender)创建一个BrightnessBlender实例。
223
224**系统能力：** SystemCapability.Graphics.Drawing
225
226**系统接口：** 此接口为系统接口。
227
228| 名称                | 类型                        | 只读 | 可选 | 说明                                                              |
229| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- |
230| cubicRate           | number                     | 否   | 否   | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。                        |
231| quadraticRate       | number                     | 否   | 否   | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。                        |
232| linearRate          | number                     | 否   | 否   | 灰度调整的线性系数。<br/>取值范围[-20, 20]。                        |
233| degree              | number                     | 否   | 否   | 灰度调整的比例。<br/>取值范围[-20, 20]。                            |
234| saturation          | number                     | 否   | 否   | 提亮的基准饱和度。<br/>取值范围[0, 20]。                            |
235| positiveCoefficient | [number, number, number]   | 否   | 否   | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 |
236| negativeCoefficient | [number, number, number]   | 否   | 否   | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 |
237| fraction            | number                     | 否   | 否   | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。  |
238
239## BrightnessBlenderParam
240BrightnessBlender参数列表。
241
242**系统能力：** SystemCapability.Graphics.Drawing
243
244**系统接口：** 此接口为系统接口。
245
246| 名称                | 类型                        | 只读 | 可选 | 说明                                                              |
247| ------------------- | -------------------------- | ---- | ---- | ---------------------------------------------------------------- |
248| cubicRate           | number                     | 否   | 否   | 灰度调整的三阶系数。<br/>取值范围[-20, 20]。                        |
249| quadraticRate       | number                     | 否   | 否   | 灰度调整的二阶系数。<br/>取值范围[-20, 20]。                        |
250| linearRate          | number                     | 否   | 否   | 灰度调整的线性系数。<br/>取值范围[-20, 20]。                        |
251| degree              | number                     | 否   | 否   | 灰度调整的比例。<br/>取值范围[-20, 20]。                            |
252| saturation          | number                     | 否   | 否   | 提亮的基准饱和度。<br/>取值范围[0, 20]。                            |
253| positiveCoefficient | [number, number, number]   | 否   | 否   | 基于基准饱和度的RGB正向调整参数。<br/>每个number的取值范围[-20, 20]。 |
254| negativeCoefficient | [number, number, number]   | 否   | 否   | 基于基准饱和度的RGB负向调整参数。<br/>每个number的取值范围[-20, 20]。 |
255| fraction            | number                     | 否   | 否   | 提亮效果的混合比例。<br/>取值范围[0, 1]，超出边界会在实现时自动截断。  |