1# Foreground Blur 2 3You can apply foreground blur effects to a component. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version. 8 9## foregroundBlurStyle 10 11foregroundBlurStyle(value: BlurStyle, options?: ForegroundBlurStyleOptions): T 12 13Applies a foreground blur style to the component. 14 15**Atomic service API**: This API can be used in atomic services since API version 11. 16 17**System capability**: SystemCapability.ArkUI.ArkUI.Full 18 19**Parameters** 20 21| Name | Type | Mandatory| Description | 22| ------- | ------------------------------------------------------------ | ---- | ------------------------ | 23| value | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | Yes | Settings of the foreground blur style. | 24| options | [ForegroundBlurStyleOptions](#foregroundblurstyleoptions) | No | Foreground blur options.| 25 26**Return value** 27 28| Type | Description | 29| ------ | ------------------------ | 30| T | Current component.| 31 32## foregroundBlurStyle<sup>18+</sup> 33 34foregroundBlurStyle(style: Optional\<BlurStyle>, options?: ForegroundBlurStyleOptions): T 35 36Applies a foreground blur style to the component. Compared with [foregroundBlurStyle](#foregroundblurstyle), this API supports the **undefined** type for the **style** parameter. 37 38**Atomic service API**: This API can be used in atomic services since API version 18. 39 40**System capability**: SystemCapability.ArkUI.ArkUI.Full 41 42**Parameters** 43 44| Name | Type | Mandatory| Description | 45| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 46| style | Optional\<[BlurStyle](ts-universal-attributes-background.md#blurstyle9)> | Yes | Settings of the foreground blur style.<br>If **style** is set to **undefined**, no blur is applied.| 47| options | [ForegroundBlurStyleOptions](#foregroundblurstyleoptions) | No | Foreground blur options. | 48 49**Return value** 50 51| Type | Description | 52| ------ | ------------------------ | 53| T | Current component.| 54 55## foregroundBlurStyle<sup>19+</sup> 56 57foregroundBlurStyle(style: Optional\<BlurStyle>, options?: ForegroundBlurStyleOptions, sysOptions?: SystemAdaptiveOptions): T 58 59Applies a foreground blur style to the component. Compared with [foregroundBlurStyle<sup>18+</sup>](#foregroundblurstyle18), this API adds the **sysOptions** parameter, which allows for system adaptive adjustments. 60 61**Atomic service API**: This API can be used in atomic services since API version 19. 62 63**System capability**: SystemCapability.ArkUI.ArkUI.Full 64 65**Parameters** 66 67| Name | Type | Mandatory| Description | 68| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 69| style | Optional\<[BlurStyle](ts-universal-attributes-background.md#blurstyle9)> | Yes | Settings of the foreground blur style.<br>If **style** is set to **undefined**, no blur is applied.| 70| options | [ForegroundBlurStyleOptions](#foregroundblurstyleoptions) | No | Foreground blur options. | 71| sysOptions | [SystemAdaptiveOptions](ts-universal-attributes-background.md#systemadaptiveoptions19) | No | System adaptive adjustment options.<br>Default value: **{ disableSystemAdaptation: false }** | 72 73**Return value** 74 75| Type | Description | 76| ------ | ------------------------ | 77| T | Current component.| 78 79> **NOTE** 80> 81> **foregroundBlurStyle** is a real-time blurring API that performs rendering frame by frame, which incurs significant performance overhead. When both the blur content and blur radius remain unchanged, it is recommended that you use the static blur API [blur](../../apis-arkgraphics2d/js-apis-effectKit.md#blur). For best practices, see [Image Blurring Optimization – When to Use](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-fuzzy-scene-performance-optimization#section4945532519). 82 83## ForegroundBlurStyleOptions 84Inherited from [BlurStyleOptions](#blurstyleoptions). 85 86**Atomic service API**: This API can be used in atomic services since API version 12. 87 88## BlurStyleOptions 89 90Defines the background blur options. 91 92| Name | Type | Mandatory| Description | 93| --------------------------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 94| colorMode | [ThemeColorMode](ts-container-with-theme.md#themecolormode10) | No | Color mode used for the foreground blur.<br>Default value: **ThemeColorMode.SYSTEM**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 95| adaptiveColor | [AdaptiveColor](#adaptivecolor10) | No | Adaptive color mode.<br>Default value: **AdaptiveColor.DEFAULT**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 96| blurOptions<sup>11+</sup> | [BlurOptions](#bluroptions11) | No | Grayscale blur parameters.<br>Default value: **grayscale: [0,0]**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 97| scale<sup>12+</sup> | number | No | Foreground blur scale.<br>Default value: **1.0**<br>Value range: [0.0, 1.0]<br>**1.0** indicates the highest blur degree.<br>**0.0** indicates the lowest blur degree.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 98 99## AdaptiveColor<sup>10+</sup> 100 101Enumerates the adaptive color modes used for the background blur effect. 102 103**Atomic service API**: This API can be used in atomic services since API version 11. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107| Name | Description | 108| ------- | ------------------------- | 109| DEFAULT | Adaptive color mode is not used. The default color is used as the mask color. Using a mode other than **DEFAULT** can be more time-consuming. | 110| AVERAGE | Adaptive color mode is used. The average color value of the color picking area is used as the mask color.| 111 112## BlurOptions<sup>11+</sup> 113Grayscale blur parameters. 114 115**Atomic service API**: This API can be used in atomic services since API version 12. 116 117**System capability**: SystemCapability.ArkUI.ArkUI.Full 118 119| Name | Type | Mandatory| Description | 120| ---- | ---- | ---- | -------------------------- | 121| grayscale | [number, number] | Yes | Grayscale blur, with two parameters in the value range of [0, 127]. The color gradation of the black and white in the image is adjusted to create different shades of gray. The first parameter indicates the brightness of the black color, and the second parameter indicates the darkness of the white color. A larger value indicates a more obvious adjustment effect (the black and white colors become grayer). For example, if the value specified is (20,20), the RGB value [0, 0, 0] (black) is converted to [20, 20, 20], RGB value [255, 255, 255] (white) is converted to [235, 235, 235] (255-20), and the color pixels remain unchanged.| 122 123 124## Example 125 126This example demonstrates how to apply content blur to an image using **foregroundBlurStyle**. 127 128```ts 129// xxx.ets 130@Entry 131@Component 132struct ForegroundBlurStyleDemo { 133 build() { 134 Column() { 135 Text('Thin Material').fontSize(30).fontColor(0xCCCCCC) 136 Image($r('app.media.bg')) 137 .width(300) 138 .height(350) 139 .foregroundBlurStyle(BlurStyle.Thin, 140 { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 }) 141 } 142 .height('100%') 143 .width('100%') 144 } 145} 146``` 147 148 149
