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