1# 背景设置 2 3设置组件的背景样式。 4 5> **说明：** 6> 7> 从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 属性 10 11| 名称 | 参数类型 | 描述 | 12| -------------------------------- | ---------------------------------------- | ---------------------------------------- | 13| background<sup>10+</sup> | builder: [CustomBuilder](ts-types.md#custombuilder8),<br>options?: {align?:[Alignment](ts-appendix-enums.md#alignment)} | builder：自定义背景。<br/>align：设置自定义背景与组件的对齐方式。<br/>同时设置了background，backgroundColor，backgroundImage时，叠加显示，background在最上层。<br/>**说明：** <br/>自定义背景渲染会有一定延迟，不能响应事件，不能进行动态更新。该属性不支持嵌套使用，不支持预览器预览。| 14| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | 设置组件的背景色。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 15| backgroundImage | src: [ResourceStr](ts-types.md#resourcestr),<br/>repeat?: [ImageRepeat](ts-appendix-enums.md#imagerepeat) | src：图片地址，支持网络图片资源地址和本地图片资源地址和Base64，不支持svg类型的图片。<br/>repeat：设置背景图片的重复样式，默认不重复。当设置的背景图片为透明底色图片，且同时设置了backgroundColor时，二者叠加显示，背景颜色在最底部。<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 16| backgroundImageSize | {<br/>width?: [Length](ts-types.md#length),<br/>height?: [Length](ts-types.md#length)<br/>} \| [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根据图片原始宽高比进行调整。 | 17| backgroundImagePosition | [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卡片中使用。 | 18| backgroundBlurStyle<sup>9+</sup> | value:[BlurStyle](ts-appendix-enums.md#blurstyle9),<br/>options<sup>10+</sup>?:[BackgroundBlurStyleOptions](#backgroundblurstyleoptions10对象说明) | 为当前组件提供一种在背景和内容之间的模糊能力。<br/>value: 背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。<br/>options: 可选参数，背景模糊选项。<br/>该接口支持在ArkTS卡片中使用。 | 19 20## BackgroundBlurStyleOptions<sup>10+</sup>对象说明 21 22| 名称 | 参数类型 | 必填 | 描述 | 23| ------------- | ---------------------------------------- | ---- | ---------------------------------------- | 24| colorMode | [ThemeColorMode](ts-appendix-enums.md#themecolormode10) | 否 | 背景模糊效果使用的深浅色模式。<br/>默认值：ThemeColorMode.System | 25| adaptiveColor | [AdaptiveColor](ts-appendix-enums.md#adaptivecolor10) | 否 | 背景模糊效果使用的取色模式。<br/>默认值：AdaptiveColor.Default | 26| scale | number | 否 | 背景材质模糊效果程度。此参数为系统接口。<br/>默认值：1.0 <br/>取值范围：[0.0, 1.0]<br/> | 27 28## 示例 29 30### 示例1 31 32```ts 33// xxx.ets 34@Entry 35@Component 36struct BackgroundExample { 37 38 build() { 39 Column({ space: 5 }) { 40 Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC) 41 Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 }) 42 43 Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC) 44 Row() 45 .backgroundImage('/comment/bg.jpg', ImageRepeat.X) 46 .backgroundImageSize({ width: '250px', height: '140px' }) 47 .width('90%') 48 .height(70) 49 .border({ width: 1 }) 50 51 Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC) 52 Row() 53 .backgroundImage('/comment/bg.jpg', ImageRepeat.Y) 54 .backgroundImageSize({ width: '500px', height: '120px' }) 55 .width('90%') 56 .height(100) 57 .border({ width: 1 }) 58 59 Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC) 60 Row() 61 .width('90%').height(150) 62 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 63 .backgroundImageSize({ width: 1000, height: 500 }) 64 .border({ width: 1 }) 65 66 Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC) 67 // 不保证图片完整的情况下占满盒子 68 Row() 69 .width(200) 70 .height(50) 71 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 72 .backgroundImageSize(ImageSize.Cover) 73 .border({ width: 1 }) 74 75 Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC) 76 // 保证图片完整的情况下放到最大 77 Row() 78 .width(200) 79 .height(50) 80 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 81 .backgroundImageSize(ImageSize.Contain) 82 .border({ width: 1 }) 83 84 Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC) 85 Row() 86 .width(100) 87 .height(50) 88 .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat) 89 .backgroundImageSize({ width: 1000, height: 560 }) 90 .backgroundImagePosition({ x: -500, y: -300 }) 91 .border({ width: 1 }) 92 } 93 .width('100%').height('100%').padding({ top: 5 }) 94 } 95} 96``` 97 98 99 100### 示例2 101 102```ts 103// xxx.ets 104@Entry 105@Component 106struct BackgroundBlurStyleDemo { 107 build() { 108 Column() { 109 Row() { 110 Text("Thin Material") 111 } 112 .width('50%') 113 .height('50%') 114 .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 }) 115 .position({ x: '15%', y: '30%' }) 116 } 117 .height('100%') 118 .width('100%') 119 .backgroundImage($r('app.media.bg')) 120 .backgroundImageSize(ImageSize.Cover) 121 } 122} 123``` 124 125 126 127### 示例3 128 129```ts 130// xxx.ets 131@Entry 132@Component 133struct BackgroundExample { 134 @Builder renderBackground() { 135 Column() { 136 Progress({value : 50}) 137 } 138 } 139 140 build() { 141 Column() { 142 Text("content") 143 .width(100) 144 .height(40) 145 .fontColor("#FFF") 146 .position({x:50, y:80}) 147 .textAlign(TextAlign.Center) 148 .backgroundColor(Color.Green) 149 } 150 .width(200).height(200) 151 .background(this.renderBackground) 152 .backgroundColor(Color.Gray) 153 } 154} 155``` 156 157
