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## blur<sup>18+</sup> 29 30blur(blurRadius: Optional\<number>, options?: BlurOptions, sysOptions?: [SystemAdaptiveOptions](ts-universal-attributes-background.md#systemadaptiveoptions18)) 31 32Applies a foreground blur effect to the component. Compared to [blur](#blur), this API supports the **undefined** type for the **blurRadius** parameter. 33 34**Widget capability**: This API can be used in ArkTS widgets since API version 18. 35 36**Atomic service API**: This API can be used in atomic services since API version 18. 37 38**System capability**: SystemCapability.ArkUI.ArkUI.Full 39 40**Parameters** 41 42| Name | Type | Mandatory| Description | 43| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 44| blurRadius | Optional\<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.<br>If **blurRadius** is set to **undefined**, the previous value is retained.| 45| options<sup>16+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | No | Grayscale parameters. | 46| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](ts-universal-attributes-background.md#systemadaptiveoptions18) | No | System adaptive adjustment options.<br>Default value: **{ disableSystemAdaptation: false }** | 47 48## shadow 49 50shadow(value: ShadowOptions | ShadowStyle) 51 52Applies a shadow effect to the component. 53 54**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. 55 56**Atomic service API**: This API can be used in atomic services since API version 11. 57 58**System capability**: SystemCapability.ArkUI.ArkUI.Full 59 60**Parameters** 61 62| Name| Type | Mandatory| Description | 63| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 64| 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.| 65 66## shadow<sup>18+</sup> 67 68shadow(options: Optional\<ShadowOptions | ShadowStyle>) 69 70Applies a shadow effect to the component. Compared to [shadow](#shadow), this API supports the **undefined** type for the **options** parameter. 71 72**Widget capability**: Since API version 18, this API is supported in ArkTS widgets. Yet, the [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) type is not supported in ArkTS widgets. 73 74**Atomic service API**: This API can be used in atomic services since API version 18. 75 76**System capability**: SystemCapability.ArkUI.ArkUI.Full 77 78**Parameters** 79 80| Name | Type | Mandatory | Description| 81| ------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ---- | 82| options | Optional\<[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.<br>If **options** is **undefined**, the component reverts to its original effect with no shadow. | 83 84## grayscale 85 86grayscale(value: number) 87 88Applies a grayscale effect to the component. 89 90**Widget capability**: This API can be used in ArkTS widgets since API version 9. 91 92**Atomic service API**: This API can be used in atomic services since API version 11. 93 94**System capability**: SystemCapability.ArkUI.ArkUI.Full 95 96**Parameters** 97 98| Name| Type | Mandatory| Description | 99| ------ | ------ | ---- | ------------------------------------------------------------ | 100| 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**.| 101 102## grayscale<sup>18+</sup> 103 104grayscale(grayscale: Optional\<number>) 105 106Applies a grayscale effect to the component. Compared to [grayscale](#grayscale), this API supports the **undefined** type for the **grayscale** parameter. 107 108**Widget capability**: This API can be used in ArkTS widgets since API version 18. 109 110**Atomic service API**: This API can be used in atomic services since API version 18. 111 112**System capability**: SystemCapability.ArkUI.ArkUI.Full 113 114**Parameters** 115 116| Name | Type | Mandatory| Description | 117| --------- | ----------------- | ---- | ------------------------------------------------------------ | 118| grayscale | Optional\<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**.<br>If **grayscale** is set to **undefined**, the default value is used, which means the component reverts to its original effect with no grayscale.| 119 120## brightness 121 122brightness(value: number) 123 124Applies a brightness effect to the component. 125 126**Widget capability**: This API can be used in ArkTS widgets since API version 9. 127 128**Atomic service API**: This API can be used in atomic services since API version 11. 129 130**System capability**: SystemCapability.ArkUI.ArkUI.Full 131 132**Parameters** 133 134| Name| Type | Mandatory| Description | 135| ------ | ------ | ---- | ------------------------------------------------------------ | 136| 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.| 137 138## brightness<sup>18+</sup> 139 140brightness(brightness: Optional\<number>) 141 142Applies a brightness effect to the component. Compared to [brightness](#brightness), this API supports the **undefined** type for the **brightness** parameter. 143 144**Widget capability**: This API can be used in ArkTS widgets since API version 18. 145 146**Atomic service API**: This API can be used in atomic services since API version 18. 147 148**System capability**: SystemCapability.ArkUI.ArkUI.Full 149 150**Parameters** 151 152| Name | Type | Mandatory| Description | 153| ---------- | ----------------- | ---- | ------------------------------------------------------------ | 154| brightness | Optional\<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 16.<br>If **brightness** is **undefined**, the brightness level is reset to **0**.| 155 156## saturate 157 158saturate(value: number) 159 160Applies a saturation effect to the component. 161 162**Widget capability**: This API can be used in ArkTS widgets since API version 9. 163 164**Atomic service API**: This API can be used in atomic services since API version 11. 165 166**System capability**: SystemCapability.ArkUI.ArkUI.Full 167 168**Parameters** 169 170| Name| Type | Mandatory| Description | 171| ------ | ------ | ---- | ------------------------------------------------------------ | 172| 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**.| 173 174## saturate<sup>18+</sup> 175 176saturate(saturate: Optional\<number>) 177 178Applies a saturation effect to the component. Compared to [saturate](#saturate), this API supports the **undefined** type for the **saturate** parameter. 179 180**Widget capability**: This API can be used in ArkTS widgets since API version 18. 181 182**Atomic service API**: This API can be used in atomic services since API version 18. 183 184**System capability**: SystemCapability.ArkUI.ArkUI.Full 185 186**Parameters** 187 188| Name | Type | Mandatory| Description | 189| -------- | ----------------- | ---- | ------------------------------------------------------------ | 190| saturate | Optional\<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**.<br>If **saturate** is **undefined**, the saturation effect is reset to **1.0**.| 191 192## contrast 193 194contrast(value: number) 195 196Applies a contrast effect to the component. 197 198**Widget capability**: This API can be used in ArkTS widgets since API version 9. 199 200**Atomic service API**: This API can be used in atomic services since API version 11. 201 202**System capability**: SystemCapability.ArkUI.ArkUI.Full 203 204**Parameters** 205 206| Name| Type | Mandatory| Description | 207| ------ | ------ | ---- | ------------------------------------------------------------ | 208| 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**.| 209 210## contrast<sup>18+</sup> 211 212contrast(contrast: Optional\<number>) 213 214Applies a contrast effect to the component. Compared to [contrast](#contrast), this API supports the **undefined** type for the **contrast** parameter. 215 216**Widget capability**: This API can be used in ArkTS widgets since API version 18. 217 218**Atomic service API**: This API can be used in atomic services since API version 18. 219 220**System capability**: SystemCapability.ArkUI.ArkUI.Full 221 222**Parameters** 223 224| Name | Type | Mandatory| Description | 225| -------- | ----------------- | ---- | ------------------------------------------------------------ | 226| contrast | Optional\<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**.<br>If **contrast** is **undefined**, the contrast effect is reset to **1.0**.| 227 228## invert 229 230invert(value: number | InvertOptions) 231 232Inverts the image. 233 234**Widget capability**: This API can be used in ArkTS widgets since API version 9. 235 236**Atomic service API**: This API can be used in atomic services since API version 11. 237 238**System capability**: SystemCapability.ArkUI.ArkUI.Full 239 240**Parameters** 241 242| Name| Type | Mandatory| Description | 243| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 244| 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.| 245 246## invert<sup>18+</sup> 247 248invert(options: Optional\<number | InvertOptions>) 249 250Inverts the image. Compared to [invert](#invert), this API supports the **undefined** type for the **options** parameter. 251 252**Widget capability**: This API can be used in ArkTS widgets since API version 18. 253 254**Atomic service API**: This API can be used in atomic services since API version 18. 255 256**System capability**: SystemCapability.ArkUI.ArkUI.Full 257 258**Parameters** 259 260| Name | Type | Mandatory| Description | 261| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 262| options | Optional\<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.<br>If **options** is **undefined**, the component reverts to its original effect.| 263 264## sepia 265 266sepia(value: number) 267 268Sepia conversion ratio of the component. 269 270**Widget capability**: This API can be used in ArkTS widgets since API version 9. 271 272**Atomic service API**: This API can be used in atomic services since API version 11. 273 274**System capability**: SystemCapability.ArkUI.ArkUI.Full 275 276**Parameters** 277 278| Name| Type | Mandatory| Description | 279| ------ | ------ | ---- | ------------------------------------------------------------ | 280| 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.<br> Value range: [0, +∞)| 281 282## sepia<sup>18+</sup> 283 284sepia(sepia: Optional\<number>) 285 286Sepia conversion ratio of the component. Compared to [sepia](#sepia), this API supports the **undefined** type for the **sepia** parameter. 287 288**Widget capability**: This API can be used in ArkTS widgets since API version 18. 289 290**Atomic service API**: This API can be used in atomic services since API version 18. 291 292**System capability**: SystemCapability.ArkUI.ArkUI.Full 293 294**Parameters** 295 296| Name| Type | Mandatory| Description | 297| ------ | ----------------- | ---- | ------------------------------------------------------------ | 298| sepia | Optional\<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.<br>If **sepia** is **undefined**, the component reverts to its original effect.<br> Value range: [0, +∞)| 299 300## hueRotate 301 302hueRotate(value: number | string) 303 304Rotates the hue of the component. 305 306**Widget capability**: This API can be used in ArkTS widgets since API version 9. 307 308**Atomic service API**: This API can be used in atomic services since API version 11. 309 310**System capability**: SystemCapability.ArkUI.ArkUI.Full 311 312**Parameters** 313 314| Name| Type | Mandatory| Description | 315| ------ | -------------------------- | ---- | ------------------------------------------------------------ | 316| 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'**.| 317 318## hueRotate<sup>18+</sup> 319 320hueRotate(rotation: Optional\<number | string>) 321 322Rotates the hue of the component. Compared to [hueRotate](#huerotate), this API supports the **undefined** type for the **rotation** parameter. 323 324**Widget capability**: This API can be used in ArkTS widgets since API version 18. 325 326**Atomic service API**: This API can be used in atomic services since API version 18. 327 328**System capability**: SystemCapability.ArkUI.ArkUI.Full 329 330**Parameters** 331 332| Name | Type | Mandatory | Description| 333| -------- | ------------------------------------- | ------------------------------------------------------------ | ---- | 334| rotation | Optional\<number \| string> | Hue rotation angle of the component.<br>Default value: **'0deg'**<br>Value range: (-∞, +∞)<br>For the string type, the value must be a numeric string.<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'**.<br>If **sepia** is **undefined**, the component reverts to its original effect with no hue rotation.| | 335 336## colorBlend<sup>7+</sup> 337 338colorBlend(value: Color | string | Resource) 339 340Applies a color blend effect to the component. 341 342**System capability**: SystemCapability.ArkUI.ArkUI.Full 343 344**Atomic service API**: This API can be used in atomic services since API version 11. 345 346**Widget capability**: This API can be used in ArkTS widgets since API version 9. 347 348**Parameters** 349 350| Name| Type | Mandatory| Description | 351| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------- | 352| value | [Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource) | Yes | Color to blend with the component.| 353 354## colorBlend<sup>18+</sup> 355 356colorBlend(color: Optional\<Color | string | Resource>) 357 358Applies a color blend effect to the component. Compared to [colorBlend<sup>7+</sup>](#colorblend7), this API supports the **undefined** type for the **color** parameter. 359 360**System capability**: SystemCapability.ArkUI.ArkUI.Full 361 362**Atomic service API**: This API can be used in atomic services since API version 18. 363 364**Widget capability**: This API can be used in ArkTS widgets since API version 18. 365 366**Parameters** 367 368| Name| Type | Mandatory| Description | 369| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 370| color | Optional\<[Color](ts-appendix-enums.md#color) \| string \| [Resource](ts-types.md#resource)> | Yes | Color to blend with the component.<br>If **color** is **undefined**, the component reverts to its original effect with no color blending.| 371 372## linearGradientBlur<sup>12+</sup> 373 374linearGradientBlur(value: number, options: LinearGradientBlurOptions) 375 376Applies a linear gradient foreground blur effect to the component. 377 378**Atomic service API**: This API can be used in atomic services since API version 12. 379 380**System capability**: SystemCapability.ArkUI.ArkUI.Full 381 382**Parameters** 383 384| Name | Type | Mandatory| Description | 385| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 386| 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**.| 387| options | [LinearGradientBlurOptions](#lineargradientbluroptions12) | Yes | Linear gradient blur effect. | 388 389## linearGradientBlur<sup>18+</sup> 390 391linearGradientBlur(value: Optional\<number>, options: Optional\<LinearGradientBlurOptions>) 392 393Applies a linear gradient foreground blur effect to the component. Compared to [linearGradientBlur<sup>12+</sup>](#lineargradientblur12), this API supports the **undefined** type for the **value** parameter. 394 395**Atomic service API**: This API can be used in atomic services since API version 18. 396 397**System capability**: SystemCapability.ArkUI.ArkUI.Full 398 399**Parameters** 400 401| Name | Type | Mandatory| Description | 402| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 403| value | Optional\<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**.<br>If **color** is **undefined**, the gradient blur effect reverts to **0**.| 404| options | Optional\<[LinearGradientBlurOptions](#lineargradientbluroptions12)> | Yes | Linear gradient blur effect.<br>If **options** is **undefined**, the gradient blur effect reverts to **0**.| 405 406## renderGroup<sup>10+</sup> 407 408renderGroup(value: boolean) 409 410Sets whether the component and its child components are rendered off the screen as a whole before being blended with its parent. 411 412**Atomic service API**: This API can be used in atomic services since API version 11. 413 414**System capability**: SystemCapability.ArkUI.ArkUI.Full 415 416**Parameters** 417 418| Name| Type | Mandatory| Description | 419| ------ | ------- | ---- | ------------------------------------------------------------ | 420| 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**<br> The value **true** means the component and its child components are rendered off the screen as a whole, and **false** means the opposite.| 421 422## renderGroup<sup>18+</sup> 423 424renderGroup(isGroup: Optional\<boolean>) 425 426Sets whether the component and its child components are rendered off the screen as a whole before being blended with its parent. Compared to [renderGroup<sup>10+</sup>](#rendergroup10), this API supports the **undefined** type for the **isGroup** parameter. 427 428**Atomic service API**: This API can be used in atomic services since API version 18. 429 430**System capability**: SystemCapability.ArkUI.ArkUI.Full 431 432**Parameters** 433 434| Name | Type | Mandatory| Description | 435| ------- | ------------------ | ---- | ------------------------------------------------------------ | 436| isGroup | Optional\<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**<br>If **isGroup** is **undefined**, the component reverts to its original effect of not enabling offscreen rendering as a whole before blending with the parent component.| 437 438## blendMode<sup>11+</sup> 439 440blendMode(value: BlendMode, type?: BlendApplyType) 441 442Defines 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. 443 444**Widget capability**: This API can be used in ArkTS widgets since API version 11. 445 446**Atomic service API**: This API can be used in atomic services since API version 12. 447 448**System capability**: SystemCapability.ArkUI.ArkUI.Full 449 450**Parameters** 451 452| Name| Type | Mandatory| Description | 453| ------ | ----------------------------------- | ---- | ------------------------------------------------------------ | 454| value | [BlendMode](#blendmode11) | Yes | Blend mode.<br>Default value: **BlendMode.NONE**<br>**NOTE**<br>When **BlendMode.NONE** is used, the blend effect is **BlendMode.SRC_OVER** by default, and **BlendApplyType** does not take effect.| 455| 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).| 456 457## blendMode<sup>18+</sup> 458 459blendMode(mode: Optional\<BlendMode>, type?: BlendApplyType) 460 461Defines 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. Compared to [blendMode<sup>11+</sup>](#blendmode11), this API supports the **undefined** type for the **mode** parameter. 462 463**Widget capability**: This API can be used in ArkTS widgets since API version 18. 464 465**Atomic service API**: This API can be used in atomic services since API version 18. 466 467**System capability**: SystemCapability.ArkUI.ArkUI.Full 468 469**Parameters** 470 471| Name| Type | Mandatory| Description | 472| ------ | ------------------------------- | ---- | ------------------------------------------------------------ | 473| mode | Optional\<[BlendMode](#blendmode11)> | Yes | Blend mode.<br>Default value: **BlendMode.NONE**<br>If **mode** is **undefined**, the component reverts to its original effect of not enabling offscreen rendering as a whole before blending with the parent component.<br>**NOTE**<br>When **BlendMode.NONE** is used, the blend effect is **BlendMode.SRC_OVER** by default, and **BlendApplyType** does not take effect.| 474| 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).| 475 476## BlendApplyType<sup>11+</sup> 477 478Defines how to apply the specified blend mode to the content of a view. 479 480**Widget capability**: This API can be used in ArkTS widgets since API version 11. 481 482**Atomic service API**: This API can be used in atomic services since API version 12. 483 484**System capability**: SystemCapability.ArkUI.ArkUI.Full 485 486| Name | Description | 487| ---------------| ---------------------------------------------------------------- | 488| FAST | The content of the view is blended in sequence on the target image. | 489| 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. | 490 491## useShadowBatching<sup>11+</sup> 492 493useShadowBatching(value: boolean) 494 495Sets 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. 496 497**Atomic service API**: This API can be used in atomic services since API version 12. 498 499**System capability**: SystemCapability.ArkUI.ArkUI.Full 500 501**Widget capability**: This API can be used in ArkTS widgets since API version 11. 502 503**Parameters** 504 505| Name| Type | Mandatory| Description | 506| ------ | ------- | ---- | ------------------------------------------------------------ | 507| 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.| 508 509## useShadowBatching<sup>18+</sup> 510 511useShadowBatching(use: Optional\<boolean>) 512 513Sets 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. Compared to [useShadowBatching<sup>11+</sup>](#useshadowbatching11), this API supports the **undefined** type for the **use** parameter. 514 515**Atomic service API**: This API can be used in atomic services since API version 18. 516 517**System capability**: SystemCapability.ArkUI.ArkUI.Full 518 519**Widget capability**: This API can be used in ArkTS widgets since API version 18. 520 521**Parameters** 522 523| Name| Type | Mandatory| Description | 524| ------ | ------------------ | ---- | ------------------------------------------------------------ | 525| use | Optional\<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.<br>If **use** is **undefined**, the component reverts to its original effect of not using shadow overlapping.| 526 527## sphericalEffect<sup>12+</sup> 528 529sphericalEffect(value: number) 530 531Applies a spherical effect to the component. 532 533**Atomic service API**: This API can be used in atomic services since API version 12. 534 535**System capability**: SystemCapability.ArkUI.ArkUI.Full 536 537**Parameters** 538 539| Name| Type | Mandatory| Description | 540| ------ | ------ | ---- | ------------------------------------------------------------ | 541| 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**.| 542 543## sphericalEffect<sup>18+</sup> 544 545sphericalEffect(effect: Optional\<number>) 546 547Applies a spherical effect to the component. Compared to [sphericalEffect<sup>12+</sup>](#sphericaleffect12), this API supports the **undefined** type for the **effect** parameter. 548 549**Atomic service API**: This API can be used in atomic services since API version 18. 550 551**System capability**: SystemCapability.ArkUI.ArkUI.Full 552 553**Parameters** 554 555| Name| Type | Mandatory| Description | 556| ------ | ----------------- | ---- | ------------------------------------------------------------ | 557| effect | Optional\<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**.<br>If **effect** is **undefined**, the spherical degree reverts to **0**.| 558 559## lightUpEffect<sup>12+</sup> 560 561lightUpEffect(value: number) 562 563Applies a light up effect to the component. 564 565**Atomic service API**: This API can be used in atomic services since API version 12. 566 567**System capability**: SystemCapability.ArkUI.ArkUI.Full 568 569**Parameters** 570 571| Name| Type | Mandatory| Description | 572| ------ | ------ | ---- | ------------------------------------------------------------ | 573| 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**.| 574 575## lightUpEffect<sup>18+</sup> 576 577lightUpEffect(degree: Optional\<number>) 578 579Applies a light up effect to the component. Compared to [lightUpEffect<sup>12+</sup>](#lightupeffect12), this API supports the **undefined** type for the **degree** parameter. 580 581**Atomic service API**: This API can be used in atomic services since API version 18. 582 583**System capability**: SystemCapability.ArkUI.ArkUI.Full 584 585**Parameters** 586 587| Name| Type | Mandatory| Description | 588| ------ | ----------------- | ---- | ------------------------------------------------------------ | 589| degree | Optional\<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**.<br>If **degree** is **undefined**, the light up degree reverts to **1**.| 590 591## pixelStretchEffect<sup>12+</sup> 592 593pixelStretchEffect(options: PixelStretchEffectOptions) 594 595Applies a pixel stretch effect to the component. 596 597**Atomic service API**: This API can be used in atomic services since API version 12. 598 599**System capability**: SystemCapability.ArkUI.ArkUI.Full 600 601**Parameters** 602 603| Name | Type | Mandatory| Description | 604| ------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 605| 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.| 606 607## pixelStretchEffect<sup>18+</sup> 608 609pixelStretchEffect(options: Optional\<PixelStretchEffectOptions>) 610 611Applies a pixel stretch effect to the component. Compared to [pixelStretchEffect<sup>12+</sup>](#pixelstretcheffect12), this API supports the **undefined** type for the **options** parameter. 612 613**Atomic service API**: This API can be used in atomic services since API version 18. 614 615**System capability**: SystemCapability.ArkUI.ArkUI.Full 616 617**Parameters** 618 619| Name | Type | Mandatory| Description | 620| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 621| options | Optional\<[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.<br>If **options** is **undefined**, the component reverts to its original effect with no pixel stretch.| 622 623## PixelStretchEffectOptions<sup>10+</sup> 624 625Describes the pixel stretch effect options. 626 627**Atomic service API**: This API can be used in atomic services since API version 11. 628 629**System capability**: SystemCapability.ArkUI.ArkUI.Full 630 631| Name | Type | Mandatory | Description | 632| ------ | ----------------- | ---- | -------------- | 633| left | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the left edge of the image.| 634| right | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the right edge of the image.| 635| top | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the top edge of the image.| 636| bottom | [Length](ts-types.md#length) | No | Length by which a pixel is stretched towards the right edge of the image.| 637 638## systemBarEffect<sup>12+</sup> 639 640systemBarEffect() 641 642Applies a system bar effect to the component, which means to invert colors based on the background and add a blur. 643 644**Atomic service API**: This API can be used in atomic services since API version 12. 645 646**System capability**: SystemCapability.ArkUI.ArkUI.Full 647 648## ShadowType<sup>10+<sup> 649 650Shadow type. 651 652**Atomic service API**: This API can be used in atomic services since API version 11. 653 654**System capability**: SystemCapability.ArkUI.ArkUI.Full 655 656| Name | Description | 657| -------- | ---------------------------------------- | 658| COLOR | Color. | 659| BLUR | Blur. | 660 661 662## ShadowOptions 663 664Provides the shadow attributes, including the blur radius, color, and offset along the x-axis and y-axis. 665 666 667**System capability**: SystemCapability.ArkUI.ArkUI.Full 668 669**Widget capability**: This API can be used in ArkTS widgets since API version 9. 670 671| Name | Type | Mandatory | Description | 672| ------- | ---------------------------------------- | ---- | ---------------------------------------- | 673| 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.| 674| 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. | 675| 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.| 676| 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.| 677| 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.| 678| fill<sup>11+</sup> | boolean | No | Whether to fill the inside of the component with shadow. **true**: Fill the inside of the component with shadow.<br>**false**: Do not 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.| 679 680## ShadowStyle<sup>10+</sup> 681 682**Atomic service API**: This API can be used in atomic services since API version 11. 683 684| Name | Description | 685| ----------------- | ------ | 686| OUTER_DEFAULT_XS | Mini shadow. | 687| OUTER_DEFAULT_SM | Small shadow. | 688| OUTER_DEFAULT_MD | Medium shadow. | 689| OUTER_DEFAULT_LG | Large shadow. | 690| OUTER_FLOATING_SM | Floating small shadow.| 691| OUTER_FLOATING_MD | Floating medium shadow.| 692 693## BlendMode<sup>11+</sup> 694 695> **NOTE** 696> 697> 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. 698 699**Widget capability**: This API can be used in ArkTS widgets since API version 11. 700 701**Atomic service API**: This API can be used in atomic services since API version 12. 702 703| Name | Description | 704| ---------------| ------ | 705| NONE | The top image is superimposed on the bottom image without any blending. | 706| CLEAR | The target pixels covered by the source pixels are erased by being turned to completely transparent. | 707| SRC | r = s: Only the source pixels are displayed. | 708| DST | r = d: Only the target pixels are displayed. | 709| SRC_OVER | r = s + (1 - sa) * d: The source pixels are blended based on opacity and cover the target pixels. | 710| DST_OVER | r = d + (1 - da) * s: The target pixels are blended based on opacity and cover on the source pixels. | 711| SRC_IN | r = s * da: Only the part of the source pixels that overlap with the target pixels is displayed. | 712| DST_IN | r = d * sa: Only the part of the target pixels that overlap with the source pixels is displayed. | 713| SRC_OUT | r = s * (1 - da): Only the part of the source pixels that do not overlap with the target pixels is displayed. | 714| DST_OUT | r = d * (1 - sa): Only the part of the target pixels that do not overlap with the source pixels is displayed. | 715| 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. | 716| 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. | 717| XOR | r = s * (1 - da) + d * (1 - sa): Only the non-overlapping part between the source pixels and the target pixels is displayed. | 718| PLUS | r = min(s + d, 1): New pixels resulting from adding the source pixels to the target pixels are displayed. | 719| MODULATE | r = s * d: New pixels resulting from multiplying the source pixels with the target pixels are displayed. | 720| 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. | 721| OVERLAY | The MULTIPLY or SCREEN mode is used based on the target pixels. | 722| DARKEN | rc = s + d - max(s * da, d * sa), ra = kSrcOver: When two colors overlap, whichever is darker is used. | 723| LIGHTEN | rc = s + d - min(s * da, d * sa), ra = kSrcOver: The darker of the pixels (source and target) is used. | 724| COLOR_DODGE | The colors of the target pixels are lightened to reflect the source pixels. | 725| COLOR_BURN | The colors of the target pixels are darkened to reflect the source pixels. | 726| HARD_LIGHT | The MULTIPLY or SCREEN mode is used, depending on the source pixels. | 727| SOFT_LIGHT | The LIGHTEN or DARKEN mode is used, depending on the source pixels. | 728| 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. | 729| EXCLUSION | rc = s + d - two(s * d), ra = kSrcOver: The final pixel is similar to <b>DIFFERENCE</b>, but with less contrast. | 730| 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. | 731| HUE | The resultant image is created with the luminance and saturation of the source image and the hue of the target image. | 732| SATURATION | The resultant image is created with the luminance and hue of the target image and the saturation of the source image. | 733| COLOR | The resultant image is created with the saturation and hue of the source image and the luminance of the target image. | 734| LUMINOSITY | The resultant image is created with the saturation and hue of the target image and the luminance of the source image. | 735 736## LinearGradientBlurOptions<sup>12+</sup> 737 738**Atomic service API**: This API can be used in atomic services since API version 12. 739 740| Name | Type | Mandatory | Description | 741| ------------- | ----------------------------------------------------------- | ----- | ------------------------------------------------------------ | 742| 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.| 743| direction | [GradientDirection](ts-appendix-enums.md#gradientdirection) | Yes | Gradient blur direction.<br>Default value:<br>GradientDirection.Bottom | 744 745## FractionStop<sup>12+</sup> 746 747FractionStop = [ number, number ] 748 749Defines a gradient blur stop. 750 751**Atomic service API**: This API can be used in atomic services since API version 12. 752 753**System capability**: SystemCapability.ArkUI.ArkUI.Full 754 755| Value Range | Description | 756| ------------- | ---------------------------------------------------------- | 757| number | Blur degree, represented by a fraction. The value **1** means opaque, and **0** means completely transparent.<br>Value range: [0, 1] | 758| number | Stop position. The value **1** indicates the end position and **0** the end position.<br> Value range: [0, 1]| 759 760## InvertOptions<sup>11+</sup> 761 762Describes the options for inverting the foreground color. 763 764**Atomic service API**: This API can be used in atomic services since API version 12. 765 766| Name | Type | Mandatory | Description | 767| -------------- | ------ | ----- | ------------------------------------------ | 768| low | number | Yes | Value when the background color is greater than the grayscale threshold.<br>Value range: [0, 1] | 769| high | number | Yes | Value when the background color is less than the grayscale threshold.<br>Value range: [0, 1] | 770| threshold | number | Yes | Grayscale threshold.<br>Value range: [0, 1] | 771| thresholdRange | number | Yes | Threshold value range.<br>Value range: [0, 1]<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.| 772 773## BackgroundImageOptions<sup>18+</sup> 774 775Defines the background image options. 776 777**Atomic service API**: This API can be used in atomic services since API version 18. 778 779**System capability**: SystemCapability.ArkUI.ArkUI.Full 780 781| Name | Type | Mandatory | Description | 782| -------------- | ------------------------------------------------| ----- | --------------------------------------------------------| 783| syncLoad | boolean | No | Whether to load the background image synchronously.<br>Default value: **false**<br>**true**: Load the background image synchronously.<br>**false**: Load the background image asynchronously. | 784| repeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | No | Repeat pattern of the background image. | 785 786## freeze<sup>12+</sup> 787 788freeze(value: boolean) 789 790Sets whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. 791 792**Atomic service API**: This API can be used in atomic services since API version 12. 793 794**System capability**: SystemCapability.ArkUI.ArkUI.Full 795 796**Parameters** 797 798| Name| Type | Mandatory| Description | 799| ------ | ------- | ---- | ------------------------------------------------------------ | 800| value | boolean | Yes | Whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. If the opacity of the component is not 1, the drawing effect may vary depending on the value.<br>Default value: **false**<br> **true**: Freeze the component.<br>**false**: Do not freeze the component.| 801 802## freeze<sup>18+</sup> 803 804freeze(freeze: Optional\<boolean>) 805 806Sets whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. Compared to [freeze](#freeze12), this API supports the **undefined** type for the **freeze** parameter. 807 808**Atomic service API**: This API can be used in atomic services since API version 18. 809 810**System capability**: SystemCapability.ArkUI.ArkUI.Full 811 812**Parameters** 813 814| Name| Type | Mandatory| Description | 815| ------ | ------------------ | ---- | ------------------------------------------------------------ | 816| freeze | Optional\<boolean> | Yes | Whether to freeze the component. When frozen, the component and its children are cached for repeated drawing after offscreen rendering, without updating internal attributes. If the opacity of the component is not 1, the drawing effect may vary depending on the value.<br>Default value: **false**<br> **true**: Freeze the component.<br>**false**: Do not freeze the component.<br>If **freeze** is set to **undefined**, the previous value is retained.| 817 818## Example 819 820### Example 1: Setting Different Image Attributes 821This example applies different image effects. 822```ts 823// xxx.ets 824@Entry 825@Component 826struct ImageEffectsExample { 827 build() { 828 Column({ space: 5 }) { 829 // Apply the shadow effect. 830 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 831 Image($r('app.media.image')) 832 .width('90%') 833 .height(30) 834 .shadow({ 835 radius: 10, 836 color: Color.Green, 837 offsetX: 20, 838 offsetY: 20 839 }) 840 841 // Add the internal shadow effect. 842 Text('shadow').fontSize(15).fontColor(0xCCCCCC).width('90%') 843 Image($r('app.media.image')) 844 .width('90%') 845 .height(30) 846 .shadow({ 847 radius: 5, 848 color: Color.Green, 849 offsetX: 20, 850 offsetY: 20, 851 fill: true 852 }).opacity(0.5) 853 854 // 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. 855 Text('grayscale').fontSize(15).fontColor(0xCCCCCC).width('90%') 856 Image($r('app.media.image')).width('90%').height(30).grayscale(0.3) 857 Image($r('app.media.image')).width('90%').height(30).grayscale(0.8) 858 859 // 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. 860 Text('brightness').fontSize(15).fontColor(0xCCCCCC).width('90%') 861 Image($r('app.media.image')).width('90%').height(30).brightness(1.2) 862 863 // Apply the saturation effect. If the value is 1, the source image is displayed. 864 Text('saturate').fontSize(15).fontColor(0xCCCCCC).width('90%') 865 Image($r('app.media.image')).width('90%').height(30).saturate(2.0) 866 Image($r('app.media.image')).width('90%').height(30).saturate(0.7) 867 868 // 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. 869 Text('contrast').fontSize(15).fontColor(0xCCCCCC).width('90%') 870 Image($r('app.media.image')).width('90%').height(30).contrast(2.0) 871 Image($r('app.media.image')).width('90%').height(30).contrast(0.8) 872 873 // Invert the image. 874 Text('invert').fontSize(15).fontColor(0xCCCCCC).width('90%') 875 Image($r('app.media.image')).width('90%').height(30).invert(0.2) 876 Image($r('app.media.image')).width('90%').height(30).invert(0.8) 877 878 // Apply the color blend effect. 879 Text('colorBlend').fontSize(15).fontColor(0xCCCCCC).width('90%') 880 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Green) 881 Image($r('app.media.image')).width('90%').height(30).colorBlend(Color.Blue) 882 883 // Convert the image color to sepia. 884 Text('sepia').fontSize(15).fontColor(0xCCCCCC).width('90%') 885 Image($r('app.media.image')).width('90%').height(30).sepia(0.8) 886 887 // Apply the hue rotation effect. 888 Text('hueRotate').fontSize(15).fontColor(0xCCCCCC).width('90%') 889 Image($r('app.media.image')).width('90%').height(30).hueRotate(90) 890 }.width('100%').margin({ top: 5 }) 891 } 892} 893``` 894 895 896 897 898### Example 2: Applying a Linear Gradient Blur Effect 899 900This example demonstrates how to apply a linear gradient blur effect on a component using **linearGradientBlur**. 901 902```ts 903// xxx.ets 904@Entry 905@Component 906struct ImageExample1 { 907 private_resource1: Resource = $r('app.media.testlinearGradientBlurOrigin') 908 @State image_src: Resource = this.private_resource1 909 910 build() { 911 Column() { 912 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) { 913 Row({ space: 5 }) { 914 Image(this.image_src) 915 .linearGradientBlur(60, 916 { fractionStops: [[0, 0], [0, 0.33], [1, 0.66], [1, 1]], direction: GradientDirection.Bottom }) 917 } 918 } 919 } 920 } 921} 922``` 923 924 925 926### Example 3: Setting Offscreen Rendering Effect 927 928This example demonstrates how to use **renderGroup** to set whether to render a component offscreen before blending it with its parent component. 929 930```ts 931// xxx.ets 932@Component 933struct Component1 { 934 @Prop renderGroupValue: boolean; 935 936 build() { 937 Row() { 938 Row() { 939 Row() 940 .backgroundColor(Color.Black) 941 .width(100) 942 .height(100) 943 .opacity(1) 944 } 945 .backgroundColor(Color.White) 946 .width(150) 947 .height(150) 948 .justifyContent(FlexAlign.Center) 949 .opacity(0.6) 950 .renderGroup(this.renderGroupValue) 951 } 952 .backgroundColor(Color.Black) 953 .width(200) 954 .height(200) 955 .justifyContent(FlexAlign.Center) 956 .opacity(1) 957 } 958} 959 960@Entry 961@Component 962struct RenderGroupExample { 963 build() { 964 Column() { 965 Component1({ renderGroupValue: true }) 966 .margin(20) 967 Component1({ renderGroupValue: false }) 968 .margin(20) 969 } 970 .width("100%") 971 .height("100%") 972 .alignItems(HorizontalAlign.Center) 973 } 974} 975``` 976 977 978 979### Example 4: Blending the Current Component Content with Canvas Content 980 981This example demonstrates how to blend the current component content with the canvas content below using **blendMode**. 982 983```ts 984// xxx.ets 985@Entry 986@Component 987struct Index { 988 build() { 989 Column() { 990 Text("blendMode") 991 .fontSize(20) 992 .fontWeight(FontWeight.Bold) 993 .fontColor('#ffff0101') 994 Row() { 995 Circle() 996 .width(200) 997 .height(200) 998 .fill(Color.Green) 999 .position({ x: 50, y: 50 }) 1000 Circle() 1001 .width(200) 1002 .height(200) 1003 .fill(Color.Blue) 1004 .position({ x: 150, y: 50 }) 1005 } 1006 .blendMode(BlendMode.OVERLAY, BlendApplyType.OFFSCREEN) 1007 .alignItems(VerticalAlign.Center) 1008 .height(300) 1009 .width('100%') 1010 } 1011 .height('100%') 1012 .width('100%') 1013 .backgroundImage($r('app.media.image')) 1014 .backgroundImageSize(ImageSize.Cover) 1015 } 1016} 1017``` 1018 1019<br>BlendMode.OVERLAY,BlendApplyType.OFFSCREEN<br> 1020 1021<br>**blendMode** can be used with offscreen rendering to produce different effects. 1022 1023### Example 5: Inverting the Foreground Color 1024 1025This example demonstrates how to invert the foreground color using **InvertOptions**. 1026 1027```ts 1028// xxx.ets 1029@Entry 1030@Component 1031struct Index { 1032 build() { 1033 Stack() { 1034 Column() 1035 Stack() { 1036 Image($r('app.media.r')).width('100%') 1037 Column() { 1038 Column().width("100%").height(30).invert({ 1039 low: 0, 1040 high: 1, 1041 threshold: 0.5, 1042 thresholdRange: 0.2 1043 }) 1044 Column().width("100%").height(30).invert({ 1045 low: 0.2, 1046 high: 0.5, 1047 threshold: 0.3, 1048 thresholdRange: 0.2 1049 }) 1050 } 1051 } 1052 .width('100%') 1053 .height('100%') 1054 } 1055 } 1056} 1057``` 1058 1059 1060 1061### Example 6: Setting Non-Overlapping Same-Layer Shadows 1062 1063This example demonstrates how to implement non-overlapping shadows at the same layer using **useShadowBatching** with **shadow**. 1064 1065```ts 1066// xxx.ets 1067@Entry 1068@Component 1069struct UseShadowBatchingExample { 1070 build() { 1071 Column() { 1072 Column({ space: 10 }) { 1073 Stack() { 1074 1075 } 1076 .width('90%') 1077 .height(50) 1078 .margin({ top: 5 }) 1079 .backgroundColor(0xFFE4C4) 1080 .shadow({ 1081 radius: 120, 1082 color: Color.Green, 1083 offsetX: 0, 1084 offsetY: 0 1085 }) 1086 .align(Alignment.TopStart) 1087 .shadow({ 1088 radius: 120, 1089 color: Color.Green, 1090 offsetX: 0, 1091 offsetY: 0 1092 }) 1093 1094 Stack() { 1095 1096 } 1097 .width('90%') 1098 .height(50) 1099 .margin({ top: 5 }) 1100 .backgroundColor(0xFFE4C4) 1101 .align(Alignment.TopStart) 1102 .shadow({ 1103 radius: 120, 1104 color: Color.Red, 1105 offsetX: 0, 1106 offsetY: 0 1107 }) 1108 .width('90%') 1109 .backgroundColor(Color.White) 1110 1111 Column() { 1112 Text() 1113 .fontWeight(FontWeight.Bold) 1114 .fontSize(20) 1115 .fontColor(Color.White) 1116 } 1117 .justifyContent(FlexAlign.Center) 1118 .width(150) 1119 .height(150) 1120 .borderRadius(10) 1121 .backgroundColor(0xf56c6c) 1122 .shadow({ 1123 radius: 300, 1124 color: Color.Yellow, 1125 offsetX: 0, 1126 offsetY: 0 1127 }) 1128 1129 Column() { 1130 Text() 1131 .fontWeight(FontWeight.Bold) 1132 .fontSize(20) 1133 .fontColor(Color.White) 1134 } 1135 .justifyContent(FlexAlign.Center) 1136 .width(150) 1137 .height(150) 1138 .backgroundColor(0x67C23A) 1139 .borderRadius(10) 1140 .translate({ y: -50 }) 1141 .shadow({ 1142 radius: 220, 1143 color: Color.Blue, 1144 offsetX: 0, 1145 offsetY: 0 1146 }) 1147 } 1148 .useShadowBatching(true) 1149 } 1150 .width('100%').margin({ top: 5 }) 1151 } 1152} 1153``` 1154 1155 1156 1157### Example 7: Applying a Spherical Effect to a Component 1158 1159This example demonstrates how to apply a spherical effect to a component using **sphericalEffect**. 1160 1161```ts 1162// xxx.ets 1163@Entry 1164@Component 1165struct SphericalEffectExample { 1166 build() { 1167 Stack() { 1168 TextInput({ placeholder: "Enter a percentage." }) 1169 .width('50%') 1170 .height(35) 1171 .type(InputType.Number) 1172 .enterKeyType(EnterKeyType.Done) 1173 .caretColor(Color.Red) 1174 .placeholderColor(Color.Blue) 1175 .placeholderFont({ 1176 size: 20, 1177 style: FontStyle.Italic, 1178 weight: FontWeight.Bold 1179 }) 1180 .sphericalEffect(0.5) 1181 }.alignContent(Alignment.Center).width("100%").height("100%") 1182 } 1183} 1184``` 1185 1186Below is how the component looks with the spherical effect applied. 1187 1188 1189 1190Below is how the component looks without the spherical effect applied. 1191 1192 1193 1194### Example 8: Applying a Light Up Effect to a Component 1195 1196This example demonstrates how to apply a light up effect to a component using **lightUpEffect**. 1197 1198```ts 1199// xxx.ets 1200@Entry 1201@Component 1202struct LightUpExample { 1203 build() { 1204 Stack() { 1205 Text('This is the text content with letterSpacing 0.') 1206 .letterSpacing(0) 1207 .fontSize(12) 1208 .border({ width: 1 }) 1209 .padding(10) 1210 .width('50%') 1211 .lightUpEffect(0.6) 1212 }.alignContent(Alignment.Center).width("100%").height("100%") 1213 } 1214} 1215 1216``` 1217 1218Below is how the component looks with the light up effect applied. 1219 1220 1221 1222Below is how the component looks with **lightUpEffect** set to **0.2**: 1223 1224 1225 1226Below is how the component looks without the light up effect applied. 1227 1228 1229 1230### Example 9: Applying a Pixel Stretch Effect to a Component 1231 1232This example demonstrates how to apply a pixel stretch effect to a component using **pixelStretchEffect**. 1233 1234```ts 1235// xxx.ets 1236@Entry 1237@Component 1238struct PixelStretchExample { 1239 build() { 1240 Stack() { 1241 Text('This is the text content with letterSpacing 0.') 1242 .letterSpacing(0) 1243 .fontSize(12) 1244 .border({ width: 1 }) 1245 .padding(10) 1246 .clip(false) 1247 .width('50%') 1248 .pixelStretchEffect({ 1249 top: 10, 1250 left: 10, 1251 right: 10, 1252 bottom: 10 1253 }) 1254 }.alignContent(Alignment.Center).width("100%").height("100%") 1255 } 1256} 1257``` 1258 1259Below is how the component looks with the pixel stretch effect applied. 1260 1261 1262 1263Below is how the component looks without the pixel stretch effect applied. 1264 1265 1266 1267 1268### Example 10: Applying a System Bar Effect to a Component 1269 1270This example demonstrates how to apply a system bar effect to a component using **systemBarEffect**. 1271 1272```ts 1273// xxx.ets 1274@Entry 1275@Component 1276struct Index { 1277 build() { 1278 Column() { 1279 Stack() { 1280 Image($r('app.media.testImage')).width('100%').height('100%') 1281 Column() 1282 .width(150) 1283 .height(10) 1284 .systemBarEffect() 1285 .border({ radius: 5 }) 1286 .margin({ bottom: 80 }) 1287 }.alignContent(Alignment.Center) 1288 } 1289 } 1290} 1291``` 1292 1293Below is how the component looks with the system bar effect applied. 1294 1295 1296
