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 the 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## backgroundImage
49
50backgroundImage(src: ResourceStr | PixelMap, repeat?: ImageRepeat)
51
52Sets the background image of the component.
53
54**Widget capability**: This API can be used in ArkTS widgets since API version 9.
55
56**Atomic service API**: This API can be used in atomic services since API version 11.
57
58**System capability**: SystemCapability.ArkUI.ArkUI.Full
59
60**Parameters**
61
62| Name| Type                                           | Mandatory| Description                                                        |
63| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
64| 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.|
65| 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.|
66
67## backgroundImageSize
68
69backgroundImageSize(value: SizeOptions | ImageSize)
70
71Sets the width and height of the component background image.
72
73**Widget capability**: This API can be used in ArkTS widgets since API version 9.
74
75**Atomic service API**: This API can be used in atomic services since API version 11.
76
77**System capability**: SystemCapability.ArkUI.ArkUI.Full
78
79**Parameters**
80
81| Name| Type                                                        | Mandatory| Description                                                        |
82| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
83| 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>A value less than 0 evaluates to the value **0**. If **height** is set but **width** is not, the image width is adjusted based on the original aspect ratio of the image.|
84
85## backgroundImagePosition
86
87backgroundImagePosition(value: Position | Alignment)
88
89Sets the position of the component background image.
90
91**Widget capability**: This API can be used in ArkTS widgets since API version 9.
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  | [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.|
102
103## BlurStyle<sup>9+</sup>
104
105**Widget capability**: This API can be used in ArkTS widgets since API version 9.
106
107**System capability**: SystemCapability.ArkUI.ArkUI.Full
108
109| Name                  | Description       |
110| -------------------- | --------- |
111| Thin                 | Thin material.<br>**Atomic service API**: This API can be used in atomic services since API version 11.  |
112| Regular              | Regular material.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
113| Thick                | Thick material.<br>**Atomic service API**: This API can be used in atomic services since API version 11.   |
114| BACKGROUND_THIN       | 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.  |
115| BACKGROUND_REGULAR    | 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.  |
116| BACKGROUND_THICK      | 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.  |
117| BACKGROUND_ULTRA_THICK | 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. |
118| NONE<sup>10+</sup> | No blur.<br>**Atomic service API**: This API can be used in atomic services since API version 11. |
119| 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.|
120| COMPONENT_THIN<sup>11+</sup> | Component thin material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
121| COMPONENT_REGULAR<sup>11+</sup> | Component regular material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
122| COMPONENT_THICK<sup>11+</sup> | Component thick material.<br>**Atomic service API**: This API can be used in atomic services since API version 12.|
123| 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.|
124
125## backgroundBlurStyle<sup>9+</sup>
126
127backgroundBlurStyle(value: BlurStyle, options?: BackgroundBlurStyleOptions)
128
129Sets the background blur style applied between the content and the background.
130
131**Widget capability**: This API can be used in ArkTS widgets since API version 9.
132
133**Atomic service API**: This API can be used in atomic services since API version 11.
134
135**System capability**: SystemCapability.ArkUI.ArkUI.Full
136
137**Parameters**
138
139| Name               | Type                                                        | Mandatory| Description                                                        |
140| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
141| value                 | [BlurStyle](#blurstyle9)                 | Yes  | Settings of the background blur style, including the blur radius, mask color, mask opacity, saturation, and brightness.|
142| options<sup>10+</sup> | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10)| No  | Background blur options.                                              |
143
144## backgroundEffect<sup>11+</sup> 
145
146backgroundEffect(options: BackgroundEffectOptions)
147
148Sets the background effect of the component.
149
150**Atomic service API**: This API can be used in atomic services since API version 11.
151
152**System capability**: SystemCapability.ArkUI.ArkUI.Full
153
154**Parameters**
155
156| Name | Type                                                        | Mandatory| Description                                      |
157| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
158| options | [BackgroundEffectOptions](#backgroundeffectoptions11) | Yes  | Background effect, including saturation, brightness, and color.|
159
160## BackgroundEffectOptions<sup>11+</sup>
161Describes the background effect.
162
163**Atomic service API**: This API can be used in atomic services since API version 12.
164
165**System capability**: SystemCapability.ArkUI.ArkUI.Full
166
167| Name       |   Type        |   Mandatory|  Description                       |
168| ----         |  ----         |   ---- | --------------------------  |
169| radius       | number        |   Yes  |   Blur radius.<br>Value range: [0, +∞)<br>Default value: **0** |
170| saturation   | number        |   No  |   Saturation.<br>Value range: [0, +∞)<br>Default value: **1** Recommended value range: [0, 50]    |
171| brightness   | number        |   No  |   Brightness.<br>Value range: [0, +∞)<br>Default value: **1** Recommended value range: [0, 2]|
172| color        | [Color](ts-appendix-enums.md#color)        |   No  |   Color.<br>Default value: transparent |
173| 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.  |
174| blurOptions  | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) |   No  |   Grayscale blur.<br>Default value: **[0, 0]** |
175| policy          | [BlurStyleActivePolicy](ts-appendix-enums.md#blurstyleactivepolicy13) | No   | Blur activation policy.<br> Default value: **FOLLOWS_WINDOW_ACTIVE_STATE**<br>|
176| inactiveColor | 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).<br>|
177| type | [BlurType](ts-appendix-enums.md#blurtype13) | No   | Blur type.<br> Default value: **WITHIN_WINDOW**<br>|
178
179## backgroundImageResizable<sup>12+</sup>
180
181backgroundImageResizable(value: ResizableOptions)
182
183Sets the resizable background image options.
184
185When **ResizableOptions** is set to a valid value, the **repeat** parameter in [backgroundImage](#backgroundimage) does not take effect.
186
187When 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.
188
189**Atomic service API**: This API can be used in atomic services since API version 12.
190
191**System capability**: SystemCapability.ArkUI.ArkUI.Full
192
193**Parameters**
194
195| Name| Type                                   | Mandatory| Description                            |
196| ------ | --------------------------------------- | ---- | -------------------------------- |
197| value  | [ResizableOptions](ts-basic-components-image.md#resizableoptions11) | Yes  | Resizable image options.|
198
199## BackgroundBlurStyleOptions<sup>10+</sup>
200
201Inherited from [BlurStyleOptions](ts-universal-attributes-foreground-blur-style.md).
202
203**Atomic service API**: This API can be used in atomic services since API version 13.
204
205| Name| Type                                                        | Mandatory| Description                                                |
206| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- |
207| policy          | [BlurStyleActivePolicy](ts-appendix-enums.md#blurstyleactivepolicy13) | No   | Blur activation policy.<br> Default value: **FOLLOWS_WINDOW_ACTIVE_STATE**<br>|
208| inactiveColor | 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).<br>|
209| type | [BlurType](ts-appendix-enums.md#blurtype13) | No   | Blur type.<br> Default value: **WITHIN_WINDOW**<br>|
210
211
212## backgroundBrightness<sup>12+</sup> 
213
214backgroundBrightness(params: BackgroundBrightnessOptions)
215
216Sets the background brightness of the component.
217
218**Atomic service API**: This API can be used in atomic services since API version 12.
219
220**System capability**: SystemCapability.ArkUI.ArkUI.Full
221
222**Parameters**
223
224| Name| Type                                                        | Mandatory| Description                                                |
225| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- |
226| params | [BackgroundBrightnessOptions](#backgroundbrightnessoptions12) | Yes  | Parameters for setting the background brightness.|
227
228## BackgroundBrightnessOptions<sup>12+</sup>
229
230**Atomic service API**: This API can be used in atomic services since API version 12.
231
232| Name           | Type                                    | Mandatory  | Description                                      |
233| ------------- | ---------------------------------------- | ---- | ---------------------------------------- |
234| rate          | number | Yes   | Brightness change rate. A larger change rate indicates a faster decrease and slower increase in brightness.<br>Default value: **0.0**<br>Value range: (0.0, +∞)<br>|
235| 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]<br>|
236
237
238## Example
239
240### Example 1
241
242```ts
243// xxx.ets
244@Entry
245@Component
246struct BackgroundExample {
247
248  build() {
249    Column({ space: 5 }) {
250      Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC)
251      Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 })
252
253      Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC)
254      Row()
255        .backgroundImage('/comment/bg.jpg', ImageRepeat.X)
256        .backgroundImageSize({ width: '250px', height: '140px' })
257        .width('90%')
258        .height(70)
259        .border({ width: 1 })
260
261      Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC)
262      Row()
263        .backgroundImage('/comment/bg.jpg', ImageRepeat.Y)
264        .backgroundImageSize({ width: '500px', height: '120px' })
265        .width('90%')
266        .height(100)
267        .border({ width: 1 })
268
269      Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC)
270      Row()
271        .width('90%').height(150)
272        .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
273        .backgroundImageSize({ width: 1000, height: 500 })
274        .border({ width: 1 })
275
276      Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC)
277      // Occupy all the space of the container, without ensuring that the image is completely displayed.
278      Row()
279        .width(200)
280        .height(50)
281        .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
282        .backgroundImageSize(ImageSize.Cover)
283        .border({ width: 1 })
284
285      Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC)
286      // Maximize the image while ensuring that it can be completely displayed.
287      Row()
288        .width(200)
289        .height(50)
290        .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
291        .backgroundImageSize(ImageSize.Contain)
292        .border({ width: 1 })
293
294      Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC)
295      Row()
296        .width(100)
297        .height(50)
298        .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
299        .backgroundImageSize({ width: 1000, height: 560 })
300        .backgroundImagePosition({ x: -500, y: -300 })
301        .border({ width: 1 })
302    }
303    .width('100%').height('100%').padding({ top: 5 })
304  }
305}
306```
307
308![en-us_image_0000001211898502](figures/en-us_image_0000001211898502.png)
309
310### Example 2
311
312```ts
313// xxx.ets
314@Entry
315@Component
316struct BackgroundBlurStyleDemo {
317  build() {
318    Column() {
319      Row() {
320        Text("Thin Material")
321      }
322      .width('50%')
323      .height('50%')
324      .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 })
325      .position({ x: '15%', y: '30%' })
326    }
327    .height('100%')
328    .width('100%')
329    .backgroundImage($r('app.media.bg'))
330    .backgroundImageSize(ImageSize.Cover)
331  }
332}
333```
334
335![en-us_image_background_blur_style](figures/en-us_image_background_blur_style.png)
336
337### Example 3
338
339```ts
340// xxx.ets
341@Entry
342@Component
343struct BackgroundExample {
344  @Builder renderBackground() {
345    Column() {
346      Progress({value : 50})
347    }
348  }
349
350  build() {
351    Column() {
352      Text("content")
353        .width(100)
354        .height(40)
355        .fontColor("#FFF")
356        .position({x:50, y:80})
357        .textAlign(TextAlign.Center)
358        .backgroundColor(Color.Green)
359    }
360    .width(200).height(200)
361    .background(this.renderBackground)
362    .backgroundColor(Color.Gray)
363  }
364}
365```
366
367![en-us_image_background](figures/en-us_image_background.png)
368
369### Example 4
370
371This example shows how to set the background brightness for the component.
372
373```ts
374// xxx.ets
375@Entry
376@Component
377struct BackgroundBrightnessDemo {
378  build() {
379    Column() {
380      Row() {
381        Text("BackgroundBrightness")
382      }
383      .width(200)
384      .height(100)
385      .position({ x: 100, y: 100 })
386      .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT})
387      .backgroundBrightness({rate:0.5,lightUpDegree:0.5}) // Background brightness
388    }
389    .width('100%')
390    .height('100%')
391    .backgroundImage($r('app.media.image'))
392    .backgroundImageSize(ImageSize.Cover)
393  }
394}
395```
396
397The following figures show how the component looks with the background brightness set.
398
399When **rate** and **lightUpDegree** are both set to **0.5**
400
401![en-us_image_background_brightness1](figures/en-us_image_background_brightness1.png)
402
403When **rate** is set to **0.5** and **lightUpDegree** **-0.1**
404
405![en-us_image_background_brightness2](figures/en-us_image_background_brightness2.png)
406
407The following figure shows how the component looks without the background brightness set.
408
409![en-us_image_background_brightness3](figures/en-us_image_background_brightness3.png)
410<!--no_check-->