1# Image Effect 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, 1000]<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 as a whole before being blended 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 as a whole before being blended 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. **BlendApplyType.FAST**: The blend mode is not implemented offscreen.<br>2. **BlendApplyType.OFFSCREEN**: An offscreen canvas of 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. This approach may cause issues with screen capture for APIs such as [linearGradientBlur<sup>12+</sup>](#lineargradientblur12), [backgroundEffect](ts-universal-attributes-background.md#backgroundeffect11), and [brightness](#brightness).| 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 350Enumerates the shadow types. 351 352**Atomic service API**: This API can be used in atomic services since API version 11. 353 354**System capability**: SystemCapability.ArkUI.ArkUI.Full 355 356| Name | Description | 357| -------- | ---------------------------------------- | 358| COLOR | Color. | 359| BLUR | Blur. | 360 361 362## ShadowOptions 363 364Provides the shadow attributes, including the blur radius, color, and offset along the x-axis and y-axis. 365 366 367**System capability**: SystemCapability.ArkUI.ArkUI.Full 368 369**Widget capability**: This API can be used in ArkTS widgets since API version 9. 370 371| Name | Type | Mandatory | Description | 372| ------- | ---------------------------------------- | ---- | ---------------------------------------- | 373| 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.| 374| 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. | 375| color | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource)\| [ColoringStrategy<sup>10+</sup> ](ts-appendix-enums.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.| 376| 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.| 377| 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.| 378| 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.| 379 380## ShadowStyle<sup>10+</sup> 381 382**Atomic service API**: This API can be used in atomic services since API version 11. 383 384| Name | Description | 385| ----------------- | ------ | 386| OUTER_DEFAULT_XS | Mini shadow. | 387| OUTER_DEFAULT_SM | Small shadow. | 388| OUTER_DEFAULT_MD | Medium shadow. | 389| OUTER_DEFAULT_LG | Large shadow. | 390| OUTER_FLOATING_SM | Floating small shadow.| 391| OUTER_FLOATING_MD | Floating medium shadow.| 392 393## BlendMode<sup>11+</sup> 394 395> **NOTE** 396> 397> 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. 398 399**Widget capability**: This API can be used in ArkTS widgets since API version 11. 400 401**Atomic service API**: This API can be used in atomic services since API version 12. 402 403| Name | Description | 404| ---------------| ------ | 405| NONE | The top image is superimposed on the bottom image without any blending. | 406| CLEAR | The target pixels covered by the source pixels are erased by being turned to completely transparent. | 407| SRC | r = s: Only the source pixels are displayed. | 408| DST | r = d: Only the target pixels are displayed. | 409| SRC_OVER | r = s + (1 - sa) * d: The source pixels are blended based on opacity and cover the target pixels. | 410| DST_OVER | r = d + (1 - da) * s: The target pixels are blended based on opacity and cover on the source pixels. | 411| SRC_IN | r = s * da: Only the part of the source pixels that overlap with the target pixels is displayed. | 412| DST_IN | r = d * sa: Only the part of the target pixels that overlap with the source pixels is displayed. | 413| SRC_OUT | r = s * (1 - da): Only the part of the source pixels that do not overlap with the target pixels is displayed. | 414| DST_OUT | r = d * (1 - sa): Only the part of the target pixels that do not overlap with the source pixels is displayed. | 415| 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. | 416| 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. | 417| XOR | r = s * (1 - da) + d * (1 - sa): Only the non-overlapping part between the source pixels and the target pixels is displayed. | 418| PLUS | r = min(s + d, 1): New pixels resulting from adding the source pixels to the target pixels are displayed. | 419| MODULATE | r = s * d: New pixels resulting from multiplying the source pixels with the target pixels are displayed. | 420| 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. | 421| OVERLAY | The MULTIPLY or SCREEN mode is used based on the target pixels. | 422| DARKEN | rc = s + d - max(s * da, d * sa), ra = kSrcOver: When two colors overlap, whichever is darker is used. | 423| LIGHTEN | rc = s + d - min(s * da, d * sa), ra = kSrcOver: The darker of the pixels (source and target) is used. | 424| COLOR_DODGE | The colors of the target pixels are lightened to reflect the source pixels. | 425| COLOR_BURN | The colors of the target pixels are darkened to reflect the source pixels. | 426| HARD_LIGHT | The MULTIPLY or SCREEN mode is used, depending on the source pixels. | 427| SOFT_LIGHT | The LIGHTEN or DARKEN mode is used, depending on the source pixels. | 428| 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. | 429| EXCLUSION | rc = s + d - two(s * d), ra = kSrcOver: The final pixel is similar to **DIFFERENCE**, but with less contrast. | 430| 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. | 431| HUE | The resultant image is created with the luminance and saturation of the source image and the hue of the target image. | 432| SATURATION | The resultant image is created with the luminance and hue of the target image and the saturation of the source image. | 433| COLOR | The resultant image is created with the saturation and hue of the source image and the luminance of the target image. | 434| LUMINOSITY | The resultant image is created with the saturation and hue of the target image and the luminance of the source image. | 435 436## LinearGradientBlurOptions<sup>12+</sup> 437 438**Atomic service API**: This API can be used in atomic services since API version 12. 439 440| Name | Type | Mandatory | Description | 441| ------------- | ----------------------------------------------------------- | ----- | ------------------------------------------------------------ | 442| 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.| 443| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | Yes | Gradient blur direction.<br>Default value:<br>GradientDirection.Bottom | 444 445## FractionStop<sup>12+</sup> 446 447FractionStop = [ number, number ] 448 449Defines a gradient blur stop. 450 451**Atomic service API**: This API can be used in atomic services since API version 12. 452 453**System capability**: SystemCapability.ArkUI.ArkUI.Full 454 455| Value Range | Description | 456| ------------- | ---------------------------------------------------------- | 457| number | Blur degree, represented by a fraction. The value **1** means opaque, and **0** means completely transparent.<br>Value range: [0, 1] | 458| number | Stop position. The value **1** indicates the end position and **0** the end position.<br> Value range: [0, 1]| 459 460## InvertOptions<sup>11+</sup> 461 462Describes the options for inverting the foreground color. 463 464**Atomic service API**: This API can be used in atomic services since API version 12. 465 466| Name | Type | Mandatory | Description | 467| -------------- | ------ | ----- | ------------------------------------------ | 468| low | number | Yes | Value when the background color is greater than the grayscale threshold. | 469| high | number | Yes | Value when the background color is less than the grayscale threshold. | 470| threshold | number | Yes | Grayscale threshold. | 471| 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.| 472 473## freeze<sup>12+</sup> 474 475freeze(value: boolean) 476 477Sets 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. 478 479**Atomic service API**: This API can be used in atomic services since API version 12. 480 481**System capability**: SystemCapability.ArkUI.ArkUI.Full 482 483**Parameters** 484 485| Name| Type | Mandatory| Description | 486| ------ | ------- | ---- | ------------------------------------------------------------ | 487| 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**| 488 489## Example 490 491### Example 1: Setting Different Image Attributes 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({ 506 radius: 10, 507 color: Color.Green, 508 offsetX: 20, 509 offsetY: 20 510 }) 511 512 // Add the internal shadow effect. 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 // 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. 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 // 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. 531 Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%') 532 Image($r('app.media.image')).width('90%').height(30).brightness(1.2) 533 534 // Apply the saturation effect. If the value is 1, the source image is displayed. 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 // 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. 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 // Invert the image. 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 // Apply the color blend effect. 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 // Convert the image color to sepia. 555 Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%') 556 Image($r('app.media.image')).width('90%').height(30).sepia(0.8) 557 558 // Apply the hue rotation effect. 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### Example 2: Applying a Linear Gradient Blur Effect 570 571This example demonstrates how to apply a linear gradient blur effect on a component using **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### Example 3: Setting Offscreen Rendering Effect 598 599This example demonstrates how to use **renderGroup** to set whether to render a component offscreen before blending it with its parent component. 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### Example 4: Blending the Current Component Content with Canvas Content 651 652This example demonstrates how to blend the current component content with the canvas content below using **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>**blendMode** can be used with offscreen rendering to produce different effects. 693 694### Example 5: Inverting the Foreground Color 695 696This example demonstrates how to invert the foreground color using **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### Example 6: Setting Non-Overlapping Same-Layer Shadows 733 734This example demonstrates how to implement non-overlapping shadows at the same layer using **useShadowBatching** with **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### Example 7: Applying a Spherical Effect to a Component 829 830This example demonstrates how to apply a spherical effect to a component using **sphericalEffect**. 831 832```ts 833// xxx.ets 834@Entry 835@Component 836struct SphericalEffectExample { 837 build() { 838 Stack() { 839 TextInput({ placeholder: "Enter a percentage." }) 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 857Below is how the component looks with the spherical effect applied. 858 859 860 861Below is how the component looks without the spherical effect applied. 862 863 864 865### Example 8: Applying a Light Up Effect to a Component 866 867This example demonstrates how to apply a light up effect to a component using **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 889Below is how the component looks with the light up effect applied. 890 891 892 893Below is how the component looks with **lightUpEffect** set to **0.2**: 894 895 896 897Below is how the component looks without the light up effect applied. 898 899 900 901### Example 9: Applying a Pixel Stretch Effect to a Component 902 903This example demonstrates how to apply a pixel stretch effect to a component using **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 930Below is how the component looks with the pixel stretch effect applied. 931 932 933 934Below is how the component looks without the pixel stretch effect applied. 935 936 937 938 939### Example 10: Applying a System Bar Effect to a Component 940 941This example demonstrates how to apply a system bar effect to a component using **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 964Below is how the component looks with the system bar effect applied. 965 966 967
