1# Background 2 3You can set the background for a component. 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## background<sup>10+</sup> 10 11background(builder: CustomBuilder, options?: { align?: Alignment }) 12 13Sets the background color of 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| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Custom background. | 24| options | {align?:[Alignment](ts-appendix-enums.md#alignment)} | No | Alignment mode between the custom background and the component.<br>If **background**, **backgroundColor**, and **backgroundImage** are set at the same time, they will all take effect, with **background** at the top layer.| 25 26> **NOTE** 27> 28> The custom background takes some time to render, during which it cannot respond to events, or be dynamically updated. This attribute cannot be nested or be previewed in DevEco Studio Previewer. 29 30## backgroundColor 31 32backgroundColor(value: ResourceColor) 33 34Sets the background color of the component. 35 36**Widget capability**: This API can be used in ArkTS widgets since API version 9. 37 38**Atomic service API**: This API can be used in atomic services since API version 11. 39 40**System capability**: SystemCapability.ArkUI.ArkUI.Full 41 42**Parameters** 43 44| Name| Type | Mandatory| Description | 45| ------ | ------------------------------------------ | ---- | ------------------ | 46| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Background color of the component.| 47 48## backgroundColor<sup>18+</sup> 49 50backgroundColor(color: Optional\<ResourceColor>) 51 52Sets the background color of the component. Compared to [backgroundColor](#backgroundcolor), this API supports the **undefined** type for the **color** parameter. 53 54**Widget capability**: This API can be used in ArkTS widgets since API version 18. 55 56**Atomic service API**: This API can be used in atomic services since API version 18. 57 58**System capability**: SystemCapability.ArkUI.ArkUI.Full 59 60**Parameters** 61 62| Name| Type | Mandatory| Description | 63| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 64| color | Optional\<[ResourceColor](ts-types.md#resourcecolor)> | Yes | Background color of the component.<br>If **color** is **undefined**, the background color reverts to the default transparent color.| 65 66> **NOTE** 67> 68> If the background color is specified through **inactiveColor** in [backgroundBlurStyle](#backgroundblurstyle9), avoid setting the background color again using **backgroundColor**. 69 70## backgroundImage 71 72backgroundImage(src: ResourceStr | PixelMap, repeat?: ImageRepeat) 73 74Sets the background image of the component. 75 76**Widget capability**: This API can be used in ArkTS widgets since API version 9. 77 78**Atomic service API**: This API can be used in atomic services since API version 11. 79 80**System capability**: SystemCapability.ArkUI.ArkUI.Full 81 82**Parameters** 83 84| Name| Type | Mandatory| Description | 85| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 86| src | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap<sup>12+</sup>](../../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Image address, which can be the address of an online or local image, a Base64 encoded string, or a pixel map. SVG images are not supported.| 87| repeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | No | Whether the background image is repeated. By default, the background image is not repeated. If the set image has a transparent background and **backgroundColor** is set, the image is overlaid on the background color.| 88 89## backgroundImage<sup>18+</sup> 90 91backgroundImage(src: ResourceStr | PixelMap, options?: BackgroundImageOptions) 92 93Sets the background image of the component. Compared to [backgroundImage](#backgroundimage), this API supports the **BackgroundImageOptions** type, but not the **ImageRepeat** type. 94 95**Widget capability**: This API can be used in ArkTS widgets since API version 18. 96 97**Atomic service API**: This API can be used in atomic services since API version 18. 98 99**System capability**: SystemCapability.ArkUI.ArkUI.Full 100 101**Parameters** 102 103| Name| Type | Mandatory| Description | 104| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 105| src | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) | Yes | Image address, which can be the address of an online or local image, a Base64 encoded string, or a pixel map. SVG images are not supported.| 106| options | [BackgroundImageOptions](ts-universal-attributes-image-effect.md#backgroundimageoptions18) | No | Background image loading mode.<br> **NOTE**<br>By default, the image is loaded asynchronously.| 107 108## backgroundImageSize 109 110backgroundImageSize(value: SizeOptions | ImageSize) 111 112Sets the width and height of the component background image. 113 114**Widget capability**: This API can be used in ArkTS widgets since API version 9. 115 116**Atomic service API**: This API can be used in atomic services since API version 11. 117 118**System capability**: SystemCapability.ArkUI.ArkUI.Full 119 120**Parameters** 121 122| Name| Type | Mandatory| Description | 123| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 124| value | [SizeOptions](ts-universal-attributes-size.md#sizeoptions) \| [ImageSize](ts-appendix-enums.md#imagesize) | Yes | Width and height of the background image. If the input is a **{width: Length, height: Length}** object and only one attribute is set, the other attribute is the set value multiplied by the original aspect ratio of the image. By default, the original image aspect ratio remains unchanged.<br>The value range of **width** and **height** is [0, +∞).<br>Default value: **ImageSize.Auto**<br>**NOTE**<br>If both **width** and **height** are set to values less than or equal to 0, they are treated as 0. If either **width** or **height** is unset or set to a value less than or equal to 0, the other one is adjusted based on the original aspect ratio of the image.| 125 126## backgroundImagePosition 127 128backgroundImagePosition(value: Position | Alignment) 129 130Sets the position of the component background image. 131 132**Widget capability**: This API can be used in ArkTS widgets since API version 9. 133 134**Atomic service API**: This API can be used in atomic services since API version 11. 135 136**System capability**: SystemCapability.ArkUI.ArkUI.Full 137 138**Parameters** 139 140| Name| Type | Mandatory| Description | 141| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 142| value | [Position](ts-types.md#position) \| [Alignment](ts-appendix-enums.md#alignment) | Yes | Position of the background image in the component, that is, the coordinates relative to the upper left corner of the component.<br>Default value:<br>{<br>x: 0,<br>y: 0<br>} <br> When **x** and **y** are set in percentage, the offset is calculated based on the width and height of the component.| 143 144## BlurStyle<sup>9+</sup> 145 146**Widget capability**: This API can be used in ArkTS widgets since API version 9. 147 148**System capability**: SystemCapability.ArkUI.ArkUI.Full 149 150| Name | Description | 151| -------------------- | --------- | 152| Thin | Thin material.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 153| Regular | Regular material.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 154| Thick | Thick material.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 155| BACKGROUND_THIN<sup>10+</sup> | Material that creates the minimum depth of field effect.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 156| BACKGROUND_REGULAR<sup>10+</sup> | Material that creates a medium shallow depth of field effect.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 157| BACKGROUND_THICK<sup>10+</sup> | Material that creates a high shallow depth of field effect.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 158| BACKGROUND_ULTRA_THICK<sup>10+</sup> | Material that creates the maximum depth of field effect.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 159| NONE<sup>10+</sup> | No blur.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 160| COMPONENT_ULTRA_THIN<sup>11+</sup> | Component ultra-thin material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 161| COMPONENT_THIN<sup>11+</sup> | Component thin material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 162| COMPONENT_REGULAR<sup>11+</sup> | Component regular material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 163| COMPONENT_THICK<sup>11+</sup> | Component thick material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 164| COMPONENT_ULTRA_THICK<sup>11+</sup> | Component ultra-thick material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 165 166## SystemAdaptiveOptions<sup>18+</sup> 167 168Defines the system adaptive adjustment options. 169 170**Widget capability**: This API can be used in ArkTS widgets since API version 18. 171 172**Atomic service API**: This API can be used in atomic services since API version 18. 173 174**System capability**: SystemCapability.ArkUI.ArkUI.Full 175 176| Name | Type | Mandatory| Description | 177| ---- | ---- | ---- | -------------------------- | 178| disableSystemAdaptation | boolean | No | Whether to disable system adaptive adjustment. Whenever possible, do not include this parameter. This parameter only affects low-computing-power devices, the definition of which is determined by the device manufacturer. On low-computing-power devices, the system automatically decides whether to adjust effects (such as blur) to lower-computing-power alternatives based on conditions including computing power and load. To disable this feature, set this parameter to **true**.<br>Default value: **false**| 179 180## backgroundBlurStyle<sup>9+</sup> 181 182backgroundBlurStyle(value: BlurStyle, options?: BackgroundBlurStyleOptions) 183 184Defines the blur style to apply between the background and content of a component. It encapsulates various blur radius, mask color, mask opacity, saturation, and brightness values through enum values. 185 186**Widget capability**: This API can be used in ArkTS widgets since API version 9. 187 188**Atomic service API**: This API can be used in atomic services since API version 11. 189 190**System capability**: SystemCapability.ArkUI.ArkUI.Full 191 192**Parameters** 193 194| Name | Type | Mandatory| Description | 195| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 196| value | [BlurStyle](#blurstyle9) | Yes | Settings of the background blur style, including the blur radius, mask color, mask opacity, saturation, and brightness.| 197| options<sup>10+</sup> | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10)| No | Background blur options. | 198 199## backgroundBlurStyle<sup>18+</sup> 200 201backgroundBlurStyle(style: Optional\<BlurStyle>, options?: BackgroundBlurStyleOptions, sysOptions?: SystemAdaptiveOptions) 202 203Defines the blur style to apply between the background and content of a component. It encapsulates various blur radius, mask color, mask opacity, saturation, and brightness values through enum values. Compared to [backgroundBlurStyle<sup>9+</sup>](#backgroundblurstyle9), this API supports the **undefined** type for the **style** parameter. 204 205**Widget capability**: This API can be used in ArkTS widgets since API version 18. 206 207**Atomic service API**: This API can be used in atomic services since API version 18. 208 209**System capability**: SystemCapability.ArkUI.ArkUI.Full 210 211**Parameters** 212 213| Name | Type | Mandatory| Description | 214| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 215| style | Optional\<[BlurStyle](#blurstyle9)> | Yes | Settings of the background blur style, including the blur radius, mask color, mask opacity, saturation, and brightness.<br>If **style** is **undefined**, the background blur reverts to its default state (that is, no blur).| 216| options<sup>16+</sup> | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10)| No | Background blur options. | 217| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](#systemadaptiveoptions18) | No | System adaptive adjustment options.<br>Default value: **{ disableSystemAdaptation: false }** | 218 219> **NOTE** 220> 221> If the background color is specified through **inactiveColor** in **backgroundBlurStyle**, avoid setting the background color again using [backgroundColor](#backgroundcolor). 222 223## backdropBlur 224 225backdropBlur(value: number, options?: BlurOptions) 226 227Applies a background blur effect to the component. You can customize the blur radius and grayscale parameters. 228 229**Widget capability**: This API can be used in ArkTS widgets since API version 9. 230 231**Atomic service API**: This API can be used in atomic services since API version 11. 232 233**System capability**: SystemCapability.ArkUI.ArkUI.Full 234 235**Parameters** 236 237| Name | Type | Mandatory| Description | 238| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 239| value | number | Yes | Background blur effect to apply to the component. The input parameter is the blur radius. The larger the radius is, the more blurred the background is. If the value is **0**, the background is not blurred.| 240| options<sup>11+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | No | Grayscale parameters. | 241 242## backdropBlur<sup>18+</sup> 243 244backdropBlur(radius: Optional\<number>, options?: BlurOptions, sysOptions?: SystemAdaptiveOptions) 245 246Applies a background blur effect to the component. You can customize the blur radius and grayscale parameters. Compared to [backdropBlur](#backdropblur), this API supports the **undefined** type for the **radius** parameter. 247 248**Widget capability**: This API can be used in ArkTS widgets since API version 18. 249 250**Atomic service API**: This API can be used in atomic services since API version 18. 251 252**System capability**: SystemCapability.ArkUI.ArkUI.Full 253 254**Parameters** 255 256| Name | Type | Mandatory| Description | 257| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 258| radius | Optional\<number> | Yes | Background blur effect to apply to the component. The input parameter is the blur radius. The larger the radius is, the more blurred the background is. If the value is **0**, the background is not blurred.<br>If **radius** is **undefined**, the background blur reverts to its default state (that is, no blur).| 259| options<sup>16+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | No | Grayscale parameters. | 260| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](#systemadaptiveoptions18) | No | System adaptive adjustment options.<br>Default value: **{ disableSystemAdaptation: false }** | 261 262> **NOTE** 263> 264> The **blur** and **backdropBlur** APIs provide real-time blurring by rendering each frame, which can be performance-intensive. For static blur effects where content and radius remain unchanged, you are advised to use the static [blur](../../apis-arkgraphics2d/js-apis-effectKit.md#blur) API to reduce the load. 265 266## backgroundEffect<sup>11+</sup> 267 268backgroundEffect(options: BackgroundEffectOptions) 269 270Sets the background effect of the component, including the blur radius, brightness, saturation, and color. 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| options | [BackgroundEffectOptions](#backgroundeffectoptions11) | Yes | Background effect, including saturation, brightness, and color.| 281 282## backgroundEffect<sup>18+</sup> 283 284backgroundEffect(options: Optional\<BackgroundEffectOptions>, sysOptions?: SystemAdaptiveOptions) 285 286Sets the background effect of the component, including the blur radius, brightness, saturation, and color. Compared to [backgroundEffect<sup>11+</sup>](#backgroundeffect11), this API supports the **undefined** type for the **options** parameter. 287 288**Atomic service API**: This API can be used in atomic services since API version 18. 289 290**System capability**: SystemCapability.ArkUI.ArkUI.Full 291 292**Parameters** 293 294| Name | Type | Mandatory| Description | 295| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 296| options | Optional\<[BackgroundEffectOptions](#backgroundeffectoptions11)> | Yes | Background effect, including saturation, brightness, and color.<br>If **options** is **undefined**, the background reverts to its default state with no effect.| 297| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](#systemadaptiveoptions18) | No | System adaptive adjustment options.<br>Default value: **{ disableSystemAdaptation: false }** | 298 299## BackgroundEffectOptions<sup>11+</sup> 300Describes the background effect. 301 302**Atomic service API**: This API can be used in atomic services since API version 12. 303 304**System capability**: SystemCapability.ArkUI.ArkUI.Full 305 306| Name | Type | Mandatory| Description | 307| ---- | ---- | ---- | -------------------------- | 308| radius | number | Yes | Blur radius.<br>Value range: [0, +∞)<br>Default value: **0** | 309| saturation | number | No | Saturation.<br>Value range: [0, +∞)<br>Default value: **1** Recommended value range: [0, 50] | 310| brightness | number | No | Brightness.<br>Value range: [0, +∞)<br>Default value: **1** Recommended value range: [0, 2]| 311| color | [ResourceColor](ts-types.md#resourcecolor) | No | Color.<br>Default value: transparent | 312| adaptiveColor | [AdaptiveColor](ts-universal-attributes-foreground-blur-style.md#adaptivecolor10) | No | Adaptive color mode used for the background blur effect.<br>Default value: **DEFAULT** When set to **AVERAGE**, the adaptive color mode takes effect only when the color has transparency. | 313| blurOptions | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | No | Grayscale blur.<br>Default value: **[0, 0]** | 314| policy<sup>14+</sup> | [BlurStyleActivePolicy](#blurstyleactivepolicy14) | No | Blur activation policy.<br> Default value: **BlurStyleActivePolicy.ALWAYS_ACTIVE**| 315| inactiveColor<sup>14+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the components within the window after the window loses focus (in which case, the blur effect on the components within the window is removed).| 316 317## backgroundImageResizable<sup>12+</sup> 318 319backgroundImageResizable(value: ResizableOptions) 320 321Sets the resizable background image options. 322 323When **ResizableOptions** is set to a valid value, the **repeat** parameter in [backgroundImage](#backgroundimage) does not take effect. 324 325When the sum of the values of **top** and **bottom** is greater than the source image height, or the sum of the values of **left** and **right** is greater than the source image width, the **ResizableOptions** attribute does not take effect. 326 327**Atomic service API**: This API can be used in atomic services since API version 12. 328 329**System capability**: SystemCapability.ArkUI.ArkUI.Full 330 331**Parameters** 332 333| Name| Type | Mandatory| Description | 334| ------ | --------------------------------------- | ---- | -------------------------------- | 335| value | [ResizableOptions](ts-basic-components-image.md#resizableoptions11) | Yes | Resizable image options.| 336 337## BackgroundBlurStyleOptions<sup>10+</sup> 338 339Inherited from [BlurStyleOptions](ts-universal-attributes-foreground-blur-style.md). 340 341**Atomic service API**: This API can be used in atomic services since API version 13. 342 343**System capability**: SystemCapability.ArkUI.ArkUI.Full 344 345| Name| Type | Mandatory| Description | 346| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | 347| policy<sup>14+</sup> | [BlurStyleActivePolicy](#blurstyleactivepolicy14) | No | Blur activation policy.<br> Default value: **BlurStyleActivePolicy.ALWAYS_ACTIVE**| 348| inactiveColor<sup>14+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the components within the window after the window loses focus (in which case, the blur effect on the components within the window is removed).| 349 350## BlurStyleActivePolicy<sup>14+</sup> 351 352**Atomic service API**: This API can be used in atomic services since API version 14. 353 354**System capability**: SystemCapability.ArkUI.ArkUI.Full 355 356| Name | Value|Description | 357| ------ | ----------------------------- |----------------------------- | 358| FOLLOWS_WINDOW_ACTIVE_STATE| 0|The blur effect changes according to the window's focus state; it is inactive when the window is not in focus and active when the window is in focus.| 359| ALWAYS_ACTIVE | 1|The blur effect is always active.| 360| ALWAYS_INACTIVE |2 |The blur effect is always inactive.| 361 362## backgroundBrightness<sup>12+</sup> 363 364backgroundBrightness(params: BackgroundBrightnessOptions) 365 366Sets the background brightness of the component. 367 368**Atomic service API**: This API can be used in atomic services since API version 12. 369 370**System capability**: SystemCapability.ArkUI.ArkUI.Full 371 372**Parameters** 373 374| Name| Type | Mandatory| Description | 375| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | 376| params | [BackgroundBrightnessOptions](#backgroundbrightnessoptions12) | Yes | Parameters for setting the background brightness.| 377 378## backgroundBrightness<sup>18+</sup> 379 380backgroundBrightness(options: Optional\<BackgroundBrightnessOptions>) 381 382Sets the background brightness of the component. Compared to [backgroundBrightness<sup>12+</sup>](#backgroundbrightness12), this API supports the **undefined** type for the **options** parameter. 383 384**Atomic service API**: This API can be used in atomic services since API version 18. 385 386**System capability**: SystemCapability.ArkUI.ArkUI.Full 387 388**Parameters** 389 390| Name | Type | Mandatory| Description | 391| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 392| options | Optional\<[BackgroundBrightnessOptions](#backgroundbrightnessoptions12)> | Yes | Parameters for setting the background brightness.<br>If **options** is **undefined**, the background reverts to its default state with no brightness effect.| 393 394## BackgroundBrightnessOptions<sup>12+</sup> 395 396**Atomic service API**: This API can be used in atomic services since API version 12. 397 398**System capability**: SystemCapability.ArkUI.ArkUI.Full 399 400| Name | Type | Mandatory| Description | 401| ------------- | ------ | ---- | ------------------------------------------------------------ | 402| rate | number | Yes | Brightness change rate. A higher rate means that brightness decreases more quickly. If **rate** is set to **0**, **lightUpDegree** will not take effect, meaning no brightening effect will occur.<br>Default value: **0.0**<br>Value range: (0.0, +∞)| 403| lightUpDegree | number | Yes | Light up degree. A greater degree indicates a greater increase in brightness.<br> Default value: **0.0**<br>Value range: [-1.0, 1.0]| 404 405> **NOTE** 406> 407> The brightness (gray scale value) of each pixel in the component background content is calculated using the following formula: 408> Y = (0.299R + 0.587G + 0.114B) / 255.0, where **R**, **G**, and **B** represent red, green, and blue channel values of the pixel, respectively, and **Y** is the gray scale value. This formula normalizes the gray scale value to a range of 0 to 1. 409> The formula for calculating the increase in brightness for each pixel is as follows: ΔY = -rate * Y + lightUpDegree. For example, when rate = 0.5 and lightUpDegree = 0.5, for a pixel with a gray scale value of 0.2, the increase in brightness is -0.5 * 0.2 + 0.5 = 0.4. For a pixel with a gray scale value of 1, the increase in brightness is -0.5 * 1 + 0.5 = 0. 410 411## Example 412 413### Example 1: Setting Basic Background Styles 414 415This example shows how to configure basic background styles by setting **backgroundColor**, **backgroundImage**, **backgroundImageSize**, and **backgroundImagePosition**. 416 417```ts 418// xxx.ets 419@Entry 420@Component 421struct BackgroundExample { 422 423 build() { 424 Column({ space: 5 }) { 425 Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC) 426 Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 }) 427 428 Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC) 429 Row() 430 .backgroundImage('/comment/bg.jpg', ImageRepeat.X) 431 .backgroundImageSize({ width: '250px', height: '140px' }) 432 .width('90%') 433 .height(70) 434 .border({ width: 1 }) 435 436 Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC) 437 Row() 438 .backgroundImage('/comment/bg.jpg', ImageRepeat.Y) 439 .backgroundImageSize({ width: '500px', height: '120px' }) 440 .width('90%') 441 .height(100) 442 .border({ width: 1 }) 443 444 Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC) 445 Row() 446 .width('90%').height(150) 447 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 448 .backgroundImageSize({ width: 1000, height: 500 }) 449 .border({ width: 1 }) 450 451 Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC) 452 // Occupy all the space of the container, without ensuring that the image is completely displayed. 453 Row() 454 .width(200) 455 .height(50) 456 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 457 .backgroundImageSize(ImageSize.Cover) 458 .border({ width: 1 }) 459 460 Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC) 461 // Maximize the image while ensuring that it can be completely displayed. 462 Row() 463 .width(200) 464 .height(50) 465 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 466 .backgroundImageSize(ImageSize.Contain) 467 .border({ width: 1 }) 468 469 Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC) 470 Row() 471 .width(100) 472 .height(50) 473 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 474 .backgroundImageSize({ width: 1000, height: 560 }) 475 .backgroundImagePosition({ x: -500, y: -300 }) 476 .border({ width: 1 }) 477 } 478 .width('100%').height('100%').padding({ top: 5 }) 479 } 480} 481``` 482 483 484 485### Example 2: Setting the Background Blur Style 486 487This example sets the background blur style using **backgroundBlurStyle**. 488 489```ts 490// xxx.ets 491@Entry 492@Component 493struct BackgroundBlurStyleDemo { 494 build() { 495 Column() { 496 Row() { 497 Text("Thin Material") 498 } 499 .width('50%') 500 .height('50%') 501 .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 }) 502 .position({ x: '15%', y: '30%' }) 503 } 504 .height('100%') 505 .width('100%') 506 .backgroundImage($r('app.media.bg')) 507 .backgroundImageSize(ImageSize.Cover) 508 } 509} 510``` 511 512 513 514### Example 3: Setting the Component Background 515 516This example sets the component background using **background**. 517 518```ts 519// xxx.ets 520@Entry 521@Component 522struct BackgroundExample { 523 @Builder renderBackground() { 524 Column() { 525 Progress({value : 50}) 526 } 527 } 528 529 build() { 530 Column() { 531 Text("content") 532 .width(100) 533 .height(40) 534 .fontColor("#FFF") 535 .position({x:50, y:80}) 536 .textAlign(TextAlign.Center) 537 .backgroundColor(Color.Green) 538 } 539 .width(200).height(200) 540 .background(this.renderBackground) 541 .backgroundColor(Color.Gray) 542 } 543} 544``` 545 546 547 548### Example 4: Setting Component Background Brightness 549 550This example sets the component background brightness using **backgroundBrightness**. 551 552```ts 553// xxx.ets 554@Entry 555@Component 556struct BackgroundBrightnessDemo { 557 build() { 558 Column() { 559 Row() { 560 Text("BackgroundBrightness") 561 } 562 .width(200) 563 .height(100) 564 .position({ x: 100, y: 100 }) 565 .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT}) 566 .backgroundBrightness({rate:0.5,lightUpDegree:0.5}) // Background brightness 567 } 568 .width('100%') 569 .height('100%') 570 .backgroundImage($r('app.media.image')) 571 .backgroundImageSize(ImageSize.Cover) 572 } 573} 574``` 575 576The following figures show how the component looks with the background brightness set. 577 578When **rate** and **lightUpDegree** are both set to **0.5** 579 580 581 582When **rate** is set to **0.5** and **lightUpDegree** **-0.1** 583 584 585 586The following figure shows how the component looks without the background brightness set. 587 588 589 590### Example 5: Setting Blur Effects 591 592This example shows how to use **blur** to apply a foreground blur effect and **backdropBlur** to apply a background blur effect. 593 594```ts 595// xxx.ets 596@Entry 597@Component 598struct BlurEffectsExample { 599 build() { 600 Column({ space: 10 }) { 601 // Blur the font. 602 Text('font blur').fontSize(15).fontColor(0xCCCCCC).width('90%') 603 Flex({ alignItems: ItemAlign.Center }) { 604 Text('original text').margin(10) 605 Text('blur text') 606 .blur(5).margin(10) 607 Text('blur text') 608 .blur(10, undefined).margin(10) // Set the foreground blur radius to 5 and disable system adaptive adjustment. 609 Text('blur text') 610 .blur(15).margin(10) 611 }.width('90%').height(40) 612 .backgroundColor(0xF9CF93) 613 614 615 // Blur the background. 616 Text('backdropBlur').fontSize(15).fontColor(0xCCCCCC).width('90%') 617 Text() 618 .width('90%') 619 .height(40) 620 .fontSize(16) 621 .backdropBlur(3) 622 .backgroundImage($r('app.media.image')) 623 .backgroundImageSize({ width: 1200, height: 160 }) 624 }.width('100%').margin({ top: 5 }) 625 } 626} 627``` 628 629 630 631### Example 6: Setting Text Blur Effects 632 633This example applies anamorphic blur effects on text using **blendMode** and **backgroundEffect**.<br> 634If unwanted lines appear, make sure the sizes of the two owning components of **blendMode** are the same. If the issue persists, the component bounds may have fallen on the floating-point coordinates. In this case, set the universal attribute [pixelRound](ts-universal-attributes-pixelRound.md#pixelround) to align the component bounds on both sides of the unwanted lines with the integer pixel coordinates. 635 636```ts 637// xxx.ets 638@Entry 639@Component 640struct Index { 641 @State shColor: Color = Color.White; 642 @State sizeDate: number = 20; 643 @State rVal: number = 255; 644 @State gVal: number = 255; 645 @State bVal: number = 255; 646 @State aVal: number = 0.1; 647 @State rad: number = 40; 648 @State satVal: number = 0.8; 649 @State briVal: number = 1.5; 650 build() { 651 Stack() { 652 Image($r('app.media.image')) 653 Column() { 654 Column({ space: 0 }) { 655 Column() { 656 Text('11') 657 .fontSize(144) 658 .fontWeight(FontWeight.Bold) 659 .fontColor('rgba(255,255,255,1)') 660 .fontFamily('HarmonyOS-Sans-Digit') 661 .maxLines(1) 662 .lineHeight(120 * 1.25) 663 .height(120 * 1.25) 664 .letterSpacing(4 * 1.25) 665 Text('42') 666 .fontSize(144) 667 .fontWeight(FontWeight.Bold) 668 .fontColor('rgba(255,255,255,1)') 669 .fontFamily('HarmonyOS-Sans-Digit') 670 .maxLines(1) 671 .lineHeight(120 * 1.25) 672 .height(120 * 1.25) 673 .letterSpacing(4 * 1.25) 674 .shadow({ 675 color: 'rgba(0,0,0,0)', 676 radius: 20, 677 offsetX: 0, 678 offsetY: 0 679 }) 680 Row() { 681 Text('October 16') 682 .fontSize(this.sizeDate) 683 .height(22) 684 .fontWeight('medium') 685 .fontColor('rgba(255,255,255,1)') 686 Text('Monday') 687 .fontSize(this.sizeDate) 688 .height(22) 689 .fontWeight('medium') 690 .fontColor('rgba(255,255,255,1)') 691 } 692 } 693 .blendMode(BlendMode.DST_IN, BlendApplyType.OFFSCREEN) 694 .pixelRound({ 695 start: PixelRoundCalcPolicy.FORCE_FLOOR , 696 top: PixelRoundCalcPolicy.FORCE_FLOOR , 697 end: PixelRoundCalcPolicy.FORCE_CEIL, 698 bottom: PixelRoundCalcPolicy.FORCE_CEIL 699 }) 700 } 701 .blendMode(BlendMode.SRC_OVER, BlendApplyType.OFFSCREEN) 702 .backgroundEffect({ 703 radius: this.rad, 704 saturation: this.satVal, 705 brightness: this.briVal, 706 color: this.getVolumeDialogWindowColor() 707 }) 708 .justifyContent(FlexAlign.Center) 709 .pixelRound({ 710 start: PixelRoundCalcPolicy.FORCE_FLOOR , 711 top: PixelRoundCalcPolicy.FORCE_FLOOR , 712 end: PixelRoundCalcPolicy.FORCE_CEIL, 713 bottom: PixelRoundCalcPolicy.FORCE_CEIL 714 }) 715 } 716 } 717 } 718 getVolumeDialogWindowColor(): ResourceColor | string { 719 return `rgba(${this.rVal.toFixed(0)}, ${this.gVal.toFixed(0)}, ${this.bVal.toFixed(0)}, ${this.aVal.toFixed(0)})`; 720 } 721} 722``` 723 724 725 726### Example 7: Comparing Blur Effects 727 728This example compares three different blur effects: **backgroundEffect**, **backDropBlur**, and **backgroundBlurStyle**. 729 730```ts 731// xxx.ets 732@Entry 733@Component 734struct BackGroundBlur { 735 private imageSize: number = 150; 736 737 build() { 738 Column({ space: 5 }) { 739 // Use backgroundBlurStyle with an enum value to set blur parameters. 740 Stack() { 741 Image($r('app.media.test')) 742 .width(this.imageSize) 743 .height(this.imageSize) 744 Column() 745 .width(this.imageSize) 746 .height(this.imageSize) 747 .backgroundBlurStyle(BlurStyle.Thin) 748 } 749 750 // backgroundEffect allows for custom settings for blur radius, brightness, saturation, and more. 751 Stack() { 752 Image($r('app.media.test')) 753 .width(this.imageSize) 754 .height(this.imageSize) 755 Column() 756 .width(this.imageSize) 757 .height(this.imageSize) 758 .backgroundEffect({ radius: 20, brightness: 0.6, saturation: 15 }) 759 } 760 761 // backdropBlur only sets blur radius and grayscale parameters. 762 Stack() { 763 Image($r('app.media.test')) 764 .width(this.imageSize) 765 .height(this.imageSize) 766 Column() 767 .width(this.imageSize) 768 .height(this.imageSize) 769 .backdropBlur(20, { grayscale: [30, 50] }) 770 } 771 } 772 .width('100%') 773 .padding({ top: 5 }) 774 } 775} 776``` 777 778 779
