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**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 16 17**系统能力：** SystemCapability.ArkUI.ArkUI.Full 18 19**参数：** 20 21| 参数名 | 类型 | 必填 | 说明 | 22| ------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 23| builder | [CustomBuilder](ts-types.md#custombuilder8) | 是 | 自定义背景。 | 24| options | {align?:[Alignment](ts-appendix-enums.md#alignment)} | 否 | 设置自定义背景与组件的对齐方式。<br/>同时设置了background，backgroundColor，backgroundImage时，叠加显示，background在最上层。 | 25 26> **说明：** 27> 28> 自定义背景渲染会有一定延迟，不能响应事件，不能进行动态更新。该属性不支持嵌套使用，不支持预览器预览。 29 30## backgroundColor 31 32backgroundColor(value: ResourceColor) 33 34设置组件背景色。 35 36**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 37 38**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 39 40**系统能力：** SystemCapability.ArkUI.ArkUI.Full 41 42**参数：** 43 44| 参数名 | 类型 | 必填 | 说明 | 45| ------ | ------------------------------------------ | ---- | ------------------ | 46| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置组件的背景色。 | 47 48## backgroundColor<sup>18+</sup> 49 50backgroundColor(color: Optional\<ResourceColor>) 51 52设置组件背景色。与[backgroundColor](#backgroundcolor)相比，color参数新增了对undefined类型的支持。 53 54**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 55 56**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 57 58**系统能力：** SystemCapability.ArkUI.ArkUI.Full 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 64| color | Optional\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 设置组件的背景色。<br/>当color的值为undefined时，恢复为默认透明的背景色。 | 65 66> **说明：** 67> 68> 当通过[backgroundBlurStyle](#backgroundblurstyle9)中的inactiveColor指定背景色时，不建议再通过backgroundColor设置背景色。 69 70## backgroundImage 71 72backgroundImage(src: ResourceStr | PixelMap, repeat?: ImageRepeat) 73 74设置组件的背景图片。 75 76**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 77 78**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 79 80**系统能力：** SystemCapability.ArkUI.ArkUI.Full 81 82**参数：** 83 84| 参数名 | 类型 | 必填 | 说明 | 85| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 86| src | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap<sup>12+</sup>](../../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 图片地址，支持网络图片资源地址和本地图片资源地址和Base64或者PixelMap资源，不支持svg类型的图片。 | 87| repeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 否 | 设置背景图片的重复样式，默认不重复。当设置的背景图片为透明底色图片，且同时设置了backgroundColor时，二者叠加显示，背景颜色在最底部。 | 88 89## backgroundImage<sup>18+</sup> 90 91backgroundImage(src: ResourceStr | PixelMap, options?: BackgroundImageOptions) 92 93设置组件的背景图片。与[backgroundImage](#backgroundimage)相比，不支持ImageRepeat类型，而是支持BackgroundImageOptions类型。 94 95**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 96 97**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 98 99**系统能力：** SystemCapability.ArkUI.ArkUI.Full 100 101**参数：** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 105| src | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap](../../apis-image-kit/js-apis-image.md#pixelmap7) | 是 | 图片地址，支持网络图片资源地址、本地图片资源地址、Base64和PixelMap资源，不支持svg类型的图片。 | 106| options | [BackgroundImageOptions](ts-universal-attributes-image-effect.md#BackgroundImageOptions) | 否 | 设置背景图片加载模式。 <br/> **说明：** <br/>默认为异步加载。| 107 108## backgroundImageSize 109 110backgroundImageSize(value: SizeOptions | ImageSize) 111 112设置组件背景图片的宽高。 113 114**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 115 116**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 117 118**系统能力：** SystemCapability.ArkUI.ArkUI.Full 119 120**参数：** 121 122| 参数名 | 类型 | 必填 | 说明 | 123| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 124| 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/>**说明：** <br/>width和height均设置为小于或等于0的值时，按值为0显示。当width和height中只有一个值未设置或者设置为小于等于0的值时，另一个会根据图片原始宽高比进行调整。 | 125 126## backgroundImagePosition 127 128backgroundImagePosition(value: Position | Alignment) 129 130设置背景图的位置。 131 132**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 133 134**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 135 136**系统能力：** SystemCapability.ArkUI.ArkUI.Full 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 142| value | [Position](ts-types.md#position) \| [Alignment](ts-appendix-enums.md#alignment) | 是 | 设置背景图在组件中显示位置，即相对于组件左上角的坐标。<br/>默认值：<br/>{<br/>x: 0,<br/>y: 0<br/>} <br/> x和y值设置百分比时，偏移量是相对组件自身宽高计算的。 | 143 144## BlurStyle<sup>9+</sup> 145 146**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 147 148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 149 150| 名称 | 描述 | 151| -------------------- | --------- | 152| Thin | 轻薄材质模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 153| Regular | 普通厚度材质模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 154| Thick | 厚材质模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 155| BACKGROUND_THIN<sup>10+</sup> | 近距景深模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 156| BACKGROUND_REGULAR<sup>10+</sup> | 中距景深模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 157| BACKGROUND_THICK<sup>10+</sup> | 远距景深模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 158| BACKGROUND_ULTRA_THICK<sup>10+</sup> | 超远距景深模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 159| NONE<sup>10+</sup> | 关闭模糊。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 160| COMPONENT_ULTRA_THIN<sup>11+</sup> | 组件超轻薄材质模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 161| COMPONENT_THIN<sup>11+</sup> | 组件轻薄材质模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 162| COMPONENT_REGULAR<sup>11+</sup> | 组件普通材质模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 163| COMPONENT_THICK<sup>11+</sup> | 组件厚材质模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 164| COMPONENT_ULTRA_THICK<sup>11+</sup> | 组件超厚材质模糊。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 165 166## SystemAdaptiveOptions<sup>18+</sup> 167 168系统自适应调节参数，系统会默认开启根据芯片算力进行自适应效果调节的能力。 169 170**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 171 172**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176| 名称 | 类型 | 必填 | 说明 | 177| ---- | ---- | ---- | -------------------------- | 178| disableSystemAdaptation | boolean | 否 | 系统自适应调节参数，推荐不携带该参数。该参数只影响低算力设备，低算力设备的定义由设备厂商决定。在低芯片算力的设备上，会根据算力和负载等条件，自动决策是否使用低算力的近似效果替代原有效果，比如模糊效果会结合接口中携带的模糊相关参数值及其他低算力处理逻辑，进行自适应效果降级处理。如果想关闭该功能，可以将该标志置为true。<br/>默认值：false | 179 180## backgroundBlurStyle<sup>9+</sup> 181 182backgroundBlurStyle(value: BlurStyle, options?: BackgroundBlurStyleOptions) 183 184为当前组件提供一种在背景和内容之间的模糊能力，通过枚举值的方式封装了不同的模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度。 185 186**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 187 188**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 189 190**系统能力：** SystemCapability.ArkUI.ArkUI.Full 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 196| value | [BlurStyle](#blurstyle9) | 是 | 背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。 | 197| options<sup>10+</sup> | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10对象说明) | 否 | 背景模糊选项。 <br/>该参数在ArkTS卡片中，暂不支持使用。 | 198 199## backgroundBlurStyle<sup>18+</sup> 200 201backgroundBlurStyle(style: Optional\<BlurStyle>, options?: BackgroundBlurStyleOptions, sysOptions?: SystemAdaptiveOptions) 202 203为当前组件提供一种在背景和内容之间的模糊能力，通过枚举值的方式封装了不同的模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度。与[backgroundBlurStyle<sup>9+</sup>](#backgroundblurstyle9)相比，style参数新增了对undefined类型的支持。 204 205**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 206 207**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 208 209**系统能力：** SystemCapability.ArkUI.ArkUI.Full 210 211**参数：** 212 213| 参数名 | 类型 | 必填 | 说明 | 214| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 215| style | Optional\<[BlurStyle](#blurstyle9)> | 是 | 背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。<br/>当style的值为undefined时，恢复为默认关闭模糊的背景。 | 216| options<sup>16+</sup> | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10对象说明) | 否 | 背景模糊选项。<br/>该参数在ArkTS卡片中，暂不支持使用。 | 217| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](#systemadaptiveoptions18) | 否 | 系统自适应调节参数。<br/>默认值：{ disableSystemAdaptation: false } | 218 219> **说明：** 220> 221> 当通过backgroundBlurStyle中的inactiveColor指定背景色时，不建议再通过[backgroundColor](#backgroundcolor)设置背景色。 222 223## backdropBlur 224 225backdropBlur(value: number, options?: BlurOptions) 226 227为组件添加背景模糊效果，可以自定义设置模糊半径和灰阶参数。 228 229**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 230 231**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 232 233**系统能力：** SystemCapability.ArkUI.ArkUI.Full 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 239| value | number | 是 | 为当前组件添加背景模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。 | 240| options<sup>11+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 241 242## backdropBlur<sup>18+</sup> 243 244backdropBlur(radius: Optional\<number>, options?: BlurOptions, sysOptions?: SystemAdaptiveOptions) 245 246为组件添加背景模糊效果，可以自定义设置模糊半径和灰阶参数。与[backdropBlur](#backdropblur)相比，radius参数新增了对undefined类型的支持。 247 248**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 249 250**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 251 252**系统能力：** SystemCapability.ArkUI.ArkUI.Full 253 254**参数：** 255 256| 参数名 | 类型 | 必填 | 说明 | 257| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 258| radius | Optional\<number> | 是 | 为当前组件添加背景模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>当radius的值为undefined时，恢复为默认无模糊的背景。 | 259| options<sup>16+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 260| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](#systemadaptiveoptions18) | 否 | 系统自适应调节参数。<br/>默认值：{ disableSystemAdaptation: false } | 261 262> **说明：** 263> 264> blur和backdropBlur是实时模糊接口，会每帧进行实时渲染，性能负载较高。当模糊内容和模糊半径都不需要变化时，建议使用[静态模糊接口](../../apis-arkgraphics2d/js-apis-effectKit.md#blur)。 265 266## backgroundEffect<sup>11+</sup> 267 268backgroundEffect(options: BackgroundEffectOptions) 269 270设置组件背景属性，包含背景模糊半径，亮度，饱和度，颜色等参数。 271 272**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 273 274**系统能力：** SystemCapability.ArkUI.ArkUI.Full 275 276**参数：** 277 278| 参数名 | 类型 | 必填 | 说明 | 279| ------- | ----------------------------------------------------- | ---- | ------------------------------------------ | 280| options | [BackgroundEffectOptions](#backgroundeffectoptions11) | 是 | 设置组件背景属性包括：饱和度，亮度，颜色。 | 281 282## backgroundEffect<sup>18+</sup> 283 284backgroundEffect(options: Optional\<BackgroundEffectOptions>, sysOptions?: SystemAdaptiveOptions) 285 286设置组件背景属性，包含背景模糊半径，亮度，饱和度，颜色等参数。与[backgroundEffect<sup>11+</sup>](#backgroundeffect11 )相比，options参数新增了对undefined类型的支持。 287 288**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 289 290**系统能力：** SystemCapability.ArkUI.ArkUI.Full 291 292**参数：** 293 294| 参数名 | 类型 | 必填 | 说明 | 295| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 296| options | Optional\<[BackgroundEffectOptions](#backgroundeffectoptions11)> | 是 | 设置组件背景属性包括：饱和度，亮度，颜色。<br/>当options的值为undefined时，恢复为无效果的背景。 | 297| sysOptions<sup>18+</sup> | [SystemAdaptiveOptions](#systemadaptiveoptions18) | 否 | 系统自适应调节参数。<br/>默认值：{ disableSystemAdaptation: false } | 298 299## BackgroundEffectOptions<sup>11+</sup> 300背景效果参数。 301 302**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 303 304**系统能力：** SystemCapability.ArkUI.ArkUI.Full 305 306| 名称 | 类型 | 必填 | 说明 | 307| ---- | ---- | ---- | -------------------------- | 308| radius | number | 是 | 模糊半径，取值范围：[0, +∞)，默认为0。 | 309| saturation | number | 否 | 饱和度，取值范围：[0, +∞)，默认为1。推荐取值范围：[0, 50]。 | 310| brightness | number | 否 | 亮度，取值范围：[0, +∞)，默认为1。推荐取值范围：[0, 2]。 | 311| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 颜色，默认透明色。 | 312| adaptiveColor | [AdaptiveColor](ts-universal-attributes-foreground-blur-style.md#adaptivecolor10) | 否 | 背景模糊效果使用的取色模式,默认为DEFAULT。使用AVERAGE时color必须带有透明度，取色模式才生效。 | 313| blurOptions | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶模糊参数，默认为[0,0]。 | 314| policy<sup>14+</sup> | [BlurStyleActivePolicy](#blurstyleactivepolicy14) | 否 | 模糊激活策略。<br/> 默认值：BlurStyleActivePolicy.ALWAYS_ACTIVE | 315| inactiveColor<sup>14+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 窗口失焦后，窗口内控件模糊效果会被移除，则使用inactiveColor作为控件背板颜色。 | 316 317## backgroundImageResizable<sup>12+</sup> 318 319backgroundImageResizable(value: ResizableOptions) 320 321设置背景图在拉伸时可调整大小的图像选项。 322 323设置合法的ResizableOptions时，[backgroundImage](#backgroundimage)属性中的repeat参数设置不生效。 324 325当设置top+bottom大于原图的高或者left+right大于原图的宽时，ResizableOptions属性设置不生效。 326 327**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 328 329**系统能力：** SystemCapability.ArkUI.ArkUI.Full 330 331**参数：** 332 333| 参数名 | 类型 | 必填 | 说明 | 334| ------ | --------------------------------------- | ---- | -------------------------------- | 335| value | [ResizableOptions](ts-basic-components-image.md#resizableoptions11) | 是 | 图像拉伸时可调整大小的图像选项。 | 336 337## BackgroundBlurStyleOptions<sup>10+</sup>对象说明 338 339继承自[BlurStyleOptions](ts-universal-attributes-foreground-blur-style.md)。 340 341**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 342 343**系统能力：** SystemCapability.ArkUI.ArkUI.Full 344 345| 名称 | 类型 | 必填 | 说明 | 346| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | 347| policy<sup>14+</sup> | [BlurStyleActivePolicy](#blurstyleactivepolicy14) | 否 | 模糊激活策略。<br/> 默认值：BlurStyleActivePolicy.ALWAYS_ACTIVE | 348| inactiveColor<sup>14+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 窗口失焦后，窗口内控件模糊效果会被移除，则使用inactiveColor作为控件背板颜色。 | 349 350## BlurStyleActivePolicy<sup>14+</sup> 351 352**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 353 354**系统能力**：SystemCapability.ArkUI.ArkUI.Full 355 356| 名称 | 值|说明 | 357| ------ | ----------------------------- |----------------------------- | 358| FOLLOWS_WINDOW_ACTIVE_STATE| 0|模糊效果跟随窗口焦点状态变化，非焦点不模糊，焦点模糊。| 359| ALWAYS_ACTIVE | 1|一直有模糊效果。| 360| ALWAYS_INACTIVE |2 |一直无模糊效果。| 361 362## backgroundBrightness<sup>12+</sup> 363 364backgroundBrightness(params: BackgroundBrightnessOptions) 365 366设置组件背景提亮效果。 367 368**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 369 370**系统能力：** SystemCapability.ArkUI.ArkUI.Full 371 372**参数：** 373 374| 参数名 | 类型 | 必填 | 说明 | 375| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | 376| params | [BackgroundBrightnessOptions](#backgroundbrightnessoptions12对象说明) | 是 | 设置组件背景提亮效果，包括：亮度变化速率，提亮程度。 | 377 378## backgroundBrightness<sup>18+</sup> 379 380backgroundBrightness(options: Optional\<BackgroundBrightnessOptions>) 381 382设置组件背景提亮效果。与[backgroundBrightness<sup>12+</sup>](#backgroundbrightness12)相比，options参数新增了对undefined类型的支持。 383 384**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 385 386**系统能力：** SystemCapability.ArkUI.ArkUI.Full 387 388**参数：** 389 390| 参数名 | 类型 | 必填 | 说明 | 391| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 392| options | Optional\<[BackgroundBrightnessOptions](#backgroundbrightnessoptions12对象说明)> | 是 | 设置组件背景提亮效果，包括：亮度变化速率，提亮程度。<br/>当options的值为undefined时，恢复为无提亮效果的背景。 | 393 394## BackgroundBrightnessOptions<sup>12+</sup>对象说明 395 396**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 397 398**系统能力：** SystemCapability.ArkUI.ArkUI.Full 399 400| 名称 | 类型 | 必填 | 说明 | 401| ------------- | ------ | ---- | ------------------------------------------------------------ | 402| rate | number | 是 | 亮度变化速率。亮度变化速率越大，提亮程度下降速度越快。若rate为0，则lightUpDegree将不生效，即不会产生任何提亮效果。<br/>默认值：0.0 <br/>取值范围：(0.0, +∞) | 403| lightUpDegree | number | 是 | 提亮程度。提亮程度越大，亮度提升程度越大。<br/> 默认值：0.0 <br/>取值范围：[-1.0, 1.0] | 404 405> **说明：** 406> 407> 对于组件背景内容，每个像素自身的亮度（灰阶值）的计算公式为： 408> `Y = （0.299R + 0.587G + 0.114B）/ 255.0`（R、G、B分别表示像素红色、绿色和蓝色通道的值，Y表示灰阶值），通过上述公式将像素点的灰阶值归一化至0~1的范围。 409> 每个像素的亮度提升计算公式为：`Δ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`。 410 411## 示例 412 413### 示例1（设置背景基础样式） 414 415该示例通过配置backgroundColor、backgroundImage、backgroundImageSize和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 // 不保证图片完整的情况下占满盒子 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 // 保证图片完整的情况下放到最大 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### 示例2（设置背景模糊样式） 486 487该示例通过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### 示例3（设置组件背景） 515 516该示例通过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### 示例4（设置组件背景提亮效果） 549 550该示例通过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}) // 背景提亮效果 567 } 568 .width('100%') 569 .height('100%') 570 .backgroundImage($r('app.media.image')) 571 .backgroundImageSize(ImageSize.Cover) 572 } 573} 574``` 575 576效果图如下： 577 578rate和lightUpDegree参数值为0.5,0.5： 579 580 581 582修改rate和lightUpDegree参数值为0.5,-0.1： 583 584 585 586去掉backgroundBrightness的设置，效果如下： 587 588 589 590### 示例5（设置模糊属性） 591 592该示例提供了模糊属性的实现方法。通过blur设置内容模糊，通过backdropBlur设置背景模糊。 593 594```ts 595// xxx.ets 596@Entry 597@Component 598struct BlurEffectsExample { 599 build() { 600 Column({ space: 10 }) { 601 // 对字体进行模糊 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) // 内容模糊半径为5，禁用系统自适应优化策略。 609 Text('blur text') 610 .blur(15).margin(10) 611 }.width('90%').height(40) 612 .backgroundColor(0xF9CF93) 613 614 615 // 对背景进行模糊 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### 示例6（设置文字异形模糊效果） 632 633该示例通过blendMode和backgroundEffect实现文字异形模糊效果。<br/> 634如果出现漏线问题，开发者应首先确保两个blendMode所在组件大小严格相同。如果确认相同，可能是组件边界落在浮点数坐标上导致，可尝试设置[pixelRound](ts-universal-attributes-pixelRound.md#pixelround)通用属性，使产生的白线、暗线两侧的组件边界对齐到整数像素坐标上。 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('10月16日') 682 .fontSize(this.sizeDate) 683 .height(22) 684 .fontWeight('medium') 685 .fontColor('rgba(255,255,255,1)') 686 Text('星期一') 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### 示例7（模糊效果对比） 727 728该示例对比了backgroundEffect、backDropBlur和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 // backgroundBlurStyle通过枚举值的方式设置模糊参数 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 可以自定义设置 模糊半径，亮度，饱和度等参数 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 只能设置模糊半径和灰阶参数 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
