1# 背景设置 2 3设置组件的背景样式。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## background<sup>10+</sup> 10 11background(builder: CustomBuilder, options?: { align?: Alignment }) 12 13设置组件背景。 14 15**系统能力：** SystemCapability.ArkUI.ArkUI.Full 16 17**参数：** 18 19| 参数名 | 类型 | 必填 | 说明 | 20| ------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 21| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 自定义背景。 | 22| options | {align?:[Alignment](ts-appendix-enums.md#alignment)} | 否 | 设置自定义背景与组件的对齐方式。<br/>同时设置了background，backgroundColor，backgroundImage时，叠加显示，background在最上层。 | 23 24> **说明：** 25> 26> 自定义背景渲染会有一定延迟，不能响应事件，不能进行动态更新。该属性不支持嵌套使用，不支持预览器预览。 27 28## backgroundColor 29 30backgroundColor(value: ResourceColor) 31 32设置组件背景色。 33 34**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 35 36**系统能力：** SystemCapability.ArkUI.ArkUI.Full 37 38**参数：** 39 40| 参数名 | 类型 | 必填 | 说明 | 41| ------ | ------------------------------------------ | ---- | ------------------ | 42| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置组件的背景色。 | 43 44## backgroundImage 45 46backgroundImage(src: ResourceStr, repeat?: ImageRepeat) 47 48设置组件的背景图片。 49 50**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 51 52**系统能力：** SystemCapability.ArkUI.ArkUI.Full 53 54**参数：** 55 56| 参数名 | 类型 | 必填 | 说明 | 57| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 58| src | [ResourceStr](ts-types.md#resourcestr) | 是 | 图片地址，支持网络图片资源地址和本地图片资源地址和Base64，不支持svg类型的图片。 | 59| repeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 否 | 设置背景图片的重复样式，默认不重复。当设置的背景图片为透明底色图片，且同时设置了backgroundColor时，二者叠加显示，背景颜色在最底部。 | 60 61## backgroundImageSize 62 63backgroundImageSize(value: SizeOptions | ImageSize) 64 65设置组件背景图片的宽高。 66 67**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 68 69**系统能力：** SystemCapability.ArkUI.ArkUI.Full 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 75| value | [SizeOptions](ts-universal-attributes-size.md#sizeoptions对象说明) \| [ImageSize](ts-appendix-enums.md#imagesize) | 是 | 设置背景图像的高度和宽度。当输入为{width: Length, height: Length}对象时，如果只设置一个属性，则第二个属性保持图片原始宽高比进行调整。默认保持原图的比例不变。<br/>width和height取值范围： [0, +∞)<br/>默认值：ImageSize.Auto<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：** <br/>设置为小于0的值时，按值为0显示。当设置了height未设置width时，width根据图片原始宽高比进行调整。 | 76 77## backgroundImagePosition 78 79backgroundImagePosition(value: Position | Alignment) 80 81设置背景图的位置。 82 83**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 84 85**系统能力：** SystemCapability.ArkUI.ArkUI.Full 86 87**参数：** 88 89| 参数名 | 类型 | 必填 | 说明 | 90| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 91| value | [Position](ts-types.md#position8) \| [Alignment](ts-appendix-enums.md#alignment) | 是 | 设置背景图在组件中显示位置，即相对于组件左上角的坐标。<br/>默认值：<br/>{<br/>x: 0,<br/>y: 0<br/>} <br/> x和y值设置百分比时，偏移量是相对组件自身宽高计算的。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 92 93## backgroundBlurStyle<sup>9+</sup> 94 95backgroundBlurStyle(value: BlurStyle, options?: BackgroundBlurStyleOptions) 96 97为当前组件提供一种在背景和内容之间的模糊能力。 98 99**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 100 101**系统能力：** SystemCapability.ArkUI.ArkUI.Full 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 107| value | [BlurStyle](ts-appendix-enums.md#blurstyle9) | 是 | 背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。 | 108| options<sup>10+</sup> | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10对象说明) | 否 | 背景模糊选项。 | 109 110## backgroundEffect<sup>11+</sup> 111 112backgroundEffect(options: BackgroundEffectOptions) 113 114设置组件背景属性。 115 116**系统能力：** SystemCapability.ArkUI.ArkUI.Full 117 118**参数：** 119 120| 参数名 | 类型 | 必填 | 说明 | 121| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 122| options | [BackgroundEffectOptions](ts-appendix-enums.md#backgroundeffectoptions11) | 是 | 设置组件背景属性包括：饱和度，亮度，颜色。 | 123 124## BackgroundBlurStyleOptions<sup>10+</sup>对象说明 125 126继承自[BlurStyleOptions](ts-universal-attributes-foreground-blur-style.md) 127 128## 示例 129 130### 示例1 131 132```ts 133// xxx.ets 134@Entry 135@Component 136struct BackgroundExample { 137 138 build() { 139 Column({ space: 5 }) { 140 Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC) 141 Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 }) 142 143 Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC) 144 Row() 145 .backgroundImage('/comment/bg.jpg', ImageRepeat.X) 146 .backgroundImageSize({ width: '250px', height: '140px' }) 147 .width('90%') 148 .height(70) 149 .border({ width: 1 }) 150 151 Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC) 152 Row() 153 .backgroundImage('/comment/bg.jpg', ImageRepeat.Y) 154 .backgroundImageSize({ width: '500px', height: '120px' }) 155 .width('90%') 156 .height(100) 157 .border({ width: 1 }) 158 159 Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC) 160 Row() 161 .width('90%').height(150) 162 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 163 .backgroundImageSize({ width: 1000, height: 500 }) 164 .border({ width: 1 }) 165 166 Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC) 167 // 不保证图片完整的情况下占满盒子 168 Row() 169 .width(200) 170 .height(50) 171 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 172 .backgroundImageSize(ImageSize.Cover) 173 .border({ width: 1 }) 174 175 Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC) 176 // 保证图片完整的情况下放到最大 177 Row() 178 .width(200) 179 .height(50) 180 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 181 .backgroundImageSize(ImageSize.Contain) 182 .border({ width: 1 }) 183 184 Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC) 185 Row() 186 .width(100) 187 .height(50) 188 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 189 .backgroundImageSize({ width: 1000, height: 560 }) 190 .backgroundImagePosition({ x: -500, y: -300 }) 191 .border({ width: 1 }) 192 } 193 .width('100%').height('100%').padding({ top: 5 }) 194 } 195} 196``` 197 198 199 200### 示例2 201 202```ts 203// xxx.ets 204@Entry 205@Component 206struct BackgroundBlurStyleDemo { 207 build() { 208 Column() { 209 Row() { 210 Text("Thin Material") 211 } 212 .width('50%') 213 .height('50%') 214 .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 }) 215 .position({ x: '15%', y: '30%' }) 216 } 217 .height('100%') 218 .width('100%') 219 .backgroundImage($r('app.media.bg')) 220 .backgroundImageSize(ImageSize.Cover) 221 } 222} 223``` 224 225 226 227### 示例3 228 229```ts 230// xxx.ets 231@Entry 232@Component 233struct BackgroundExample { 234 @Builder renderBackground() { 235 Column() { 236 Progress({value : 50}) 237 } 238 } 239 240 build() { 241 Column() { 242 Text("content") 243 .width(100) 244 .height(40) 245 .fontColor("#FFF") 246 .position({x:50, y:80}) 247 .textAlign(TextAlign.Center) 248 .backgroundColor(Color.Green) 249 } 250 .width(200).height(200) 251 .background(this.renderBackground) 252 .backgroundColor(Color.Gray) 253 } 254} 255``` 256 257 258 259### 示例4 260 261设置组件背景提亮效果 262 263```ts 264// xxx.ets 265@Entry 266@Component 267struct BackgroundBrightnessDemo { 268 build() { 269 Column() { 270 Row() { 271 Text("BackgroundBrightness") 272 } 273 .width(200) 274 .height(100) 275 .position({ x: 100, y: 100 }) 276 .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT}) 277 .backgroundBrightness({rate:0.5,lightUpDegree:0.5}) // 背景提亮效果 278 } 279 .width('100%') 280 .height('100%') 281 .backgroundImage($r('app.media.image')) 282 .backgroundImageSize(ImageSize.Cover) 283 } 284} 285``` 286 287效果图如下： 288 289rate和lightUpDegree参数值为0.5,0.5： 290 291 292 293修改rate和lightUpDegree参数值为0.5,-0.1： 294 295 296 297去掉backgroundBrightness的设置，效果如下： 298 299
