1# 图像效果 2 3设置组件的模糊、阴影、球面效果以及设置图片的图像效果。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## blur 10 11blur(value: number, options?: BlurOptions) 12 13为组件添加内容模糊效果。 14 15**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 16 17**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 18 19**系统能力：** SystemCapability.ArkUI.ArkUI.Full 20 21**参数：** 22 23| 参数名 | 类型 | 必填 | 说明 | 24| --------------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 25| value | number | 是 | 当前组件添加内容模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。 | 26| options<sup>11+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 27 28## shadow 29 30shadow(value: ShadowOptions | ShadowStyle) 31 32为组件添加阴影效果。 33 34**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用，ArkTS卡片上不支持参数为 [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10枚举说明)类型。 35 36**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 37 38**系统能力：** SystemCapability.ArkUI.ArkUI.Full 39 40**参数：** 41 42| 参数名 | 类型 | 必填 | 说明 | 43| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 44| value | [ShadowOptions](#shadowoptions对象说明) \| [ShadowStyle](#shadowstyle10枚举说明)<sup>10+</sup> | 是 | 为当前组件添加阴影效果。<br/>入参类型为ShadowOptions时，可以指定模糊半径、阴影的颜色、X轴和Y轴的偏移量。<br/>入参类型为ShadowStyle时，可指定不同阴影样式。 | 45 46## grayscale 47 48grayscale(value: number) 49 50为组件添加灰度效果。 51 52**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 53 54**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 55 56**系统能力：** SystemCapability.ArkUI.ArkUI.Full 57 58**参数：** 59 60| 参数名 | 类型 | 必填 | 说明 | 61| ------ | ------ | ---- | ------------------------------------------------------------ | 62| value | number | 是 | 为当前组件添加灰度效果。值定义为灰度转换的比例，入参1.0则完全转为灰度图像，入参0.0则图像无变化，入参在0.0和1.0之间时，效果呈线性变化。（百分比)<br/>默认值：0.0<br/>取值范围：[0.0, 1.0]<br/>**说明：**<br/>设置小于0.0的值时，按值为0.0处理，设置大于1.0的值时，按值为1.0处理。 | 63 64## brightness 65 66brightness(value: number) 67 68为组件添加高光效果。 69 70**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 71 72**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.ArkUI.ArkUI.Full 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| ------ | ------ | ---- | ------------------------------------------------------------ | 80| value | number | 是 | 为当前组件添加高光效果，入参为高光比例，值为1时没有效果，小于1时亮度变暗，0为全黑，大于1时亮度增加，数值越大亮度越大，亮度为2时会变为全白。<br/>默认值：1.0<br/>推荐取值范围：[0, 2]<br/>**说明：**<br/>设置小于0的值时，按值为0处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 81 82## saturate 83 84saturate(value: number) 85 86为组件添加饱和度效果。 87 88**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 89 90**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 91 92**系统能力：** SystemCapability.ArkUI.ArkUI.Full 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------ | ------ | ---- | ------------------------------------------------------------ | 98| value | number | 是 | 为当前组件添加饱和度效果，饱和度为颜色中的含色成分和消色成分(灰)的比例，入参为1时，显示原图像，大于1时含色成分越大，饱和度越大，小于1时消色成分越大，饱和度越小。（百分比）<br/>默认值：1.0<br/>推荐取值范围：[0, 50)<br/>**说明：**<br/>设置小于0的值时，按值为0处理。 | 99 100## contrast 101 102contrast(value: number) 103 104为组件添加对比度效果。 105 106**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 107 108**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| ------ | ------ | ---- | ------------------------------------------------------------ | 116| value | number | 是 | 为当前组件添加对比度效果，入参为对比度的值。值为1时，显示原图，大于1时，值越大对比度越高，图像越清晰醒目，小于1时，值越小对比度越低，当对比度为0时，图像变为全灰。（百分比）<br/>默认值：1.0<br/>推荐取值范围：[0, 10)<br/>**说明：**<br/>设置小于0的值时，按值为0处理。 | 117 118## invert 119 120invert(value: number | InvertOptions) 121 122反转输入的图像。 123 124**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 125 126**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 127 128**系统能力：** SystemCapability.ArkUI.ArkUI.Full 129 130**参数：** 131 132| 参数名 | 类型 | 必填 | 说明 | 133| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 134| value | number \| [InvertOptions](#invertoptions11对象说明)<sup>11+</sup> | 是 | 反转输入的图像。<br/>入参对象为number时,入参为图像反转的比例，值为1时完全反转，值为0则图像无变化。（百分比）<br/>取值范围：[0, 1]<br/>设置小于0的值时，按值为0处理。<br/>入参对象为 InvertOptions时，对比背景颜色灰度值和阈值区间，背景颜色灰度值小于阈值区间时反色取high值，当背景颜色灰度值大于阈值区间时反色取low值，背景颜色灰度值在阈值区间内取值由high线性渐变到low。 | 135 136## sepia 137 138sepia(value: number) 139 140将图像转换为深褐色。 141 142**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 143 144**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 145 146**系统能力：** SystemCapability.ArkUI.ArkUI.Full 147 148**参数：** 149 150| 参数名 | 类型 | 必填 | 说明 | 151| ------ | ------ | ---- | ------------------------------------------------------------ | 152| value | number | 是 | 将图像转换为深褐色。入参为图像反转的比例，值为1则完全是深褐色的，值为0图像无变化。 （百分比） | 153 154## hueRotate 155 156hueRotate(value: number | string) 157 158色相旋转效果。 159 160**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 161 162**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166**参数：** 167 168| 参数名 | 类型 | 必填 | 说明 | 169| ------ | -------------------------- | ---- | ------------------------------------------------------------ | 170| value | number \| string | 是 | 色相旋转效果，输入参数为旋转角度。<br/>默认值：'0deg'<br/>取值范围：(-∞, +∞)<br/>**说明：**<br/>色调旋转360度会显示原始颜色。先将色调旋转180 度，然后再旋转-180度会显示原始颜色。数据类型为number时，值为90和'90deg'效果一致。 | 171 172## colorBlend<sup>7+</sup> 173 174colorBlend(value: Color | string | Resource) 175 176为组件添加颜色叠加效果。 177 178**系统能力：** SystemCapability.ArkUI.ArkUI.Full 179 180**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 181 182**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------- | 188| value | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | 是 | 为当前组件添加颜色叠加效果，入参为叠加的颜色。 | 189 190## linearGradientBlur<sup>12+</sup> 191 192linearGradientBlur(value: number, options: LinearGradientBlurOptions) 193 194为组件添加内容线性渐变模糊效果。 195 196**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 197 198**系统能力：** SystemCapability.ArkUI.ArkUI.Full 199 200**参数：** 201 202| 参数名 | 类型 | 必填 | 说明 | 203| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 204| value | number | 是 | 为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>取值范围：[0, 1000]<br/>线性梯度模糊包含两个部分fractionStops和direction。 | 205| options | [LinearGradientBlurOptions](#lineargradientbluroptions12对象说明) | 是 | 设置线性渐变模糊效果。 | 206 207## renderGroup<sup>10+</sup> 208 209renderGroup(value: boolean) 210 211设置当前控件和子控件是否先整体离屏渲染绘制后再与父控件融合绘制。 212 213**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 214 215**系统能力：** SystemCapability.ArkUI.ArkUI.Full 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| ------ | ------- | ---- | ------------------------------------------------------------ | 221| value | boolean | 是 | 设置当前控件和子控件是否先整体离屏渲染绘制后再与父控件融合绘制。当前控件的不透明度不为1时绘制效果可能有差异。<br/>默认值：false | 222 223## blendMode<sup>11+</sup> 224 225blendMode(value: BlendMode, type?: BlendApplyType) 226 227将当前控件的内容（包含子节点内容）与下方画布（可能为离屏画布）已有内容进行混合。 228 229**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 230 231**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 232 233**系统能力：** SystemCapability.ArkUI.ArkUI.Full 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| ------ | ------------------------------- | ---- | ------------------------------------------------------------ | 239| value | [BlendMode](#blendmode11枚举说明) | 是 | 混合模式。<br/>默认值：BlendMode.NONE | 240| type | [BlendApplyType](#blendapplytype11枚举说明) | 否 | blendMode实现方式是否离屏。<br/>默认值：BlendApplyType.FAST<br/>**说明：**<br/>1. 设置BlendApplyType.FAST时，不离屏。<br/>2. 设置BlendApplyType.OFFSCREEN时，会创建当前组件大小的离屏画布，再将当前组件（含子组件）的内容绘制到离屏画布上，再用指定的混合模式与下方画布已有内容进行混合。 | 241 242## BlendApplyType<sup>11+</sup>枚举说明 243 244指示如何将指定的混合模式应用于视图的内容。 245 246**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 247 248**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 249 250**系统能力：** SystemCapability.ArkUI.ArkUI.Full 251 252| 名称 | 描述 | 253| ---------------| ---------------------------------------------------------------- | 254| FAST | 在目标图像上按顺序混合视图的内容。 | 255| OFFSCREEN | 将此组件和子组件内容绘制到离屏画布上，然后整体进行混合。 | 256 257## useShadowBatching<sup>11+</sup> 258 259useShadowBatching(value: boolean) 260 261控件内部子节点的阴影进行同层绘制，同层元素阴影重叠。 262 263**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 264 265**系统能力：** SystemCapability.ArkUI.ArkUI.Full 266 267**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| ------ | ------- | ---- | ------------------------------------------------------------ | 273| value | boolean | 是 | 控件内部子节点的阴影进行同层绘制，同层元素阴影重叠。<br/>默认值：false<br/>**说明：**<br/>1. 默认不开启，如果子节点的阴影半径较大，节点各自的阴影会互相重叠。 当开启时，元素的阴影将不会重叠。<br/>2. 不推荐useShadowBatching嵌套使用，如果嵌套使用，只会对当前的子节点生效，无法递推。 | 274 275## sphericalEffect<sup>12+</sup> 276 277sphericalEffect(value: number) 278 279设置组件的图像球面化程度。 280 281**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 282 283**系统能力：** SystemCapability.ArkUI.ArkUI.Full 284 285**参数：** 286 287| 参数名 | 类型 | 必填 | 说明 | 288| ------ | ------ | ---- | ------------------------------------------------------------ | 289| value | number | 是 | 设置组件的图像球面化程度。<br/>取值范围：[0,1]。<br/>**说明：**<br/>1. 如果value等于0则图像保持原样，如果value等于1则图像为完全球面化效果。在0和1之间，数值越大，则球面化程度越高。<br/>`value < 0 `或者` value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。<br/>2. 组件阴影和外描边不支持球面效果。<br>3. 设置value大于0时，组件冻屏不更新并且把组件内容绘制到透明离屏buffer上，如果要更新组件属性则需要把value设置为0。 | 290 291## lightUpEffect<sup>12+</sup> 292 293lightUpEffect(value: number) 294 295设置组件图像亮起程度。 296 297**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 298 299**系统能力：** SystemCapability.ArkUI.ArkUI.Full 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| ------ | ------ | ---- | ------------------------------------------------------------ | 305| value | number | 是 | 设置组件图像亮起程度。<br/>取值范围：[0,1]。<br/>如果value等于0则图像为全黑，如果value等于1则图像为全亮效果。0到1之间数值越大，表示图像亮度越高。`value < 0` 或者 `value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。 | 306 307## pixelStretchEffect<sup>12+</sup> 308 309pixelStretchEffect(options: PixelStretchEffectOptions) 310 311设置组件的图像边缘像素扩展距离。 312 313**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 314 315**系统能力：** SystemCapability.ArkUI.ArkUI.Full 316 317**参数：** 318 319| 参数名 | 类型 | 必填 | 说明 | 320| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 321| options | [PixelStretchEffectOptions](#pixelstretcheffectoptions10) | 是 | 设置组件的图像边缘像素扩展距离。<br/>参数`options`包括上下左右四个方向的边缘像素扩展距离。<br/>**说明：**<br/>1. 如果距离为正值，表示向外扩展，放大原来图像大小。上下左右四个方向分别用边缘像素填充，填充的距离即为设置的边缘扩展的距离。<br/>2. 如果距离为负值，表示内缩，但是最终图像大小不变。<br/>内缩方式：<br/>图像根据`options`的设置缩小，缩小大小为四个方向边缘扩展距离的绝对值。<br/>图像用边缘像素扩展到原来大小。<br/>3. 对`options`的输入约束：<br/>上下左右四个方向的扩展统一为非正值或者非负值。即四个边同时向外扩或者内缩，方向一致。<br/>所有方向的输入均为百分比或者具体值，不支持百分比和具体值混用。<br/>所有异常情况下，显示为{0，0，0，0}效果，即跟原图保持一致。 | 322 323## PixelStretchEffectOptions<sup>10+</sup> 324 325像素扩展属性集合,用于描述像素扩展的信息。 326 327**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 328 329**系统能力：** SystemCapability.ArkUI.ArkUI.Full 330 331| 名称 | 类型 | 必填 | 说明 | 332| ------ | ----------------- | ---- | -------------- | 333| left | [Length](ts-types.md#length) | 否 | 组件图像左边沿像素扩展距离。 | 334| right | [Length](ts-types.md#length) | 否 | 组件图像右边沿像素扩展距离。 | 335| top | [Length](ts-types.md#length) | 否 | 组件图像上边沿像素扩展距离。 | 336| bottom | [Length](ts-types.md#length) | 否 | 组件图像下边沿像素扩展距离。 | 337 338## systemBarEffect<sup>12+</sup> 339 340systemBarEffect() 341 342根据背景进行智能反色并且带有模糊效果。 343 344**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 345 346**系统能力：** SystemCapability.ArkUI.ArkUI.Full 347 348## ShadowType<sup>10+<sup>枚举说明 349 350阴影类型。 351 352**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 353 354**系统能力：** SystemCapability.ArkUI.ArkUI.Full 355 356| 名称 | 描述 | 357| -------- | ---------------------------------------- | 358| COLOR | 颜色。 | 359| BLUR | 模糊。 | 360 361 362## ShadowOptions对象说明 363 364阴影属性集合，用于设置阴影的模糊半径、阴影的颜色、X轴和Y轴的偏移量。 365 366 367**系统能力：** SystemCapability.ArkUI.ArkUI.Full 368 369**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 370 371| 名称 | 类型 | 必填 | 说明 | 372| ------- | ---------------------------------------- | ---- | ---------------------------------------- | 373| radius | number \| [Resource](ts-types.md#resource) | 是 | 阴影模糊半径。<br/>取值范围：[0, +∞)<br/>单位：px<br/>**说明：** <br/>设置小于0的值时，按值为0处理。<br/>如需使用vp单位的数值可用[vp2px](ts-pixel-units.md#像素单位转换)进行转换。<br/>如果radius为Resource类型，则传入的值需为number类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 374| type<sup>10+</sup> | [ShadowType<sup>10+</sup>](#shadowtype10枚举说明) | 否 | 阴影类型。<br/>默认为COLOR。 <br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 375| color | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource)\| [ColoringStrategy<sup>10+</sup> ](ts-appendix-enums.md#coloringstrategy10) | 否 | 阴影的颜色。<br/>默认为黑色。 <br/>**说明：** <br/>从API version 11开始，该接口支持使用ColoringStrategy实现智能取色，智能取色功能不支持在ArkTS卡片、[textShadow](ts-basic-components-text.md#textshadow10)中使用。<br/>当前仅支持平均取色和主色取色，智能取色区域为shadow绘制区域。<br/>支持使用'average'字符串触发智能平均取色模式，支持使用'primary'字符串触发智能主色模式。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 376| offsetX | number \| [Resource](ts-types.md#resource) | 否 | 阴影的X轴偏移量。<br/>默认值：0<br/>单位：px<br/>**说明：** <br/>如需使用vp单位的数值可用[vp2px](ts-pixel-units.md#像素单位转换)进行转换。<br/>如果offsetX为Resource类型，则传入的值需为number类型。<br/> **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 377| offsetY | number \| [Resource](ts-types.md#resource) | 否 | 阴影的Y轴偏移量。<br/>默认值：0<br/>单位：px<br/>**说明：** <br/>如需使用vp单位的数值可用[vp2px](ts-pixel-units.md#像素单位转换)进行转换。<br/>如果offsetY为Resource类型，则传入的值需为number类型。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 378| fill<sup>11+</sup> | boolean | 否 | 阴影是否内部填充。<br/>默认为false。<br/>**说明：**<br/>[textShadow](ts-basic-components-text.md#textshadow10)中该字段不生效。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 379 380## ShadowStyle<sup>10+</sup>枚举说明 381 382**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 383 384| 名称 | 描述 | 385| ----------------- | ------ | 386| OUTER_DEFAULT_XS | 超小阴影。 | 387| OUTER_DEFAULT_SM | 小阴影。 | 388| OUTER_DEFAULT_MD | 中阴影。 | 389| OUTER_DEFAULT_LG | 大阴影。 | 390| OUTER_FLOATING_SM | 浮动小阴影。 | 391| OUTER_FLOATING_MD | 浮动中阴影。 | 392 393## BlendMode<sup>11+</sup>枚举说明 394 395> **说明：** 396> 397> blendMode枚举中，s表示源像素，d表示目标像素，sa表示原像素透明度，da表示目标像素透明度，r表示混合后像素，ra表示混合后像素透明度。 398 399**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 400 401**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 402 403| 名称 | 描述 | 404| ---------------| ------ | 405| NONE | 将上层图像直接覆盖到下层图像上，不进行任何混合操作。 | 406| CLEAR | 将源像素覆盖的目标像素清除为完全透明。 | 407| SRC | r = s，只显示源像素。 | 408| DST | r = d，只显示目标像素。 | 409| SRC_OVER | r = s + (1 - sa) * d，将源像素按照透明度进行混合，覆盖在目标像素上。 | 410| DST_OVER | r = d + (1 - da) * s，将目标像素按照透明度进行混合，覆盖在源像素上。 | 411| SRC_IN | r = s * da，只显示源像素中与目标像素重叠的部分。 | 412| DST_IN | r = d * sa，只显示目标像素中与源像素重叠的部分。 | 413| SRC_OUT | r = s * (1 - da)，只显示源像素中与目标像素不重叠的部分。 | 414| DST_OUT | r = d * (1 - sa)，只显示目标像素中与源像素不重叠的部分。 | 415| SRC_ATOP | r = s * da + d * (1 - sa)，在源像素和目标像素重叠的地方绘制源像素，在源像素和目标像素不重叠的地方绘制目标像素。 | 416| DST_ATOP | r = d * sa + s * (1 - da)，在源像素和目标像素重叠的地方绘制目标像素，在源像素和目标像素不重叠的地方绘制源像素。 | 417| XOR | r = s * (1 - da) + d * (1 - sa)，只显示源像素与目标像素不重叠的部分。 | 418| PLUS | r = min(s + d, 1)，将源像素值与目标像素值相加，并将结果作为新的像素值。 | 419| MODULATE | r = s * d，将源像素与目标像素进行乘法运算，并将结果作为新的像素值。 | 420| SCREEN | r = s + d - s * d，将两个图像的像素值相加，然后减去它们的乘积来实现混合。 | 421| OVERLAY | 根据目标像素来决定使用MULTIPLY混合模式还是SCREEN混合模式。 | 422| DARKEN | rc = s + d - max(s * da, d * sa), ra = kSrcOver，当两个颜色重叠时，较暗的颜色会覆盖较亮的颜色。 | 423| LIGHTEN | rc = s + d - min(s * da, d * sa), ra = kSrcOver，将源图像和目标图像中的像素进行比较，选取两者中较亮的像素作为最终的混合结果。 | 424| COLOR_DODGE | 使目标像素变得更亮来反映源像素。 | 425| COLOR_BURN | 使目标像素变得更暗来反映源像素。 | 426| HARD_LIGHT | 根据源像素的值来决定目标像素变得更亮或者更暗。根据源像素来决定使用MULTIPLY混合模式还是SCREEN混合模式。 | 427| SOFT_LIGHT | 根据源像素来决定使用LIGHTEN混合模式还是DARKEN混合模式。 | 428| DIFFERENCE | rc = s + d - 2 * (min(s * da, d * sa)), ra = kSrcOver，对比源像素和目标像素，亮度更高的像素减去亮度更低的像素，产生高对比度的效果。 | 429| EXCLUSION | rc = s + d - two(s * d), ra = kSrcOver，对比源像素和目标像素，亮度更高的像素减去亮度更低的像素，产生柔和的效果。 | 430| MULTIPLY | r = s * (1 - da) + d * (1 - sa) + s * d，将源图像与目标图像进行乘法混合，得到一张新的图像。 | 431| HUE | 保留源图像的亮度和饱和度，但会使用目标图像的色调来替换源图像的色调。 | 432| SATURATION | 保留目标像素的亮度和色调，但会使用源像素的饱和度来替换目标像素的饱和度。 | 433| COLOR | 保留源像素的饱和度和色调，但会使用目标像素的亮度来替换源像素的亮度。 | 434| LUMINOSITY | 保留目标像素的色调和饱和度，但会用源像素的亮度替换目标像素的亮度。 | 435 436## LinearGradientBlurOptions<sup>12+</sup>对象说明 437 438**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 439 440| 名称 | 类型 | 必填 | 说明 | 441| ------------- | ----------------------------------------------------------- | ----- | ------------------------------------------------------------ | 442| fractionStops | Array\<[FractionStop](#fractionstop12)> | 是 | 数组中保存的每一个二元数组（取值0-1，小于0则为0，大于1则为1）表示[模糊程度, 模糊位置]；模糊位置需严格递增，开发者传入的数据不符合规范会记录日志，渐变模糊数组中二元数组个数必须大于等于2，否则渐变模糊不生效。 | 443| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | 是 | 渐变模糊方向。<br/>默认值：<br/>GradientDirection.Bottom | 444 445## FractionStop<sup>12+</sup> 446 447FractionStop = [ number, number ] 448 449定义模糊段。 450 451**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 452 453**系统能力：** SystemCapability.ArkUI.ArkUI.Full 454 455| 取值范围 | 说明 | 456| ------------- | ---------------------------------------------------------- | 457| number | 分数,值1表示不透明，0表示完全透明。<br/>取值范围：[0,1] | 458| number | 停止位置,值1表示区域结束位置，0表示区域开始位置。<br/> 取值范围:[0,1] | 459 460## InvertOptions<sup>11+</sup>对象说明 461 462前景智能取反色。 463 464**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 465 466| 名称 | 类型 | 必填 | 说明 | 467| -------------- | ------ | ----- | ------------------------------------------ | 468| low | number | 是 | 背景颜色灰度值大于阈值区间时的取值。 | 469| high | number | 是 | 背景颜色灰度值小于阈值区间时的取值。 | 470| threshold | number | 是 | 灰度阈值。 | 471| thresholdRange | number | 是 | 阈值范围。<br/>**说明：**<br/>灰度阈值上下偏移thresholdRange构成阈值区间，背景颜色灰度值在区间内取值由high线性渐变到low。| 472 473## freeze<sup>12+</sup> 474 475freeze(value: boolean) 476 477设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。 478 479**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 480 481**系统能力：** SystemCapability.ArkUI.ArkUI.Full 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| ------ | ------- | ---- | ------------------------------------------------------------ | 487| value | boolean | 是 | 设置当前控件和子控件是否整体离屏渲染绘制后重复绘制缓存，不再进行内部属性更新。当前控件的不透明度不为1时绘制效果可能有差异。<br/>默认值：false | 488 489## 示例 490 491### 示例1（设置图片不同属性效果） 492设置图片的效果，包括阴影，灰度，高光，饱和度，对比度，图像反转，叠色，色相旋转等。 493```ts 494// xxx.ets 495@Entry 496@Component 497struct ImageEffectsExample { 498 build() { 499 Column({ space: 5 }) { 500 // 添加阴影效果，图片效果不变 501 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 502 Image($r('app.media.image')) 503 .width('90%') 504 .height(30) 505 .shadow({ 506 radius: 10, 507 color: Color.Green, 508 offsetX: 20, 509 offsetY: 20 510 }) 511 512 // 添加内部阴影效果 513 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 514 Image($r('app.media.image')) 515 .width('90%') 516 .height(30) 517 .shadow({ 518 radius: 5, 519 color: Color.Green, 520 offsetX: 20, 521 offsetY: 20, 522 fill: true 523 }).opacity(0.5) 524 525 // 灰度效果0~1，越接近1，灰度越明显 526 Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%') 527 Image($r('app.media.image')).width('90%').height(30).grayscale(0.3) 528 Image($r('app.media.image')).width('90%').height(30).grayscale(0.8) 529 530 // 高光效果，1为正常图片，<1变暗，>1亮度增大 531 Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%') 532 Image($r('app.media.image')).width('90%').height(30).brightness(1.2) 533 534 // 饱和度，原图为1 535 Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%') 536 Image($r('app.media.image')).width('90%').height(30).saturate(2.0) 537 Image($r('app.media.image')).width('90%').height(30).saturate(0.7) 538 539 // 对比度，1为原图，>1值越大越清晰，<1值越小越模糊 540 Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%') 541 Image($r('app.media.image')).width('90%').height(30).contrast(2.0) 542 Image($r('app.media.image')).width('90%').height(30).contrast(0.8) 543 544 // 图像反转比例 545 Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%') 546 Image($r('app.media.image')).width('90%').height(30).invert(0.2) 547 Image($r('app.media.image')).width('90%').height(30).invert(0.8) 548 549 // 叠色添加 550 Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%') 551 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Green) 552 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Blue) 553 554 // 深褐色 555 Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%') 556 Image($r('app.media.image')).width('90%').height(30).sepia(0.8) 557 558 // 色相旋转 559 Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%') 560 Image($r('app.media.image')).width('90%').height(30).hueRotate(90) 561 }.width('100%').margin({ top: 5 }) 562 } 563} 564``` 565 566 567 568 569### 示例2（设置组件线性渐变模糊效果） 570 571该示例主要演示通过linearGradientBlur设置组件的内容线性渐变模糊效果。 572 573```ts 574// xxx.ets 575@Entry 576@Component 577struct ImageExample1 { 578 private_resource1: Resource = $r('app.media.testlinearGradientBlurOrigin') 579 @State image_src: Resource = this.private_resource1 580 581 build() { 582 Column() { 583 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 584 Row({ space: 5 }) { 585 Image(this.image_src) 586 .linearGradientBlur(60, 587 { fractionStops: [[0, 0], [0, 0.33], [1, 0.66], [1, 1]], direction: GradientDirection.Bottom }) 588 } 589 } 590 } 591 } 592} 593``` 594 595 596 597### 示例3（设置离屏渲染效果） 598 599该示例主要演示通过renderGroup来设置组件是否先整体离屏渲染绘制后，再与父控件融合绘制。 600 601```ts 602// xxx.ets 603@Component 604struct Component1 { 605 @Prop renderGroupValue: boolean; 606 607 build() { 608 Row() { 609 Row() { 610 Row() 611 .backgroundColor(Color.Black) 612 .width(100) 613 .height(100) 614 .opacity(1) 615 } 616 .backgroundColor(Color.White) 617 .width(150) 618 .height(150) 619 .justifyContent(FlexAlign.Center) 620 .opacity(0.6) 621 .renderGroup(this.renderGroupValue) 622 } 623 .backgroundColor(Color.Black) 624 .width(200) 625 .height(200) 626 .justifyContent(FlexAlign.Center) 627 .opacity(1) 628 } 629} 630 631@Entry 632@Component 633struct RenderGroupExample { 634 build() { 635 Column() { 636 Component1({ renderGroupValue: true }) 637 .margin(20) 638 Component1({ renderGroupValue: false }) 639 .margin(20) 640 } 641 .width("100%") 642 .height("100%") 643 .alignItems(HorizontalAlign.Center) 644 } 645} 646``` 647 648 649 650### 示例4（当前组件内容与下方画布内容混合） 651 652该示例主要演示通过blendMode将当前组件内容与下方画布内容混合。 653 654```ts 655// xxx.ets 656@Entry 657@Component 658struct Index { 659 build() { 660 Column() { 661 Text("blendMode") 662 .fontSize(20) 663 .fontWeight(FontWeight.Bold) 664 .fontColor('#ffff0101') 665 Row() { 666 Circle() 667 .width(200) 668 .height(200) 669 .fill(Color.Green) 670 .position({ x: 50, y: 50 }) 671 Circle() 672 .width(200) 673 .height(200) 674 .fill(Color.Blue) 675 .position({ x: 150, y: 50 }) 676 } 677 .blendMode(BlendMode.OVERLAY, BlendApplyType.OFFSCREEN) 678 .alignItems(VerticalAlign.Center) 679 .height(300) 680 .width('100%') 681 } 682 .height('100%') 683 .width('100%') 684 .backgroundImage($r('app.media.image')) 685 .backgroundImageSize(ImageSize.Cover) 686 } 687} 688``` 689 690<br/>BlendMode.OVERLAY,BlendApplyType.OFFSCREEN<br/> 691 692<br/>不同的混合模式搭配是否需要离屏从而产生不同的效果。 693 694### 示例5（前景智能取反色） 695 696该示例主要通过InvertOptions来实现前景智能取反色。 697 698```ts 699// xxx.ets 700@Entry 701@Component 702struct Index { 703 build() { 704 Stack() { 705 Column() 706 Stack() { 707 Image($r('app.media.r')).width('100%') 708 Column() { 709 Column().width("100%").height(30).invert({ 710 low: 0, 711 high: 1, 712 threshold: 0.5, 713 thresholdRange: 0.2 714 }) 715 Column().width("100%").height(30).invert({ 716 low: 0.2, 717 high: 0.5, 718 threshold: 0.3, 719 thresholdRange: 0.2 720 }) 721 } 722 } 723 .width('100%') 724 .height('100%') 725 } 726 } 727} 728``` 729 730 731 732### 示例6（设置同层阴影不重叠效果） 733 734该示例主要通过useShadowBatching搭配shadow实现同层阴影不重叠效果。 735 736```ts 737// xxx.ets 738@Entry 739@Component 740struct UseShadowBatchingExample { 741 build() { 742 Column() { 743 Column({ space: 10 }) { 744 Stack() { 745 746 } 747 .width('90%') 748 .height(50) 749 .margin({ top: 5 }) 750 .backgroundColor(0xFFE4C4) 751 .shadow({ 752 radius: 120, 753 color: Color.Green, 754 offsetX: 0, 755 offsetY: 0 756 }) 757 .align(Alignment.TopStart) 758 .shadow({ 759 radius: 120, 760 color: Color.Green, 761 offsetX: 0, 762 offsetY: 0 763 }) 764 765 Stack() { 766 767 } 768 .width('90%') 769 .height(50) 770 .margin({ top: 5 }) 771 .backgroundColor(0xFFE4C4) 772 .align(Alignment.TopStart) 773 .shadow({ 774 radius: 120, 775 color: Color.Red, 776 offsetX: 0, 777 offsetY: 0 778 }) 779 .width('90%') 780 .backgroundColor(Color.White) 781 782 Column() { 783 Text() 784 .fontWeight(FontWeight.Bold) 785 .fontSize(20) 786 .fontColor(Color.White) 787 } 788 .justifyContent(FlexAlign.Center) 789 .width(150) 790 .height(150) 791 .borderRadius(10) 792 .backgroundColor(0xf56c6c) 793 .shadow({ 794 radius: 300, 795 color: Color.Yellow, 796 offsetX: 0, 797 offsetY: 0 798 }) 799 800 Column() { 801 Text() 802 .fontWeight(FontWeight.Bold) 803 .fontSize(20) 804 .fontColor(Color.White) 805 } 806 .justifyContent(FlexAlign.Center) 807 .width(150) 808 .height(150) 809 .backgroundColor(0x67C23A) 810 .borderRadius(10) 811 .translate({ y: -50 }) 812 .shadow({ 813 radius: 220, 814 color: Color.Blue, 815 offsetX: 0, 816 offsetY: 0 817 }) 818 } 819 .useShadowBatching(true) 820 } 821 .width('100%').margin({ top: 5 }) 822 } 823} 824``` 825 826 827 828### 示例7（设置组件图像球面效果） 829 830该示例主要演示通过sphericalEffect设置组件的图像球面效果。 831 832```ts 833// xxx.ets 834@Entry 835@Component 836struct SphericalEffectExample { 837 build() { 838 Stack() { 839 TextInput({ placeholder: "请输入变化范围百分比（[0%,100%]）" }) 840 .width('50%') 841 .height(35) 842 .type(InputType.Number) 843 .enterKeyType(EnterKeyType.Done) 844 .caretColor(Color.Red) 845 .placeholderColor(Color.Blue) 846 .placeholderFont({ 847 size: 20, 848 style: FontStyle.Italic, 849 weight: FontWeight.Bold 850 }) 851 .sphericalEffect(0.5) 852 }.alignContent(Alignment.Center).width("100%").height("100%") 853 } 854} 855``` 856 857效果图如下： 858 859 860 861去掉sphericalEffect的设置，效果如下： 862 863 864 865### 示例8（设置组件图像渐亮效果） 866 867该示例主要演示通过lightUpEffect设置组件的图像渐亮效果。 868 869```ts 870// xxx.ets 871@Entry 872@Component 873struct LightUpExample { 874 build() { 875 Stack() { 876 Text('This is the text content with letterSpacing 0.') 877 .letterSpacing(0) 878 .fontSize(12) 879 .border({ width: 1 }) 880 .padding(10) 881 .width('50%') 882 .lightUpEffect(0.6) 883 }.alignContent(Alignment.Center).width("100%").height("100%") 884 } 885} 886 887``` 888 889效果图如下： 890 891 892 893修改lightUpEffect参数值为0.2： 894 895 896 897去掉lightUpEffect的设置，效果如下： 898 899 900 901### 示例9（设置组件图像边缘像素扩展效果） 902 903该示例主要演示通过pixelStretchEffect设置组件的图像边缘像素扩展效果。 904 905```ts 906// xxx.ets 907@Entry 908@Component 909struct PixelStretchExample { 910 build() { 911 Stack() { 912 Text('This is the text content with letterSpacing 0.') 913 .letterSpacing(0) 914 .fontSize(12) 915 .border({ width: 1 }) 916 .padding(10) 917 .clip(false) 918 .width('50%') 919 .pixelStretchEffect({ 920 top: 10, 921 left: 10, 922 right: 10, 923 bottom: 10 924 }) 925 }.alignContent(Alignment.Center).width("100%").height("100%") 926 } 927} 928``` 929 930效果图如下： 931 932 933 934去掉pixelStretchEffect的设置，原图效果如下： 935 936 937 938 939### 示例10（系统导航条智能反色） 940 941该示例主要演示通过systemBarEffect来实现系统导航条智能反色。 942 943```ts 944// xxx.ets 945@Entry 946@Component 947struct Index { 948 build() { 949 Column() { 950 Stack() { 951 Image($r('app.media.testImage')).width('100%').height('100%') 952 Column() 953 .width(150) 954 .height(10) 955 .systemBarEffect() 956 .border({ radius: 5 }) 957 .margin({ bottom: 80 }) 958 }.alignContent(Alignment.Center) 959 } 960 } 961} 962``` 963 964效果图如下： 965 966
