1# Image Effects 2 3Image effects include blur, shadow, spherical effect, and much more. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9## blur 10 11blur(value: number, options?: BlurOptions) 12 13Applies a foreground blur effect to the component. 14 15**Widget capability**: This API can be used in ArkTS widgets since API version 9. 16 17**Atomic service API**: This API can be used in atomic services since API version 11. 18 19**System capability**: SystemCapability.ArkUI.ArkUI.Full 20 21**Parameters** 22 23| Name | Type | Mandatory| Description | 24| --------------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 25| value | number | Yes | Foreground blur effect to apply to the component. The input parameter is the blur radius. The larger the radius is, the more blurred the content is. If the value is **0**, the content is not blurred.| 26| options<sup>11+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | No | Grayscale parameters. | 27 28## shadow 29 30shadow(value: ShadowOptions | ShadowStyle) 31 32Applies a shadow effect to the component. 33 34**Widget capability**: Since API version 9, this API is supported in ArkTS widgets. Yet, the [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) type is not supported in ArkTS widgets. 35 36**Atomic service API**: This API can be used in atomic services since API version 11. 37 38**System capability**: SystemCapability.ArkUI.ArkUI.Full 39 40**Parameters** 41 42| Name| Type | Mandatory| Description | 43| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 44| value | [ShadowOptions](#shadowoptions) \| [ShadowStyle](#shadowstyle10)<sup>10+</sup> | Yes | Shadow of the component.<br>When the value type is **ShadowOptions**, the blur radius, shadow color, and offset along the x-axis and y-axis can be specified.<br>When the value type is **ShadowStyle**, the shadow style can be specified.| 45 46## grayscale 47 48grayscale(value: number) 49 50Applies a grayscale effect to the component. 51 52**Widget capability**: This API can be used in ArkTS widgets since API version 9. 53 54**Atomic service API**: This API can be used in atomic services since API version 11. 55 56**System capability**: SystemCapability.ArkUI.ArkUI.Full 57 58**Parameters** 59 60| Name| Type | Mandatory| Description | 61| ------ | ------ | ---- | ------------------------------------------------------------ | 62| value | number | Yes | Grayscale conversion ratio of the component. If the value is **1.0**, the component is completely converted to grayscale. If the value is **0.0**, the component remains unchanged. Between **0** and **1**, the value applies a linear multiplier on the grayscale effect. The unit is percentage.<br>Default value: **0.0**<br>Value range: [0.0, 1.0]<br>**NOTE**<br>A value less than **0.0** evaluates to the value **0.0**. A value greater than **1.0** evaluates to the value **1.0**.| 63 64## brightness 65 66brightness(value: number) 67 68Applies a brightness effect to the component. 69 70**Widget capability**: This API can be used in ArkTS widgets since API version 9. 71 72**Atomic service API**: This API can be used in atomic services since API version 11. 73 74**System capability**: SystemCapability.ArkUI.ArkUI.Full 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | ------ | ---- | ------------------------------------------------------------ | 80| value | number | Yes | Brightness of the component. The value **1** indicates no effects. The value **0** indicates the complete darkness. If the value is less than **1**, the brightness decreases. If the value is greater than **1**, the brightness increases. A larger value indicates a higher brightness. A brightness of 2 turns the component completely white.<br>Default value: **1.0**<br>Recommended value range: [0, 2]<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 81 82## saturate 83 84saturate(value: number) 85 86Applies a saturation effect to the component. 87 88**Widget capability**: This API can be used in ArkTS widgets since API version 9. 89 90**Atomic service API**: This API can be used in atomic services since API version 11. 91 92**System capability**: SystemCapability.ArkUI.ArkUI.Full 93 94**Parameters** 95 96| Name| Type | Mandatory| Description | 97| ------ | ------ | ---- | ------------------------------------------------------------ | 98| value | number | Yes | Saturation of the component. The saturation is the ratio of the chromatic component to the achromatic component (gray) in a color. If the value is **1**, the original image is displayed. If the value is greater than **1**, a higher percentage of the chromatic component indicates a higher saturation. If the value is less than **1**, a higher percentage of the achromatic component indicates a lower saturation. The unit is percentage.<br>Default value: **1.0**<br>Recommended value range: [0, 50)<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.| 99 100## contrast 101 102contrast(value: number) 103 104Applies a contrast effect to the component. 105 106**Widget capability**: This API can be used in ArkTS widgets since API version 9. 107 108**Atomic service API**: This API can be used in atomic services since API version 11. 109 110**System capability**: SystemCapability.ArkUI.ArkUI.Full 111 112**Parameters** 113 114| Name| Type | Mandatory| Description | 115| ------ | ------ | ---- | ------------------------------------------------------------ | 116| value | number | Yes | Contrast of the component. The input parameter is a contrast value. If the value is **1**, the source image is displayed. If the value is greater than 1, a larger value indicates a higher contrast and a clearer image. If the value is less than 1, a smaller value indicates a lower contrast is. If the value is **0**, the image becomes all gray. The unit is percentage.<br>Default value: **1.0**<br>Recommended value range: [0, 10)<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.| 117 118## invert 119 120invert(value: number | InvertOptions) 121 122Inverts the image. 123 124**Widget capability**: This API can be used in ArkTS widgets since API version 9. 125 126**Atomic service API**: This API can be used in atomic services since API version 11. 127 128**System capability**: SystemCapability.ArkUI.ArkUI.Full 129 130**Parameters** 131 132| Name| Type | Mandatory| Description | 133| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 134| value | number \| [InvertOptions](#invertoptions11)<sup>11+</sup> | Yes | How the image is inverted.<br>If the value is of the number type, it indicates the inversion ratio. If the value is **1**, the image is completely inverted. If the value is **0**, the image remains unchanged. The unit is percentage.<br>Value range: [0, 1]<br>A value less than 0 evaluates to the value **0**.<br>If the value is of the InvertOptions type, the grayscale value of the background color is compared with the threshold range. If the grayscale value is greater than the upper bound of the threshold range, the **high** value is used. If the grayscale value is less than the lower bound of the threshold range, the **low** value is used. If the grayscale value is within the threshold range, the background color changes linearly from high to low.| 135 136## sepia 137 138sepia(value: number) 139 140Sepia conversion ratio of the component. 141 142**Widget capability**: This API can be used in ArkTS widgets since API version 9. 143 144**Atomic service API**: This API can be used in atomic services since API version 11. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148**Parameters** 149 150| Name| Type | Mandatory| Description | 151| ------ | ------ | ---- | ------------------------------------------------------------ | 152| value | number | Yes | Sepia conversion ratio of the component. If the value is **1**, the image is completely sepia. If the value is **0**, the component remains unchanged. The unit is percentage.| 153 154## hueRotate 155 156hueRotate(value: number | string) 157 158Rotates the hue of the component. 159 160**Widget capability**: This API can be used in ArkTS widgets since API version 9. 161 162**Atomic service API**: This API can be used in atomic services since API version 11. 163 164**System capability**: SystemCapability.ArkUI.ArkUI.Full 165 166**Parameters** 167 168| Name| Type | Mandatory| Description | 169| ------ | -------------------------- | ---- | ------------------------------------------------------------ | 170| value | number \| string | Yes | Hue rotation angle of the component.<br>Default value: **'0deg'**<br>Value range: (-∞, +∞)<br>**NOTE**<br>A rotation of 360 degrees leaves the color unchanged. A rotation of 180 degrees and then -180 degrees also leaves the color unchanged. When the data type is number, the value **90** is equivalent to **'90deg'**.| 171 172## colorBlend<sup>7+</sup> 173 174colorBlend(value: Color | string | Resource) 175 176Applies a color blend effect to the component. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Atomic service API**: This API can be used in atomic services since API version 11. 181 182**Widget capability**: This API can be used in ArkTS widgets since API version 9. 183 184**Parameters** 185 186| Name| Type | Mandatory| Description | 187| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------- | 188| value | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | Yes | Color to blend with the component.| 189 190## linearGradientBlur<sup>12+</sup> 191 192linearGradientBlur(value: number, options: LinearGradientBlurOptions) 193 194Applies a linear gradient foreground blur effect to the component. 195 196**Atomic service API**: This API can be used in atomic services since API version 12. 197 198**System capability**: SystemCapability.ArkUI.ArkUI.Full 199 200**Parameters** 201 202| Name | Type | Mandatory| Description | 203| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 204| value | number | Yes | Blur radius. A larger value indicates a higher blur degree. If the value is 0, the content is not blurred.<br>Value range: [0, 60]<br>Linear gradient blur consists of two parts: **fractionStops** and **direction**.| 205| options | [LinearGradientBlurOptions](#lineargradientbluroptions12) | Yes | Linear gradient blur effect. | 206 207## renderGroup<sup>10+</sup> 208 209renderGroup(value: boolean) 210 211Sets whether the component and its child components are rendered off the screen and then drawn together with its parent. 212 213**Atomic service API**: This API can be used in atomic services since API version 11. 214 215**System capability**: SystemCapability.ArkUI.ArkUI.Full 216 217**Parameters** 218 219| Name| Type | Mandatory| Description | 220| ------ | ------- | ---- | ------------------------------------------------------------ | 221| value | boolean | Yes | Whether the component and its child components are rendered off the screen and then drawn together with its parent. If the opacity of the component is not 1, the drawing effect may vary depending on the value.<br>Default value: **false**| 222 223## blendMode<sup>11+</sup> 224 225blendMode(value: BlendMode, type?: BlendApplyType) 226 227Defines how the component's content (including the content of it child components) is blended with the existing content on the canvas (possibly offscreen canvas) below. 228 229**Widget capability**: This API can be used in ArkTS widgets since API version 11. 230 231**Atomic service API**: This API can be used in atomic services since API version 12. 232 233**System capability**: SystemCapability.ArkUI.ArkUI.Full 234 235**Parameters** 236 237| Name| Type | Mandatory| Description | 238| ------ | ------------------------------- | ---- | ------------------------------------------------------------ | 239| value | [BlendMode](#blendmode11) | Yes | Blend mode.<br>Default value: **BlendMode.NONE** | 240| type | [BlendApplyType](#blendapplytype11) | No | Whether the blend mode is implemented offscreen.<br>Default value: **BlendApplyType.FAST**<br>**NOTE**<br>1. Available options:<br>**BlendApplyType.FAST**: The blend mode is not implemented offscreen.<br>2. When **BlendApplyType.OFFSCREEN** is set, an offscreen canvas the size of the current component is created. The content of the current component (including child components) is then drawn onto the offscreen canvas, and blended with the existing content on the canvas below using the specified blend mode. | 241 242## BlendApplyType<sup>11+</sup> 243 244Defines how to apply the specified blend mode to the content of a view. 245 246**Widget capability**: This API can be used in ArkTS widgets since API version 11. 247 248**Atomic service API**: This API can be used in atomic services since API version 12. 249 250**System capability**: SystemCapability.ArkUI.ArkUI.Full 251 252| Name | Description | 253| ---------------| ---------------------------------------------------------------- | 254| FAST | The content of the view is blended in sequence on the target image. | 255| OFFSCREEN | The content of the component and its child components are drawn on the offscreen canvas, and then blended with the existing content on the canvas. | 256 257## useShadowBatching<sup>11+</sup> 258 259useShadowBatching(value: boolean) 260 261Sets whether to draw shadows of child nodes in the component at the same layer, so that the shadows of elements at the same layer overlap. 262 263**Atomic service API**: This API can be used in atomic services since API version 12. 264 265**System capability**: SystemCapability.ArkUI.ArkUI.Full 266 267**Widget capability**: This API can be used in ArkTS widgets since API version 11. 268 269**Parameters** 270 271| Name| Type | Mandatory| Description | 272| ------ | ------- | ---- | ------------------------------------------------------------ | 273| value | boolean | Yes | Whether to draw shadows of child nodes in the component at the same layer, so that the shadows of elements at the same layer overlap.<br>Default value: **false**<br>**NOTE**<br>1. When this feature is disabled (default), if the shadow radius of a child node is large, the shadows of the child nodes may overlap. This overlap issue does not occur when the feature is enabled.<br>2. Avoid nesting **useShadowBatching**. When used in nested mode, **useShadowBatching** takes effect for the current child node only and cannot be recursively used.| 274 275## sphericalEffect<sup>12+</sup> 276 277sphericalEffect(value: number) 278 279Applies a spherical effect to the component. 280 281**Atomic service API**: This API can be used in atomic services since API version 12. 282 283**System capability**: SystemCapability.ArkUI.ArkUI.Full 284 285**Parameters** 286 287| Name| Type | Mandatory| Description | 288| ------ | ------ | ---- | ------------------------------------------------------------ | 289| value | number | Yes | Spherical degree of the component.<br>The value ranges from 0 to 1.<br>**NOTE**<br>1. If the value is **0**, the component remains unchanged. If the value is 1, the component is completely spherical. Between **0** and **1**, a larger value indicates a higher spherical degree.<br>A value less than 0 is handled as the value **0**. A value greater than 1 is handled as the value **1**.<br>2. The component's shadow and outer stroke do not support spherical effects.<br>3. If the value is greater than 0, the component is frozen and not updated, and its content is drawn to the transparent offscreen buffer. To update the component attributes, set the value to **0**.| 290 291## lightUpEffect<sup>12+</sup> 292 293lightUpEffect(value: number) 294 295Applies a light up effect to the component. 296 297**Atomic service API**: This API can be used in atomic services since API version 12. 298 299**System capability**: SystemCapability.ArkUI.ArkUI.Full 300 301**Parameters** 302 303| Name| Type | Mandatory| Description | 304| ------ | ------ | ---- | ------------------------------------------------------------ | 305| value | number | Yes | Light up degree of the component.<br>The value ranges from 0 to 1.<br>If the value is **0**, the component is dark. If the value is **1**, the component is fully illuminated. Between **0** and **1**, a larger value indicates higher luminance. A value less than 0 is handled as the value **0**. A value greater than 1 is handled as the value **1**.| 306 307## pixelStretchEffect<sup>12+</sup> 308 309pixelStretchEffect(options: PixelStretchEffectOptions) 310 311Applies a pixel stretch effect to the component. 312 313**Atomic service API**: This API can be used in atomic services since API version 12. 314 315**System capability**: SystemCapability.ArkUI.ArkUI.Full 316 317**Parameters** 318 319| Name | Type | Mandatory| Description | 320| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 321| options | [PixelStretchEffectOptions](#pixelstretcheffectoptions10) | Yes | Pixel stretch effect options.<br>The value includes the length by which a pixel is stretched toward the four edges.<br>**NOTE**<br>1. If the length is a positive value, the original image is stretched, and the image size increases. The edge pixels grow by the set length toward the top, bottom, left, and right edges.<br>2. If the length is a negative value, the original image shrinks as follows, but the image size remains unchanged:<br>Shrinking mode:<br>(1) The image shrinks from the four edges by the absolute value of length set through **options**.<br>(2) The image is stretched back to the original size with edge pixels.<br>3. Constraints on **options**:<br>(1) The length values for the four edges must be all positive or all negative. That is, the four edges are stretched or shrink at the same time in the same direction.<br>(2) The length values must all be a percentage or a specific value. Combined use of the percentage and specific value is not allowed.<br>(3) If the input value is invalid, the image is displayed as {0, 0, 0, 0}, that is, the image is the same as the original image.| 322 323## PixelStretchEffectOptions<sup>10+</sup> 324 325Describes the pixel stretch effect options. 326 327**Atomic service API**: This API can be used in atomic services since API version 11. 328 329**System capability**: SystemCapability.ArkUI.ArkUI.Full 330 331| Name | Type | Mandatory | Description | 332| ------ | ----------------- | ---- | -------------- | 333| left | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the left edge of the image.| 334| right | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the right edge of the image.| 335| top | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the top edge of the image.| 336| bottom | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the right edge of the image.| 337 338## systemBarEffect<sup>12+</sup> 339 340systemBarEffect() 341 342Applies a system bar effect to the component, which means to invert colors based on the background and add a blur. 343 344**Atomic service API**: This API can be used in atomic services since API version 12. 345 346**System capability**: SystemCapability.ArkUI.ArkUI.Full 347 348## ShadowType<sup>10+<sup> 349 350**Atomic service API**: This API can be used in atomic services since API version 11. 351 352**System capability**: SystemCapability.ArkUI.ArkUI.Full 353 354| Name | Description | 355| -------- | ---------------------------------------- | 356| COLOR | Color. | 357| BLUR | Blur. | 358 359 360## ShadowOptions 361 362Provides the shadow attributes, including the blur radius, color, and offset along the x-axis and y-axis. 363 364 365**System capability**: SystemCapability.ArkUI.ArkUI.Full 366 367**Widget capability**: This API can be used in ArkTS widgets since API version 9. 368 369| Name | Type | Mandatory | Description | 370| ------- | ---------------------------------------- | ---- | ---------------------------------------- | 371| radius | number \| [Resource](ts-types.md#resource) | Yes | Blur radius of the shadow.<br>Value range: [0, +∞)<br>Unit: px<br>**NOTE**<br>A value less than 0 evaluates to the value **0**.<br>To use a value in the vp unit, call [vp2px](ts-pixel-units.md#pixel-unit-conversion) to convert it into px.<br>If **radius** is of the Resource type, its value must be of the number type.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 372| type<sup>10+</sup> | [ShadowType<sup>10+</sup>](#shadowtype10) | No | Shadow type.<br>Default value: **COLOR**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 373| color | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource)\| [ColoringStrategy<sup>10+</sup> ](ts-types.md#coloringstrategy10) | No | Color of the shadow.<br>The default color is black.<br>**NOTE**<br>Since API version 11, this API supports **ColoringStrategy**, which cannot be used with ArkTS widgets or the [textShadow](ts-basic-components-text.md#textshadow10) attribute.<br>With **ColoringStrategy**, the average color or primary color can be obtained, and the obtained color is applied to the shadow drawing area.<br>The **'average'** string can be used to trigger the mode for obtaining the average color, and the **'primary'** string for obtaining the primary color.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 374| offsetX | number \| [Resource](ts-types.md#resource) | No | Offset of the shadow along the x-axis.<br>Default value: **0**<br>Unit: px<br>**NOTE**<br>To use a value in the vp unit, call [vp2px](ts-pixel-units.md#pixel-unit-conversion) to convert it into px.<br>If **offsetX** is of the Resource type, its value must be of the number type.<br> **Atomic service API**: This API can be used in atomic services since API version 11.| 375| offsetY | number \| [Resource](ts-types.md#resource) | No | Offset of the shadow along the y-axis.<br>Default value: **0**<br>Unit: px<br>**NOTE**<br>To use a value in the vp unit, call [vp2px](ts-pixel-units.md#pixel-unit-conversion) to convert it into px.<br>If **offsetY** is of the Resource type, its value must be of the number type.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 376| fill<sup>11+</sup> | boolean | No | Whether to fill the inside of the component with shadow.<br>The default value is **false**.<br>**NOTE**<br>This attribute does not take effect in [textShadow](ts-basic-components-text.md#textshadow10).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 377 378## ShadowStyle<sup>10+</sup> 379 380**Atomic service API**: This API can be used in atomic services since API version 11. 381 382| Name | Description | 383| ----------------- | ------ | 384| OUTER_DEFAULT_XS | Mini shadow. | 385| OUTER_DEFAULT_SM | Small shadow. | 386| OUTER_DEFAULT_MD | Medium shadow. | 387| OUTER_DEFAULT_LG | Large shadow. | 388| OUTER_FLOATING_SM | Floating small shadow.| 389| OUTER_FLOATING_MD | Floating medium shadow.| 390 391## BlendMode<sup>11+</sup> 392 393> **NOTE** 394> 395> In the **blendMode** enums, **s** indicates the source pixel, **d** indicates the target pixel, **sa** indicates the opacity of the source pixel, **da** indicates the opacity of the target pixel, **r** indicates the pixel after blending, and **ra** indicates the opacity of the pixel after blending. 396 397**Widget capability**: This API can be used in ArkTS widgets since API version 11. 398 399**Atomic service API**: This API can be used in atomic services since API version 12. 400 401| Name | Description | 402| ---------------| ------ | 403| NONE | The top image is superimposed on the bottom image without any blending. | 404| CLEAR | The target pixels covered by the source pixels are erased by being turned to completely transparent. | 405| SRC | r = s: Only the source pixels are displayed. | 406| DST | r = d: Only the target pixels are displayed. | 407| SRC_OVER | r = s + (1 - sa) * d: The source pixels are blended based on opacity and cover the target pixels. | 408| DST_OVER | r = d + (1 - da) * s: The target pixels are blended based on opacity and cover on the source pixels. | 409| SRC_IN | r = s * da: Only the part of the source pixels that overlap with the target pixels is displayed. | 410| DST_IN | r = d * sa: Only the part of the target pixels that overlap with the source pixels is displayed. | 411| SRC_OUT | r = s * (1 - da): Only the part of the source pixels that do not overlap with the target pixels is displayed. | 412| DST_OUT | r = d * (1 - sa): Only the part of the target pixels that do not overlap with the source pixels is displayed. | 413| SRC_ATOP | r = s * da + d * (1 - sa): The part of the source pixels that overlap with the target pixels is displayed and the part of the target pixels that do not overlap with the source pixels are displayed. | 414| DST_ATOP | r = d * sa + s * (1 - da): The part of the target pixels that overlap with the source pixels and the part of the source pixels that do not overlap with the target pixels are displayed. | 415| XOR | r = s * (1 - da) + d * (1 - sa): Only the non-overlapping part between the source pixels and the target pixels is displayed. | 416| PLUS | r = min(s + d, 1): New pixels resulting from adding the source pixels to the target pixels are displayed. | 417| MODULATE | r = s * d: New pixels resulting from multiplying the source pixels with the target pixels are displayed. | 418| SCREEN | r = s + d - s * d: Pixels are blended by adding the source pixels to the target pixels and subtracting the product of their multiplication. | 419| OVERLAY | The MULTIPLY or SCREEN mode is used based on the target pixels. | 420| DARKEN | rc = s + d - max(s * da, d * sa), ra = kSrcOver: When two colors overlap, whichever is darker is used. | 421| LIGHTEN | rc = s + d - min(s * da, d * sa), ra = kSrcOver: The darker of the pixels (source and target) is used. | 422| COLOR_DODGE | The colors of the target pixels are lightened to reflect the source pixels. | 423| COLOR_BURN | The colors of the target pixels are darkened to reflect the source pixels. | 424| HARD_LIGHT | The MULTIPLY or SCREEN mode is used, depending on the source pixels. | 425| SOFT_LIGHT | The LIGHTEN or DARKEN mode is used, depending on the source pixels. | 426| DIFFERENCE | rc = s + d - 2 * (min(s * da, d * sa)), ra = kSrcOver: The final pixel is the result of subtracting the darker of the two pixels (source and target) from the lighter one. | 427| EXCLUSION | rc = s + d - two(s * d), ra = kSrcOver: The final pixel is similar to <b>DIFFERENCE</b>, but with less contrast. | 428| MULTIPLY | r = s * (1 - da) + d * (1 - sa) + s * d: The final pixel is the result of multiplying the source pixel by the target pixel. | 429| HUE | The resultant image is created with the luminance and saturation of the source image and the hue of the target image. | 430| SATURATION | The resultant image is created with the luminance and hue of the target image and the saturation of the source image. | 431| COLOR | The resultant image is created with the saturation and hue of the source image and the luminance of the target image. | 432| LUMINOSITY | The resultant image is created with the saturation and hue of the target image and the luminance of the source image. | 433 434## LinearGradientBlurOptions<sup>12+</sup> 435 436**Atomic service API**: This API can be used in atomic services since API version 12. 437 438| Name | Type | Mandatory | Description | 439| ------------- | ----------------------------------------------------------- | ----- | ------------------------------------------------------------ | 440| fractionStops | Array\<[FractionStop](#fractionstop12)> | Yes | Gradient blur stops. The value is a set of binary arrays, each of which indicates [blur degree, blur position] and consists of numbers ranging from 0 to 1 (those less than 0 are treated as **0**, and those greater than 1 are treated as **1**). The blur positions in the arrays must be in strict ascending order. Noncompliance will be logged. For the blur settings to take effect, the number of binary arrays must be greater than or equal to 2.| 441| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | Yes | Gradient blur direction.<br>Default value:<br>GradientDirection.Bottom | 442 443## FractionStop<sup>12+</sup> 444 445FractionStop = [ number, number ] 446 447Defines a gradient blur stop. 448 449**Atomic service API**: This API can be used in atomic services since API version 12. 450 451**System capability**: SystemCapability.ArkUI.ArkUI.Full 452 453| Value Range | Description | 454| ------------- | ---------------------------------------------------------- | 455| number | Blur degree, represented by a fraction. The value **1** means opaque, and **0** means completely transparent.<br>Value range: [0, 1] | 456| number | Stop position. The value **1** indicates the end position and **0** the end position.<br> Value range: [0, 1]| 457 458## InvertOptions<sup>11+</sup> 459 460Describes the options for inverting the foreground color. 461 462**Atomic service API**: This API can be used in atomic services since API version 12. 463 464| Name | Type | Mandatory | Description | 465| -------------- | ------ | ----- | ------------------------------------------ | 466| low | number | Yes | Value when the background color is greater than the grayscale threshold. | 467| high | number | Yes | Value when the background color is less than the grayscale threshold. | 468| threshold | number | Yes | Grayscale threshold. | 469| thresholdRange | number | Yes | Threshold value range.<br>**NOTE**<br>This range defines the upper and lower bounds of the grayscale threshold. The grayscale value changes linearly from high to low within the range.| 470 471## freeze<sup>12+</sup> 472 473freeze(value: boolean) 474 475Sets whether to freeze the component. A frozen component can no longer be changed once it and its child components are rendered off the screen: Its attributes cannot be updated across renders. 476 477**Atomic service API**: This API can be used in atomic services since API version 12. 478 479**System capability**: SystemCapability.ArkUI.ArkUI.Full 480 481**Parameters** 482 483| Name| Type | Mandatory| Description | 484| ------ | ------- | ---- | ------------------------------------------------------------ | 485| value | boolean | Yes | Whether to freeze the component. A frozen component can no longer be changed once it and its child components are rendered off the screen: Its attributes cannot be updated across renders. If the opacity of the component is not 1, the drawing effect may vary depending on the value.<br>Default value: **false**| 486 487## Example 488 489 490 491### Example 1 492This example applies different image effects. 493```ts 494// xxx.ets 495@Entry 496@Component 497struct ImageEffectsExample { 498 build() { 499 Column({ space: 5 }) { 500 // Apply the shadow effect. 501 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 502 Image($r('app.media.image')) 503 .width('90%') 504 .height(30) 505 .shadow({ radius: 10, color: Color.Green, offsetX: 20, offsetY: 20 }) 506 507 // Add the internal shadow effect. 508 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 509 Image($r('app.media.image')) 510 .width('90%') 511 .height(30) 512 .shadow({ radius: 5, color: Color.Green, offsetX: 20, offsetY: 20,fill:true }).opacity(0.5) 513 514 // Apply the grayscale effect. The grayscale value ranges from 0 to 1. The closer the grayscale value is to 1, the more obvious the grayscale effect is. 515 Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%') 516 Image($r('app.media.image')).width('90%').height(30).grayscale(0.3) 517 Image($r('app.media.image')).width('90%').height(30).grayscale(0.8) 518 519 // Apply the brightness effect. The value 1 indicates no effects. If the value is less than 1, the brightness decreases. If the value is greater than 1, the brightness increases. 520 Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%') 521 Image($r('app.media.image')).width('90%').height(30).brightness(1.2) 522 523 // Apply the saturation effect. If the value is 1, the source image is displayed. 524 Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%') 525 Image($r('app.media.image')).width('90%').height(30).saturate(2.0) 526 Image($r('app.media.image')).width('90%').height(30).saturate(0.7) 527 528 // Apply the contrast effect. If the value is 1, the source image is displayed. If the value is greater than 1, a larger value indicates a higher contrast and a clearer image. If the value is less than 1, a smaller value indicates a lower contrast is. 529 Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%') 530 Image($r('app.media.image')).width('90%').height(30).contrast(2.0) 531 Image($r('app.media.image')).width('90%').height(30).contrast(0.8) 532 533 // Invert the image. 534 Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%') 535 Image($r('app.media.image')).width('90%').height(30).invert(0.2) 536 Image($r('app.media.image')).width('90%').height(30).invert(0.8) 537 538 // Apply the color blend effect. 539 Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%') 540 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Green) 541 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Blue) 542 543 // Convert the image color to sepia. 544 Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%') 545 Image($r('app.media.image')).width('90%').height(30).sepia(0.8) 546 547 // Apply the hue rotation effect. 548 Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%') 549 Image($r('app.media.image')).width('90%').height(30).hueRotate(90) 550 }.width('100%').margin({ top: 5 }) 551 } 552} 553``` 554 555 556 557 558### Example 2 559 560This example applies a linear gradient blur effect to a component. 561 562```ts 563// xxx.ets 564@Entry 565@Component 566struct ImageExample1 { 567 private_resource1:Resource = $r('app.media.testlinearGradientBlurOrigin') 568 @State image_src: Resource = this.private_resource1 569 build() { 570 Column() { 571 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 572 Row({ space: 5 }) { 573 Image(this.image_src) 574 .linearGradientBlur(60, { fractionStops: [[0,0],[0,0.33],[1,0.66],[1,1]], direction: GradientDirection.Bottom }) 575 } 576 } 577 } 578 } 579} 580 581``` 582 583 584 585### Example 3 586This example shows how to use **renderGroup**: 587```ts 588// xxx.ets 589@Component 590struct Component1 { 591 @Prop renderGroupValue: boolean; 592 build() { 593 Row() { 594 Row() { 595 Row() 596 .backgroundColor(Color.Black) 597 .width(100) 598 .height(100) 599 .opacity(1) 600 } 601 .backgroundColor(Color.White) 602 .width(150) 603 .height(150) 604 .justifyContent(FlexAlign.Center) 605 .opacity(0.6) 606 .renderGroup(this.renderGroupValue) 607 } 608 .backgroundColor(Color.Black) 609 .width(200) 610 .height(200) 611 .justifyContent(FlexAlign.Center) 612 .opacity(1) 613 } 614} 615@Entry 616@Component 617struct RenderGroupExample { 618 build() { 619 Column() { 620 Component1({renderGroupValue: true}) 621 .margin(20) 622 Component1({renderGroupValue: false}) 623 .margin(20) 624 } 625 .width("100%") 626 .height("100%") 627 .alignItems(HorizontalAlign.Center) 628 } 629} 630``` 631 632 633 634### Example 4 635This example shows how to use **blendMode** alone: 636```ts 637// xxx.ets 638@Entry 639@Component 640struct Index { 641 build() { 642 Column() { 643 Text("blendMode") 644 .fontSize(20) 645 .fontWeight(FontWeight.Bold) 646 .fontColor('#ffff0101') 647 Row() { 648 Circle() 649 .width(200) 650 .height(200) 651 .fill(Color.Green) 652 .position({ x: 50, y: 50 }) 653 Circle() 654 .width(200) 655 .height(200) 656 .fill(Color.Blue) 657 .position({ x: 150, y: 50 }) 658 } 659 .blendMode(BlendMode.OVERLAY,BlendApplyType.OFFSCREEN) 660 .alignItems(VerticalAlign.Center) 661 .height(300) 662 .width('100%') 663 } 664 .height('100%') 665 .width('100%') 666 .backgroundImage($r('app.media.image')) 667 .backgroundImageSize(ImageSize.Cover) 668 } 669} 670``` 671 672<br>BlendMode.OVERLAY,BlendApplyType.OFFSCREEN<br> 673 674<br>**blendMode** can be used with offscreen rendering to produce different effects. 675 676### Example 5 677This example shows how to use **InvertOptions**: 678```ts 679// xxx.ets 680 @Entry 681 @Component 682 struct Index { 683 build() { 684 Stack() { 685 Column() 686 Stack(){ 687 Image($r('app.media.r')).width('100%') 688 Column(){ 689 Column().width("100%").height(30).invert({ 690 low:0, 691 high:1, 692 threshold:0.5, 693 thresholdRange:0.2 694 }) 695 Column().width("100%").height(30).invert({ 696 low:0.2, 697 high:0.5, 698 threshold:0.3, 699 thresholdRange:0.2 700 }) 701 } 702 } 703 .width('100%') 704 .height('100%') 705 } 706 } 707 } 708 709``` 710 711 712 713### Example 6 714This example shows how to use **UseShadowBatching** with **shadow** to ensure that shadows at the same layer do not overlap: 715```ts 716// xxx.ets 717@Entry 718@Component 719struct UseShadowBatchingExample { 720 build() { 721 Column() { 722 Column({ space: 10 }) { 723 Stack() { 724 725 }.width('90%').height(50).margin({ top: 5 }).backgroundColor(0xFFE4C4) 726 .shadow({ radius: 120, color: Color.Green, offsetX: 0, offsetY: 0 }) 727 .align(Alignment.TopStart).shadow({ radius: 120, color: Color.Green, offsetX: 0, offsetY: 0 }) 728 729 Stack() { 730 731 }.width('90%').height(50).margin({ top: 5 }).backgroundColor(0xFFE4C4) 732 .align(Alignment.TopStart).shadow({ radius: 120, color: Color.Red, offsetX: 0, offsetY: 0 }) 733 .width('90%') 734 .backgroundColor(Color.White) 735 736 Column() { 737 Text() 738 .fontWeight(FontWeight.Bold) 739 .fontSize(20) 740 .fontColor(Color.White) 741 } 742 .justifyContent(FlexAlign.Center) 743 .width(150) 744 .height(150) 745 .borderRadius(10) 746 .backgroundColor(0xf56c6c) 747 .shadow({ radius: 300, color: Color.Yellow, offsetX: 0, offsetY: 0 }) 748 749 Column() { 750 Text() 751 .fontWeight(FontWeight.Bold) 752 .fontSize(20) 753 .fontColor(Color.White) 754 } 755 .justifyContent(FlexAlign.Center) 756 .width(150) 757 .height(150) 758 .backgroundColor(0x67C23A) 759 .borderRadius(10) 760 .translate({ y: -50}) 761 .shadow({ radius: 220, color: Color.Blue, offsetX: 0, offsetY: 0 }) 762 } 763 .useShadowBatching(true) 764 } 765 .width('100%').margin({ top: 5 }) 766 } 767} 768``` 769 770 771 772### Example 7 773 774This example applies a spherical effect to a component. 775 776```ts 777// xxx.ets 778@Entry 779@Component 780struct SphericalEffectExample { 781 build() { 782 Stack() { 783 TextInput({placeholder: "Enter a percentage."}) 784 .width('50%') 785 .height(35) 786 .type(InputType.Number) 787 .enterKeyType(EnterKeyType.Done) 788 .caretColor(Color.Red) 789 .placeholderColor(Color.Blue) 790 .placeholderFont({ 791 size: 20, 792 style: FontStyle.Italic, 793 weight: FontWeight.Bold 794 }) 795 .sphericalEffect(0.5) 796 }.alignContent(Alignment.Center).width("100%").height("100%") 797 } 798} 799 800``` 801 802Below is how the component looks with the spherical effect applied. 803 804 805 806Below is how the component looks without the spherical effect applied. 807 808 809 810### Example 8 811 812This example applies a light up effect to a component. 813 814```ts 815// xxx.ets 816@Entry 817@Component 818struct LightUpExample { 819 build() { 820 Stack() { 821 Text('This is the text content with letterSpacing 0.') 822 .letterSpacing(0) 823 .fontSize(12) 824 .border({ width: 1 }) 825 .padding(10) 826 .width('50%') 827 .lightUpEffect(0.6) 828 }.alignContent(Alignment.Center).width("100%").height("100%") 829 } 830} 831 832``` 833 834Below is how the component looks with the light up effect applied. 835 836 837 838Below is how the component looks with **lightUpEffect** set to **0.2**: 839 840 841 842Below is how the component looks without the light up effect applied. 843 844 845 846### Example 9 847 848This example applies a pixel stretch effect to a component. 849 850```ts 851// xxx.ets 852@Entry 853@Component 854struct PixelStretchExample { 855 build() { 856 Stack() { 857 Text('This is the text content with letterSpacing 0.') 858 .letterSpacing(0) 859 .fontSize(12) 860 .border({ width: 1 }) 861 .padding(10) 862 .clip(false) 863 .width('50%') 864 .pixelStretchEffect({top:10,left:10,right:10,bottom:10 }) 865 }.alignContent(Alignment.Center).width("100%").height("100%") 866 } 867} 868 869``` 870 871Below is how the component looks with the pixel stretch effect applied. 872 873 874 875Below is how the component looks without the pixel stretch effect applied. 876 877 878 879 880### Example 10 881 882This example applies a system bar effect to a component. 883 884```ts 885// xxx.ets 886@Entry 887@Component 888struct Index { 889 build() { 890 Column() { 891 Stack(){ 892 Image($r('app.media.testImage')).width('100%').height('100%') 893 Column().width(150).height(10) 894 .systemBarEffect() 895 .border({radius:5}) 896 .margin({bottom:80}) 897 }.alignContent(Alignment.Center) 898 } 899 } 900} 901 902``` 903 904Below is how the component looks with the system bar effect applied. 905 906 907
