鸿蒙5.0开辟进阶：API ArkUI框架-ArkTS组件（背景设置）

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

• 鸿蒙开辟核心知识点，看这篇文章就够了
  
• 最新版！鸿蒙HarmonyOS Next应用开辟实战学习路线
  
• 鸿蒙HarmonyOS NEXT开辟技能最全学习路线指南
  
• 鸿蒙应用开辟实战项目，看这一篇文章就够了（部分项目附源码）
  

---

背景设置

设置组件的背景样式。
   说明
  从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
  background10+

background(builder: CustomBuilder, options?: { align?: Alignment })
设置组件背景。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明builderCustomBuilder是自界说背景。options{align?:Alignment}否 设置自界说背景与组件的对齐方式。
同时设置了background，backgroundColor，backgroundImage时，叠加显示，background在最上层。
    说明
  自界说背景渲染会有一定延迟，不能相应事件，不能进行动态更新。该属性不支持嵌套利用，不支持预览器预览。
  backgroundColor

backgroundColor(value: ResourceColor)
设置组件背景色。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中利用。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueResourceColor是设置组件的背景色。   说明
  当通过backgroundBlurStyle中的inactiveColor指定背景色时，不发起再通过backgroundColor设置背景色。
  backgroundImage

backgroundImage(src: ResourceStr | PixelMap, repeat?: ImageRepeat)
设置组件的背景图片。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中利用。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明srcResourceStr | PixelMap12+是图片地址，支持网络图片资源地址和当地图片资源地址和Base64或者PixelMap资源，不支持svg类型的图片。repeatImageRepeat否设置背景图片的重复样式，默认不重复。当设置的背景图片为透明底色图片，且同时设置了backgroundColor时，二者叠加显示，背景颜色在最底部。 backgroundImageSize

backgroundImageSize(value: SizeOptions | ImageSize)
设置组件背景图片的宽高。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中利用。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueSizeOptions | ImageSize是 设置背景图像的高度和宽度。当输入为{width: Length, height: Length}对象时，如果只设置一个属性，则第二个属性保持图片原始宽高比进行调整。默认保持原图的比例稳定。
width和height取值范围： [0, +∞)
默认值：ImageSize.Auto
说明：
width和height均设置为小于或即是0的值时，按值为0显示。当width和height中只有一个值未设置或者设置为小于即是0的值时，另一个会根据图片原始宽高比进行调整。
  backgroundImagePosition

backgroundImagePosition(value: Position | Alignment)
设置背景图的位置。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中利用。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valuePosition | Alignment是 设置背景图在组件中显示位置，即相对于组件左上角的坐标。
默认值：
{
x: 0,
y: 0
}
x和y值设置百分比时，偏移量是相对组件自身宽高计算的。
  BlurStyle9+

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
名称描述Thin 轻薄材质模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
Regular 普通厚度材质模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
Thick 厚材质模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
BACKGROUND_THIN10+ 近距景深模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
BACKGROUND_REGULAR10+ 中距景深模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
BACKGROUND_THICK10+ 远距景深模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
BACKGROUND_ULTRA_THICK10+ 超远距景深模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
NONE10+ 关闭模糊。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
COMPONENT_ULTRA_THIN11+ 组件超轻薄材质模糊。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
COMPONENT_THIN11+ 组件轻薄材质模糊。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
COMPONENT_REGULAR11+ 组件普通材质模糊。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
COMPONENT_THICK11+ 组件厚材质模糊。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
COMPONENT_ULTRA_THICK11+ 组件超厚材质模糊。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
  backgroundBlurStyle9+

backgroundBlurStyle(value: BlurStyle, options?: BackgroundBlurStyleOptions)
为当前组件提供一种在背景和内容之间的模糊能力，通过枚举值的方式封装了差别的模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中利用。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueBlurStyle是背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。options10+BackgroundBlurStyleOptions否背景模糊选项。   说明
  当通过backgroundBlurStyle中的inactiveColor指定背景色时，不发起再通过backgroundColor设置背景色。
  backdropBlur

backdropBlur(value: number, options?: BlurOptions)
为组件添加背景模糊结果，可以自定设置模糊半径和灰阶参数。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中利用。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valuenumber是为当前组件添加背景模糊结果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。options11+BlurOptions否灰门路参数。   说明
  blur和backdropBlur是实时模糊接口，会每帧进行实时渲染，性能负载较高。当模糊内容和模糊半径都不必要变化时，发起利用静态模糊接口。
  backgroundEffect11+

backgroundEffect(options: BackgroundEffectOptions)
设置组件背景属性，包含背景模糊半径，亮度，饱和度，颜色等参数。
元服务API： 从API version 11开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明optionsBackgroundEffectOptions是设置组件背景属性包括：饱和度，亮度，颜色。 BackgroundEffectOptions11+

背景结果参数。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
名称类型必填说明radiusnumber是模糊半径，取值范围：[0, +∞)，默认为0。saturationnumber否饱和度，取值范围：[0, +∞)，默认为1。推荐取值范围：[0, 50]。brightnessnumber否亮度，取值范围：[0, +∞)，默认为1。推荐取值范围：[0, 2]。colorResourceColor否颜色，默认透明色。adaptiveColorAdaptiveColor否背景模糊结果利用的取色模式,默认为DEFAULT。利用AVERAGE时color必须带有透明度，取色模式才生效。blurOptionsBlurOptions否灰阶模糊参数，默认为[0,0]。 backgroundImageResizable12+

backgroundImageResizable(value: ResizableOptions)
设置背景图在拉伸时可调整大小的图像选项。
设置正当的ResizableOptions时，backgroundImage属性中的repeat参数设置不生效。
当设置top+bottom大于原图的高或者left+right大于原图的宽时，ResizableOptions属性设置不生效。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueResizableOptions是图像拉伸时可调整大小的图像选项。 BackgroundBlurStyleOptions10+对象说明

继承自BlurStyleOptions
元服务API： 从API version 11开始，该接口支持在元服务中利用。
backgroundBrightness12+

backgroundBrightness(params: BackgroundBrightnessOptions)
设置组件背景提亮结果。
元服务API： 从API version 12开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明paramsBackgroundBrightnessOptions是设置组件背景提亮结果，包括：亮度变化速率，提亮程度。 BackgroundBrightnessOptions12+对象说明

元服务API： 从API version 12开始，该接口支持在元服务中利用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
名称类型必填说明ratenumber是 亮度变化速率。亮度变化速率越大，提亮程度下降速率越快。若rate为0，则lightUpDegree将不生效，即不会产生任何提亮结果。
默认值：0.0
取值范围：(0.0, +∞)
lightUpDegreenumber是 提亮程度。提亮程度越大，亮度提拔程度越大。
默认值：0.0
取值范围：[-1.0, 1.0]
    说明
  对于组件背景内容，每个像素自身的亮度（灰阶值）的计算公式为：
  Y = （0.299R + 0.587G + 0.114B）/ 255.0（R、G、B分别表示像素红色、绿色和蓝色通道的值，Y表示灰阶值），通过上述公式将像素点的灰阶值归一化至0~1的范围。
  每个像素的亮度提拔计算公式为：ΔY = -rate*Y + lightUpDegree。例如，当rate=0.5，lightUpDegree=0.5时，对于灰阶值为0.2的像素点，亮度增加值为-0.5*0.2 + 0.5 = 0.4，对于灰阶值为1的像素点，亮度增加值为-0.5*1 + 0.5 = 0。
  示例

示例1（设置背景基础样式）

该示例通过配置backgroundColor、backgroundImage、backgroundImageSize和backgroundImagePosition设置背景的基础样式。

1. // xxx.ets
2. @Entry
3. @Component
4. struct BackgroundExample {
6.   build() {
7.     Column({ space: 5 }) {
8.       Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC)
9.       Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 })
11.       Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC)
12.       Row()
13.         .backgroundImage('/comment/bg.jpg', ImageRepeat.X)
14.         .backgroundImageSize({ width: '250px', height: '140px' })
15.         .width('90%')
16.         .height(70)
17.         .border({ width: 1 })
19.       Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC)
20.       Row()
21.         .backgroundImage('/comment/bg.jpg', ImageRepeat.Y)
22.         .backgroundImageSize({ width: '500px', height: '120px' })
23.         .width('90%')
24.         .height(100)
25.         .border({ width: 1 })
27.       Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC)
28.       Row()
29.         .width('90%').height(150)
30.         .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
31.         .backgroundImageSize({ width: 1000, height: 500 })
32.         .border({ width: 1 })
34.       Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC)
35.       // 不保证图片完整的情况下占满盒子
36.       Row()
37.         .width(200)
38.         .height(50)
39.         .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
40.         .backgroundImageSize(ImageSize.Cover)
41.         .border({ width: 1 })
43.       Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC)
44.       // 保证图片完整的情况下放到最大
45.       Row()
46.         .width(200)
47.         .height(50)
48.         .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
49.         .backgroundImageSize(ImageSize.Contain)
50.         .border({ width: 1 })
52.       Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC)
53.       Row()
54.         .width(100)
55.         .height(50)
56.         .backgroundImage('/comment/bg.jpg', ImageRepeat.NoRepeat)
57.         .backgroundImageSize({ width: 1000, height: 560 })
58.         .backgroundImagePosition({ x: -500, y: -300 })
59.         .border({ width: 1 })
60.     }
61.     .width('100%').height('100%').padding({ top: 5 })
62.   }
63. }

复制代码

示例2（设置背景模糊样式）

该示例通过backgroundBlurStyle设置背景模糊样式。

1. // xxx.ets
2. @Entry
3. @Component
4. struct BackgroundBlurStyleDemo {
5.   build() {
6.     Column() {
7.       Row() {
8.         Text("Thin Material")
9.       }
10.       .width('50%')
11.       .height('50%')
12.       .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 })
13.       .position({ x: '15%', y: '30%' })
14.     }
15.     .height('100%')
16.     .width('100%')
17.     .backgroundImage($r('app.media.bg'))
18.     .backgroundImageSize(ImageSize.Cover)
19.   }
20. }

复制代码

示例3（设置组件背景）

该示例通过background设置组件背景。

1. // xxx.ets
2. @Entry
3. @Component
4. struct BackgroundExample {
5.   @Builder renderBackground() {
6.     Column() {
7.       Progress({value : 50})
8.     }
9.   }
11.   build() {
12.     Column() {
13.       Text("content")
14.         .width(100)
15.         .height(40)
16.         .fontColor("#FFF")
17.         .position({x:50, y:80})
18.         .textAlign(TextAlign.Center)
19.         .backgroundColor(Color.Green)
20.     }
21.     .width(200).height(200)
22.     .background(this.renderBackground)
23.     .backgroundColor(Color.Gray)
24.   }
25. }

复制代码

示例4（设置组件背景提亮结果）

该示例通过backgroundBrightness设置组件背景提亮结果。

1. // xxx.ets
2. @Entry
3. @Component
4. struct BackgroundBrightnessDemo {
5.   build() {
6.     Column() {
7.       Row() {
8.         Text("BackgroundBrightness")
9.       }
10.       .width(200)
11.       .height(100)
12.       .position({ x: 100, y: 100 })
13.       .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT})
14.       .backgroundBrightness({rate:0.5,lightUpDegree:0.5}) // 背景提亮效果
15.     }
16.     .width('100%')
17.     .height('100%')
18.     .backgroundImage($r('app.media.image'))
19.     .backgroundImageSize(ImageSize.Cover)
20.   }
21. }

复制代码

结果图如下：
rate和lightUpDegree参数值为0.5,0.5：

修改rate和lightUpDegree参数值为0.5,-0.1：

去掉backgroundBrightness的设置，结果如下：

示例5（设置模糊属性）

该示例提供了模糊属性的实现方法。通过blur设置内容模糊，通过backdropBlur设置背景模糊。

1. // xxx.ets
2. @Entry
3. @Component
4. struct BlurEffectsExample {
5.   build() {
6.     Column({ space: 10 }) {
7.       // 对字体进行模糊
8.       Text('font blur').fontSize(15).fontColor(0xCCCCCC).width('90%')
9.       Flex({ alignItems: ItemAlign.Center }) {
10.         Text('original text').margin(10)
11.         Text('blur text')
12.           .blur(5).margin(10)
13.         Text('blur text')
14.           .blur(10).margin(10)
15.         Text('blur text')
16.           .blur(15).margin(10)
17.       }.width('90%').height(40)
18.       .backgroundColor(0xF9CF93)
22.       // 对背景进行模糊
23.       Text('backdropBlur').fontSize(15).fontColor(0xCCCCCC).width('90%')
24.       Text()
25.         .width('90%')
26.         .height(40)
27.         .fontSize(16)
28.         .backdropBlur(3)
29.         .backgroundImage($r('app.media.image'))
30.         .backgroundImageSize({ width: 1200, height: 160 })
31.     }.width('100%').margin({ top: 5 })
32.   }
33. }

复制代码

示例6（设置文字异形模糊结果）

该示例通过blendMode和backgroundEffect实现文字异形模糊结果。
如果出现漏线题目，开辟者应首先确保两个blendMode所在组件大小严格类似。如果确认类似，大概是组件边界落在浮点数坐标上导致，可尝试设置pixelRound通用属性，使产生的白线、暗线两侧的组件边界对齐到整数像素坐标上。

1. // xxx.ets
2. @Entry
3. @Component
4. struct Index {
5.   @State shColor: Color = Color.White;
6.   @State sizeDate: number = 20;
7.   @State rVal: number = 255;
8.   @State gVal: number = 255;
9.   @State bVal: number = 255;
10.   @State aVal: number = 0.1;
11.   @State rad: number = 40;
12.   @State satVal: number = 0.8;
13.   @State briVal: number = 1.5;
14.   build() {
15.     Stack() {
16.       Image($r('app.media.image'))
17.       Column() {
18.         Column({ space: 0 }) {
19.           Column() {
20.             Text('11')
21.               .fontSize(144)
22.               .fontWeight(FontWeight.Bold)
23.               .fontColor('rgba(255,255,255,1)')
24.               .fontFamily('HarmonyOS-Sans-Digit')
25.               .maxLines(1)
26.               .lineHeight(120 * 1.25)
27.               .height(120 * 1.25)
28.               .letterSpacing(4 * 1.25)
29.             Text('42')
30.               .fontSize(144)
31.               .fontWeight(FontWeight.Bold)
32.               .fontColor('rgba(255,255,255,1)')
33.               .fontFamily('HarmonyOS-Sans-Digit')
34.               .maxLines(1)
35.               .lineHeight(120 * 1.25)
36.               .height(120 * 1.25)
37.               .letterSpacing(4 * 1.25)
38.               .shadow({
39.                 color: 'rgba(0,0,0,0)',
40.                 radius: 20,
41.                 offsetX: 0,
42.                 offsetY: 0
43.               })
44.             Row() {
45.               Text('10月16日')
46.                 .fontSize(this.sizeDate)
47.                 .height(22)
48.                 .fontWeight('medium')
49.                 .fontColor('rgba(255,255,255,1)')
50.               Text('星期一')
51.                 .fontSize(this.sizeDate)
52.                 .height(22)
53.                 .fontWeight('medium')
54.                 .fontColor('rgba(255,255,255,1)')
55.             }
56.           }
57.           .blendMode(BlendMode.DST_IN, BlendApplyType.OFFSCREEN)
58.           .pixelRound({
59.             start: PixelRoundCalcPolicy.FORCE_FLOOR ,
60.             top: PixelRoundCalcPolicy.FORCE_FLOOR ,
61.             end: PixelRoundCalcPolicy.FORCE_CEIL,
62.             bottom: PixelRoundCalcPolicy.FORCE_CEIL
63.           })
64.         }
65.         .blendMode(BlendMode.SRC_OVER, BlendApplyType.OFFSCREEN)
66.         .backgroundEffect({
67.           radius: this.rad,
68.           saturation: this.satVal,
69.           brightness: this.briVal,
70.           color: this.getVolumeDialogWindowColor()
71.         })
72.         .justifyContent(FlexAlign.Center)
73.         .pixelRound({
74.           start: PixelRoundCalcPolicy.FORCE_FLOOR ,
75.           top: PixelRoundCalcPolicy.FORCE_FLOOR ,
76.           end: PixelRoundCalcPolicy.FORCE_CEIL,
77.           bottom: PixelRoundCalcPolicy.FORCE_CEIL
78.         })
79.       }
80.     }
81.   }
82.   getVolumeDialogWindowColor(): ResourceColor | string {
83.     return `rgba(${this.rVal.toFixed(0)}, ${this.gVal.toFixed(0)}, ${this.bVal.toFixed(0)}, ${this.aVal.toFixed(0)})`;
84.   }
85. }

复制代码

示例7（模糊结果对比）

该示例对比了backgroundEffect、backDropBlur和backgroundBlurStyle三种差别的模糊结果。

1. // xxx.ets
2. // xxx.ets
3. @Entry
4. @Component
5. struct BackGroundBlur {
6.   private imageSize: number = 150;
8.   build() {
9.     Column({ space: 5 }) {
10.       // backgroundBlurStyle通过枚举值的方式设置模糊参数
11.       Stack() {
12.         Image($r('app.media.test'))
13.           .width(this.imageSize)
14.           .height(this.imageSize)
15.         Column()
16.           .width(this.imageSize)
17.           .height(this.imageSize)
18.           .backgroundBlurStyle(BlurStyle.Thin)
19.       }
21.       // backgroundEffect 可以自定义设置 模糊半径，亮度，饱和度等参数
22.       Stack() {
23.         Image($r('app.media.test'))
24.           .width(this.imageSize)
25.           .height(this.imageSize)
26.         Column()
27.           .width(this.imageSize)
28.           .height(this.imageSize)
29.           .backgroundEffect({ radius: 20, brightness: 0.6, saturation: 15 })
30.       }
32.       // backdropBlur 只能设置模糊半径和灰阶参数
33.       Stack() {
34.         Image($r('app.media.test'))
35.           .width(this.imageSize)
36.           .height(this.imageSize)
37.         Column()
38.           .width(this.imageSize)
39.           .height(this.imageSize)
40.           .backdropBlur(20, { grayscale: [30, 50] })
41.       }
42.     }
43.     .width('100%')
44.     .padding({ top: 5 })
45.   }
46. }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。