1# 背景设置 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @CCFFWW--> 5<!--Designer: @yangfan229--> 6<!--Tester: @lxl007--> 7<!--Adviser: @HelloCrease--> 8 9设置组件的背景样式。 10 11> **说明：** 12> 13> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15## background<sup>10+</sup> 16 17background(content: CustomBuilder | ResourceColor, options?: BackgroundOptions): T 18 19设置组件背景。从API version 20开始，content参数新增了对[ResourceColor](ts-types.md#resourcecolor)类型的支持，并新增了背景向父组件的安全区扩展的能力。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 29| content | [CustomBuilder](ts-types.md#custombuilder8) \| [ResourceColor](ts-types.md#resourcecolor) | 是 | 自定义背景。 | 30| options | [BackgroundOptions](#backgroundoptions20对象说明) | 否 | 设置自定义背景选项。<br/>**说明：**<br/>API version 20之前，options: <br/>{<br/>align?: [Alignment](ts-appendix-enums.md#alignment)<br/>}| 31 32**返回值：** 33 34| 类型 | 说明 | 35| -------- | -------- | 36| T | 返回当前组件。 | 37 38> **说明：** 39> 40> - 自定义背景渲染存在一定延迟，不能响应事件。该属性不支持嵌套使用。 41> - CustomBuilder类型的背景不支持在预览器中预览。 42> - 从API version 20开始，支持动态更新背景。 43> - 同时设置background，backgroundColor，backgroundImage时，三者将按以下规则叠加显示： 44> - 若background为ResourceColor类型，或设置ignoresLayoutSafeAreaEdges属性，则background位于最底层。 45> - 其他情况下，background位于最上层。 46 47## BackgroundOptions<sup>20+</sup>对象说明 48 49background配置选项。 50 51**系统能力：** SystemCapability.ArkUI.ArkUI.Full 52 53| 名称 | 类型 | 必填 | 说明 | 54| ------------- | ------ | ---- | ------------------------------------------------------------ | 55| align<sup>10+</sup> | [Alignment](ts-appendix-enums.md#alignment) | 否 | 自定义背景与组件的对齐方式。该属性仅对CustomBuilder类型的背景生效。如果设置了ignoresLayoutSafeAreaEdges，则背景的布局区域为包含了扩展安全区的范围。<br/>默认值：Alignment.Center<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 56| ignoresLayoutSafeAreaEdges | Array<[LayoutSafeAreaEdge](ts-universal-attributes-expand-safe-area.md#layoutsafeareaedge12)> | 否 | 配置背景要扩展到的安全区，包括：状态栏，导航栏和[safeAreaPadding](./ts-universal-attributes-size.md#safeareapadding14)。<br/> 默认值：<br/>- CustomBuilder背景：[]，不扩展。<br/>- ResourceColor背景：[LayoutSafeAreaEdge.ALL]，扩展至所有方向。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 57 58> **说明：** 59> 60> Shape, RowSplit, ColumnSplit, SideBarContainer, Stepper, List, Grid, WaterFlow, Scroll, Refresh, Swiper, Tabs组件的clip属性默认值为true，子组件的背景扩展会被裁剪。 61 62## backgroundColor 63 64backgroundColor(value: ResourceColor): T 65 66设置组件背景色。 67 68**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 69 70**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 71 72**系统能力：** SystemCapability.ArkUI.ArkUI.Full 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| ------ | ------------------------------------------ | ---- | ------------------ | 78| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 设置组件的背景色。 | 79 80**返回值：** 81 82| 类型 | 说明 | 83| ------ | ------------------------ | 84| T | 返回当前组件。 | 85 86## backgroundColor<sup>18+</sup> 87 88backgroundColor(color: Optional\<ResourceColor>): T 89 90设置组件背景色。与[backgroundColor](#backgroundcolor)相比，color参数新增了对undefined类型的支持。 91 92**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 93 94**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 95 96**系统能力：** SystemCapability.ArkUI.ArkUI.Full 97 98**参数：** 99 100| 参数名 | 类型 | 必填 | 说明 | 101| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 102| color | Optional\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 设置组件的背景色。<br/>当color的值为undefined时，恢复为默认透明的背景色。 | 103 104**返回值：** 105 106| 类型 | 说明 | 107| ------ | ------------------------ | 108| T | 返回当前组件。 | 109 110> **说明：** 111> 112> 当通过[backgroundBlurStyle](#backgroundblurstyle9)中的inactiveColor指定背景色时，不建议再通过backgroundColor设置背景色。 113 114## backgroundColor<sup>20+</sup> 115 116backgroundColor(color: Optional<ResourceColor | ColorMetrics>): T 117 118设置组件背景色。与[backgroundColor](#backgroundcolor18)相比，color参数新增了对[ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12)类型的支持。 119 120**卡片能力：** 从API version 20开始，该接口支持在ArkTS卡片中使用。 121 122**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 130| color | Optional\<[ResourceColor](ts-types.md#resourcecolor) \| [ColorMetrics](../js-apis-arkui-graphics.md#colormetrics12)> | 是 | 设置组件的背景色。<br/>当color的值为undefined时，恢复为默认透明的背景色。 | 131 132**返回值：** 133 134| 类型 | 说明 | 135| ------ | ------------------------ | 136| T | 返回当前组件。 | 137 138## backgroundImage 139 140backgroundImage(src: ResourceStr | PixelMap, repeat?: ImageRepeat): T 141 142设置组件的背景图片。 143 144**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 145 146**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 147 148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 154| src | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap<sup>12+</sup>](../../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | 图片地址，支持网络图片资源地址、本地图片资源地址、Base64和PixelMap资源，不支持svg和gif类型的图片。 | 155| repeat | [ImageRepeat](ts-appendix-enums.md#imagerepeat) | 否 | 设置背景图片的重复样式，默认不重复。当设置的背景图片为透明底色图片，且同时设置了backgroundColor时，二者叠加显示，背景颜色在最底部。 | 156 157**返回值：** 158 159| 类型 | 说明 | 160| ------ | ------------------------ | 161| T | 返回当前组件。 | 162 163## backgroundImage<sup>18+</sup> 164 165backgroundImage(src: ResourceStr | PixelMap, options?: BackgroundImageOptions): T 166 167设置组件的背景图片。与[backgroundImage](#backgroundimage)相比，增加了设置图片同步或异步加载方式的能力。 168 169**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 170 171**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 172 173**系统能力：** SystemCapability.ArkUI.ArkUI.Full 174 175**参数：** 176 177| 参数名 | 类型 | 必填 | 说明 | 178| ------ | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 179| src | [ResourceStr](ts-types.md#resourcestr) \| [PixelMap](../../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | 图片地址，支持网络图片资源地址、本地图片资源地址、Base64和PixelMap资源，不支持svg、gif和webp等类型的动图。 | 180| options | [BackgroundImageOptions](ts-universal-attributes-image-effect.md#backgroundimageoptions18) | 否 | 设置背景图选项。 | 181 182**返回值：** 183 184| 类型 | 说明 | 185| ------ | ------------------------ | 186| T | 返回当前组件。 | 187 188## backgroundImageSize 189 190backgroundImageSize(value: SizeOptions | ImageSize): T 191 192设置组件背景图片的宽度和高度。当未设置backgroundImageSize时，默认组件背景图片宽高效果为ImageSize.Auto。 193 194**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 195 196**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 197 198**系统能力：** SystemCapability.ArkUI.ArkUI.Full 199 200**参数：** 201 202| 参数名 | 类型 | 必填 | 说明 | 203| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 204| value | [SizeOptions](ts-types.md#sizeoptions) \| [ImageSize](ts-appendix-enums.md#imagesize) | 是 | 设置背景图像的高度和宽度。默认保持原图的比例不变。<br/>width和height取值范围： [0, +∞)<br/>**说明：** <br/>width和height均设置为小于或等于0的值时，按值为0显示。当width和height中只有一个值未设置或者设置为小于等于0的值时，另一个会根据图片原始宽高比进行调整。 | 205 206**返回值：** 207 208| 类型 | 说明 | 209| ------ | ------------------------ | 210| T | 返回当前组件。 | 211 212## backgroundImagePosition 213 214backgroundImagePosition(value: Position | Alignment): T 215 216设置背景图的位置。当未设置backgroundImagePosition时，组件默认背景图位置为当前组件左上角。 217 218**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 219 220**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 221 222**系统能力：** SystemCapability.ArkUI.ArkUI.Full 223 224**参数：** 225 226| 参数名 | 类型 | 必填 | 说明 | 227| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 228| value | [Position](ts-types.md#position) \| [Alignment](ts-appendix-enums.md#alignment) | 是 | 设置背景图在组件中显示位置，即相对于组件左上角的坐标。<br/> x和y值设置百分比时，偏移量是相对组件自身宽高计算的。 | 229 230**返回值：** 231 232| 类型 | 说明 | 233| ------ | ------------------------ | 234| T | 返回当前组件。 | 235 236## BlurStyle<sup>9+</sup> 237 238模糊样式类型。 239 240**系统能力：** SystemCapability.ArkUI.ArkUI.Full 241 242| 名称 | 值 | 说明 | 243| -------------------- | ------- | --------- | 244| Thin | - | 轻薄材质模糊。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 245| Regular | - | 普通厚度材质模糊。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 246| Thick | - | 厚材质模糊。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 247| BACKGROUND_THIN<sup>10+</sup> | - | 近距景深模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 248| BACKGROUND_REGULAR<sup>10+</sup> | - | 中距景深模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 249| BACKGROUND_THICK<sup>10+</sup> | - | 远距景深模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 250| BACKGROUND_ULTRA_THICK<sup>10+</sup> | - | 超远距景深模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 251| NONE<sup>10+</sup> | - | 关闭模糊。<br/>**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 252| COMPONENT_ULTRA_THIN<sup>11+</sup> | 8 | 组件超轻薄材质模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 253| COMPONENT_THIN<sup>11+</sup> | 9 | 组件轻薄材质模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 254| COMPONENT_REGULAR<sup>11+</sup> | 10 | 组件普通材质模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 255| COMPONENT_THICK<sup>11+</sup> | 11 | 组件厚材质模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 256| COMPONENT_ULTRA_THICK<sup>11+</sup> | 12 | 组件超厚材质模糊。<br/>**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 257 258## SystemAdaptiveOptions<sup>19+</sup> 259 260系统自适应调节参数，系统会默认开启根据芯片算力进行自适应效果调节的能力。 261 262**卡片能力：** 从API version 19开始，该接口支持在ArkTS卡片中使用。 263 264**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 265 266**系统能力：** SystemCapability.ArkUI.ArkUI.Full 267 268| 名称 | 类型 | 必填 | 说明 | 269| ---- | ---- | ---- | -------------------------- | 270| disableSystemAdaptation | boolean | 否 | 系统自适应调节参数，推荐不携带该参数。该参数只影响低算力设备，低算力设备的定义由设备厂商决定。在低芯片算力的设备上，会根据算力和负载等条件，自动决策是否使用低算力的近似效果替代原有效果，比如模糊效果会结合接口中携带的模糊相关参数值及其他低算力处理逻辑，进行自适应效果降级处理。如果想关闭该功能，可以将该标志置为true。<br/>默认值：false | 271 272## backgroundBlurStyle<sup>9+</sup> 273 274backgroundBlurStyle(value: BlurStyle, options?: BackgroundBlurStyleOptions): T 275 276为当前组件提供一种背景材质模糊能力，通过枚举值的方式封装了不同的模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度。 277 278**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 279 280**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 281 282**系统能力：** SystemCapability.ArkUI.ArkUI.Full 283 284**参数：** 285 286| 参数名 | 类型 | 必填 | 说明 | 287| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 288| value | [BlurStyle](#blurstyle9) | 是 | 背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。 | 289| options | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10对象说明) | 否 | 背景模糊选项。 <br/>该参数在ArkTS卡片中，暂不支持使用。 | 290 291**返回值：** 292 293| 类型 | 说明 | 294| ------ | ------------------------ | 295| T | 返回当前组件。 | 296 297## backgroundBlurStyle<sup>18+</sup> 298 299backgroundBlurStyle(style: Optional\<BlurStyle>, options?: BackgroundBlurStyleOptions): T 300 301为当前组件提供一种背景材质模糊能力，通过枚举值的方式封装了不同的模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度。与[backgroundBlurStyle<sup>9+</sup>](#backgroundblurstyle9)相比，style参数新增了对undefined类型的支持。 302 303**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 304 305**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 306 307**系统能力：** SystemCapability.ArkUI.ArkUI.Full 308 309**参数：** 310 311| 参数名 | 类型 | 必填 | 说明 | 312| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 313| style | Optional\<[BlurStyle](#blurstyle9)> | 是 | 背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。<br/>当style的值为undefined时，恢复为默认关闭模糊的背景。 | 314| options | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10对象说明) | 否 | 背景模糊选项。<br/>该参数在ArkTS卡片中，暂不支持使用。 | 315 316**返回值：** 317 318| 类型 | 说明 | 319| ------ | ------------------------ | 320| T | 返回当前组件。 | 321 322> **说明：** 323> 324> 当通过backgroundBlurStyle中的inactiveColor指定背景色时，不建议再通过[backgroundColor](#backgroundcolor)设置背景色。 325 326## backgroundBlurStyle<sup>19+</sup> 327 328backgroundBlurStyle(style: Optional\<BlurStyle>, options?: BackgroundBlurStyleOptions, sysOptions?: SystemAdaptiveOptions): T 329 330为当前组件提供一种背景材质模糊能力，通过枚举值的方式封装了不同的模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度。与[backgroundBlurStyle<sup>18+</sup>](#backgroundblurstyle18)相比，新增了sysOptions参数，即支持系统自适应调节参数。 331 332**卡片能力：** 从API version 19开始，该接口支持在ArkTS卡片中使用。 333 334**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 335 336**系统能力：** SystemCapability.ArkUI.ArkUI.Full 337 338**参数：** 339 340| 参数名 | 类型 | 必填 | 说明 | 341| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 342| style | Optional\<[BlurStyle](#blurstyle9)> | 是 | 背景模糊样式。模糊样式中封装了模糊半径、蒙版颜色、蒙版透明度、饱和度、亮度五个参数。<br/>当style的值为undefined时，恢复为默认关闭模糊的背景。 | 343| options | [BackgroundBlurStyleOptions](#backgroundblurstyleoptions10对象说明) | 否 | 背景模糊选项。<br/>该参数在ArkTS卡片中，暂不支持使用。 | 344| sysOptions | [SystemAdaptiveOptions](#systemadaptiveoptions19) | 否 | 系统自适应调节参数。<br/>默认值：{ disableSystemAdaptation: false } | 345 346**返回值：** 347 348| 类型 | 说明 | 349| ------ | ------------------------ | 350| T | 返回当前组件。 | 351 352> **说明：** 353> 354> 当通过backgroundBlurStyle中的inactiveColor指定背景色时，不建议再通过[backgroundColor](#backgroundcolor)设置背景色。 355 356## backdropBlur 357 358backdropBlur(value: number, options?: BlurOptions): T 359 360为组件添加背景模糊效果，支持自定义设置模糊半径和灰阶参数。 361 362**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 363 364**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 365 366**系统能力：** SystemCapability.ArkUI.ArkUI.Full 367 368**参数：** 369 370| 参数名 | 类型 | 必填 | 说明 | 371| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 372| value | number | 是 | 为当前组件添加背景模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。 | 373| options<sup>11+</sup> | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 374 375**返回值：** 376 377| 类型 | 说明 | 378| ------ | ------------------------ | 379| T | 返回当前组件。 | 380 381## backdropBlur<sup>18+</sup> 382 383backdropBlur(radius: Optional\<number>, options?: BlurOptions): T 384 385为组件添加背景模糊效果，支持自定义设置模糊半径和灰阶参数。与[backdropBlur](#backdropblur)相比，radius参数新增了对undefined类型的支持。 386 387**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 388 389**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 390 391**系统能力：** SystemCapability.ArkUI.ArkUI.Full 392 393**参数：** 394 395| 参数名 | 类型 | 必填 | 说明 | 396| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 397| radius | Optional\<number> | 是 | 为当前组件添加背景模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>当radius的值为undefined时，恢复为默认无模糊的背景。 | 398| options | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 399 400**返回值：** 401 402| 类型 | 说明 | 403| ------ | ------------------------ | 404| T | 返回当前组件。 | 405 406> **说明：** 407> 408> blur和backdropBlur是实时模糊接口，会每帧进行实时渲染，性能负载较高。当模糊内容和模糊半径都不需要变化时，建议使用[静态模糊接口](../../apis-arkgraphics2d/js-apis-effectKit.md#blur)。 409 410## backdropBlur<sup>19+</sup> 411 412backdropBlur(radius: Optional\<number>, options?: BlurOptions, sysOptions?: SystemAdaptiveOptions): T 413 414为组件添加背景模糊效果，支持自定义设置模糊半径和灰阶参数。与[backdropBlur<sup>18+</sup>](#backdropblur18)相比，新增了sysOptions参数，即支持系统自适应调节参数。 415 416**卡片能力：** 从API version 19开始，该接口支持在ArkTS卡片中使用。 417 418**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 419 420**系统能力：** SystemCapability.ArkUI.ArkUI.Full 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 426| radius | Optional\<number> | 是 | 为当前组件添加背景模糊效果，入参为模糊半径，模糊半径越大越模糊，为0时不模糊。<br/>当radius的值为undefined时，恢复为默认无模糊的背景。 | 427| options | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶梯参数。 | 428| sysOptions | [SystemAdaptiveOptions](#systemadaptiveoptions19) | 否 | 系统自适应调节参数。<br/>默认值：{ disableSystemAdaptation: false } | 429 430**返回值：** 431 432| 类型 | 说明 | 433| ------ | ------------------------ | 434| T | 返回当前组件。 | 435 436> **说明：** 437> 438> backgroundBlurStyle、blur和backdropBlur为实时接口，每帧执行实时渲染，性能负载较大。当模糊内容与模糊半径均无需变动时，推荐采用静态模糊接口[blur](../../apis-arkgraphics2d/js-apis-effectKit.md#blur)。最佳实践请参考[图像模糊动效优化-使用场景](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-fuzzy-scene-performance-optimization#section4945532519)。 439 440## backgroundEffect<sup>11+</sup> 441 442backgroundEffect(options: BackgroundEffectOptions): T 443 444设置组件背景属性，包括背景模糊半径、亮度、饱和度和颜色等参数。 445 446**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 447 448**系统能力：** SystemCapability.ArkUI.ArkUI.Full 449 450**参数：** 451 452| 参数名 | 类型 | 必填 | 说明 | 453| ------- | ----------------------------------------------------- | ---- | ------------------------------------------ | 454| options | [BackgroundEffectOptions](#backgroundeffectoptions11) | 是 | 设置组件背景属性包括：饱和度，亮度，颜色。 | 455 456**返回值：** 457 458| 类型 | 说明 | 459| ------ | ------------------------ | 460| T | 返回当前组件。 | 461 462## backgroundEffect<sup>18+</sup> 463 464backgroundEffect(options: Optional\<BackgroundEffectOptions>): T 465 466设置组件背景属性，包括背景模糊半径、亮度、饱和度和颜色等参数。与[backgroundEffect<sup>11+</sup>](#backgroundeffect11 )相比，options参数新增了对undefined类型的支持。 467 468**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 469 470**系统能力：** SystemCapability.ArkUI.ArkUI.Full 471 472**参数：** 473 474| 参数名 | 类型 | 必填 | 说明 | 475| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 476| options | Optional\<[BackgroundEffectOptions](#backgroundeffectoptions11)> | 是 | 设置组件背景属性包括：饱和度，亮度，颜色。<br/>当options的值为undefined时，恢复为无效果的背景。 | 477 478**返回值：** 479 480| 类型 | 说明 | 481| ------ | ------------------------ | 482| T | 返回当前组件。 | 483 484## backgroundEffect<sup>19+</sup> 485 486backgroundEffect(options: Optional\<BackgroundEffectOptions>, sysOptions?: SystemAdaptiveOptions): T 487 488设置组件背景属性，包括背景模糊半径、亮度、饱和度和颜色等参数。与[backgroundEffect<sup>18+</sup>](#backgroundeffect18)相比，新增了sysOptions参数，即支持系统自适应调节参数。 489 490> **说明：** 491> 492> backgroundEffect接口为实时接口，每帧对模糊等效果执行实时渲染，性能负载较大。当组件背景模糊效果无需变动时，推荐采用静态模糊接口[blur](../../apis-arkgraphics2d/js-apis-effectKit.md#blur)实现模糊效果。最佳实践请参考：[图像模糊动效优化-使用场景](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-fuzzy-scene-performance-optimization#section4945532519)。 493 494**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 495 496**系统能力：** SystemCapability.ArkUI.ArkUI.Full 497 498**参数：** 499 500| 参数名 | 类型 | 必填 | 说明 | 501| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 502| options | Optional\<[BackgroundEffectOptions](#backgroundeffectoptions11)> | 是 | 设置组件背景属性包括：饱和度，亮度，颜色。<br/>当options的值为undefined时，恢复为无效果的背景。 | 503| sysOptions | [SystemAdaptiveOptions](#systemadaptiveoptions19) | 否 | 系统自适应调节参数。<br/>默认值：{ disableSystemAdaptation: false } | 504 505**返回值：** 506 507| 类型 | 说明 | 508| ------ | ------------------------ | 509| T | 返回当前组件。 | 510 511## BackgroundEffectOptions<sup>11+</sup> 512 513背景效果参数。 514 515**系统能力：** SystemCapability.ArkUI.ArkUI.Full 516 517| 名称 | 类型 | 必填 | 说明 | 518| ---- | ---- | ---- | -------------------------- | 519| radius | number | 是 | 模糊半径，取值范围：[0, +∞)，默认为0。 <br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 520| saturation | number | 否 | 饱和度，取值范围：[0, +∞)，默认为1。推荐取值范围：[0, 50]。 <br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 521| brightness | number | 否 | 亮度，取值范围：[0, +∞)，默认为1。推荐取值范围：[0, 2]。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 522| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 颜色，默认透明色。<br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 523| adaptiveColor | [AdaptiveColor](ts-universal-attributes-foreground-blur-style.md#adaptivecolor10枚举说明) | 否 | 背景模糊效果使用的取色模式,默认为DEFAULT。使用AVERAGE时color必须带有透明度，取色模式才生效。 <br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 524| blurOptions | [BlurOptions](ts-universal-attributes-foreground-blur-style.md#bluroptions11) | 否 | 灰阶模糊参数，默认为[0,0]。 <br/> **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 525| policy<sup>14+</sup> | [BlurStyleActivePolicy](#blurstyleactivepolicy14) | 否 | 模糊激活策略。<br/> 默认值：BlurStyleActivePolicy.ALWAYS_ACTIVE <br/> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。| 526| inactiveColor<sup>14+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 模糊不生效时使用的背景色。该参数需配合policy参数使用。当policy使模糊失效时，控件模糊效果会被移除，如果设置了inactiveColor会使用inactiveColor作为控件背景色。<br/> **原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 527 528## backgroundImageResizable<sup>12+</sup> 529 530backgroundImageResizable(value: ResizableOptions): T 531 532设置背景图在拉伸时可调整大小的图像选项。 533 534设置合法的ResizableOptions时，[backgroundImage](#backgroundimage)属性中的repeat参数设置不生效。 535 536当设置top+bottom大于原图的高或者left+right大于原图的宽时，ResizableOptions属性设置不生效。 537 538**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 539 540**系统能力：** SystemCapability.ArkUI.ArkUI.Full 541 542**参数：** 543 544| 参数名 | 类型 | 必填 | 说明 | 545| ------ | --------------------------------------- | ---- | -------------------------------- | 546| value | [ResizableOptions](ts-basic-components-image.md#resizableoptions11) | 是 | 图像拉伸时可调整大小的图像选项。 | 547 548**返回值：** 549 550| 类型 | 说明 | 551| ------ | ------------------------ | 552| T | 返回当前组件。 | 553 554## BackgroundBlurStyleOptions<sup>10+</sup>对象说明 555 556继承自[BlurStyleOptions](ts-universal-attributes-foreground-blur-style.md#blurstyleoptions)。 557 558**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 559 560**系统能力：** SystemCapability.ArkUI.ArkUI.Full 561 562| 名称 | 类型 | 只读 | 可选 | 说明 | 563| ------ | ------------------------------------------------------------ | ---- | ---- |---------------------------------------------------- | 564| policy<sup>14+</sup> | [BlurStyleActivePolicy](#blurstyleactivepolicy14) | 否 | 是 | 模糊激活策略。<br/> 默认值：BlurStyleActivePolicy.ALWAYS_ACTIVE <br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 565| inactiveColor<sup>14+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 模糊不生效时使用的背景色。该参数需配合policy参数使用。当policy使模糊失效时，控件模糊效果会被移除，如果设置了inactiveColor会使用inactiveColor作为控件背景色。<br/>**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 | 566 567## BlurStyleActivePolicy<sup>14+</sup> 568 569**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 570 571**系统能力**：SystemCapability.ArkUI.ArkUI.Full 572 573| 名称 | 值|说明 | 574| ------ | ----------------------------- |----------------------------- | 575| FOLLOWS_WINDOW_ACTIVE_STATE| 0|模糊效果跟随窗口焦点状态变化，非焦点不模糊，焦点模糊。| 576| ALWAYS_ACTIVE | 1|一直有模糊效果。| 577| ALWAYS_INACTIVE |2 |一直无模糊效果。| 578 579## backgroundBrightness<sup>12+</sup> 580 581backgroundBrightness(params: BackgroundBrightnessOptions): T 582 583设置组件背景提亮效果。 584 585**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 586 587**系统能力：** SystemCapability.ArkUI.ArkUI.Full 588 589**参数：** 590 591| 参数名 | 类型 | 必填 | 说明 | 592| ------ | ------------------------------------------------------------ | ---- | ---------------------------------------------------- | 593| params | [BackgroundBrightnessOptions](#backgroundbrightnessoptions12对象说明) | 是 | 设置组件背景提亮效果，包括：亮度变化速率，提亮程度。 | 594 595**返回值：** 596 597| 类型 | 说明 | 598| ------ | ------------------------ | 599| T | 返回当前组件。 | 600 601## backgroundBrightness<sup>18+</sup> 602 603backgroundBrightness(options: Optional\<BackgroundBrightnessOptions>): T 604 605设置组件背景提亮效果。与[backgroundBrightness<sup>12+</sup>](#backgroundbrightness12)相比，options参数新增了对undefined类型的支持。 606 607**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 608 609**系统能力：** SystemCapability.ArkUI.ArkUI.Full 610 611**参数：** 612 613| 参数名 | 类型 | 必填 | 说明 | 614| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 615| options | Optional\<[BackgroundBrightnessOptions](#backgroundbrightnessoptions12对象说明)> | 是 | 设置组件背景提亮效果，包括：亮度变化速率，提亮程度。<br/>当options的值为undefined时，恢复为无提亮效果的背景。 | 616 617**返回值：** 618 619| 类型 | 说明 | 620| ------ | ------------------------ | 621| T | 返回当前组件。 | 622 623## BackgroundBrightnessOptions<sup>12+</sup>对象说明 624 625背景亮度选项。 626 627**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 628 629**系统能力：** SystemCapability.ArkUI.ArkUI.Full 630 631| 名称 | 类型 | 必填 | 说明 | 632| ------------- | ------ | ---- | ------------------------------------------------------------ | 633| rate | number | 是 | 亮度变化速率。亮度变化速率越大，提亮程度下降速度越快。若rate为0，则lightUpDegree将不生效，即不会产生任何提亮效果。<br/>默认值：0.0 <br/>取值范围：(0.0, +∞) | 634| lightUpDegree | number | 是 | 提亮程度。提亮程度越大，亮度提升程度越大。<br/> 默认值：0.0 <br/>取值范围：[-1.0, 1.0] | 635 636> **说明：** 637> 638> 对于组件背景内容，每个像素自身的亮度（灰阶值）的计算公式为： 639> `Y = （0.299R + 0.587G + 0.114B）/ 255.0`（R、G、B分别表示像素红色、绿色和蓝色通道的值，Y表示灰阶值），通过上述公式将像素点的灰阶值归一化至0~1的范围。 640> 每个像素的亮度提升计算公式为：`Δ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`。 641 642## 示例 643 644### 示例1（设置背景基础样式） 645 646该示例通过配置backgroundColor、backgroundImage、backgroundImageSize和backgroundImagePosition设置背景的基础样式。 647 648```ts 649// xxx.ets 650@Entry 651@Component 652struct BackgroundExample { 653 654 build() { 655 Column({ space: 5 }) { 656 Text('background color').fontSize(9).width('90%').fontColor(0xCCCCCC) 657 Row().width('90%').height(50).backgroundColor(0xE5E5E5).border({ width: 1 }) 658 659 Text('background image repeat along X').fontSize(9).width('90%').fontColor(0xCCCCCC) 660 Row() 661 //$r('app.media.image')需要替换为开发者所需的图像资源文件。 662 .backgroundImage($r('app.media.image'), ImageRepeat.X) 663 .backgroundImageSize({ width: '250px', height: '140px' }) 664 .width('90%') 665 .height(70) 666 .border({ width: 1 }) 667 668 Text('background image repeat along Y').fontSize(9).width('90%').fontColor(0xCCCCCC) 669 Row() 670 //$r('app.media.image')需要替换为开发者所需的图像资源文件。 671 .backgroundImage($r('app.media.image'), ImageRepeat.Y) 672 .backgroundImageSize({ width: '500px', height: '120px' }) 673 .width('90%') 674 .height(100) 675 .border({ width: 1 }) 676 677 Text('background image size').fontSize(9).width('90%').fontColor(0xCCCCCC) 678 Row() 679 .width('90%').height(150) 680 //$r('app.media.image')需要替换为开发者所需的图像资源文件。 681 .backgroundImage($r('app.media.image'), ImageRepeat.NoRepeat) 682 .backgroundImageSize({ width: 1000, height: 500 }) 683 .border({ width: 1 }) 684 685 Text('background fill the box(Cover)').fontSize(9).width('90%').fontColor(0xCCCCCC) 686 // 不保证图片完整的情况下占满盒子 687 Row() 688 .width(200) 689 .height(50) 690 //$r('app.media.image')需要替换为开发者所需的图像资源文件。 691 .backgroundImage($r('app.media.image'), ImageRepeat.NoRepeat) 692 .backgroundImageSize(ImageSize.Cover) 693 .border({ width: 1 }) 694 695 Text('background fill the box(Contain)').fontSize(9).width('90%').fontColor(0xCCCCCC) 696 // 保证图片完整的情况下放到最大 697 Row() 698 .width(200) 699 .height(50) 700 //$r('app.media.image')需要替换为开发者所需的图像资源文件。 701 .backgroundImage($r('app.media.image'), ImageRepeat.NoRepeat) 702 .backgroundImageSize(ImageSize.Contain) 703 .border({ width: 1 }) 704 705 Text('background image position').fontSize(9).width('90%').fontColor(0xCCCCCC) 706 Row() 707 .width(100) 708 .height(50) 709 //$r('app.media.image')需要替换为开发者所需的图像资源文件。 710 .backgroundImage($r('app.media.image'), ImageRepeat.NoRepeat) 711 .backgroundImageSize({ width: 1000, height: 560 }) 712 .backgroundImagePosition({ x: -500, y: -300 }) 713 .border({ width: 1 }) 714 } 715 .width('100%').height('100%').padding({ top: 5 }) 716 } 717} 718``` 719 720 721 722### 示例2（设置背景模糊样式） 723 724该示例通过backgroundBlurStyle设置背景模糊样式。 725 726```ts 727// xxx.ets 728@Entry 729@Component 730struct BackgroundBlurStyleDemo { 731 build() { 732 Column() { 733 Row() { 734 Text("Thin Material") 735 } 736 .width('50%') 737 .height('50%') 738 .backgroundBlurStyle(BlurStyle.Thin, 739 { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 }) 740 .position({ x: '15%', y: '30%' }) 741 } 742 .height('100%') 743 .width('100%') 744 .backgroundImage($r('app.media.bg')) 745 .backgroundImageSize(ImageSize.Cover) 746 } 747} 748``` 749 750 751 752### 示例3（设置组件背景） 753 754该示例通过background设置组件背景。 755 756```ts 757// xxx.ets 758@Entry 759@Component 760struct BackgroundExample { 761 @Builder renderBackground() { 762 Column() { 763 Progress({value : 50}) 764 } 765 } 766 767 build() { 768 Column() { 769 Text("content") 770 .width(100) 771 .height(40) 772 .fontColor("#FFF") 773 .position({x:50, y:80}) 774 .textAlign(TextAlign.Center) 775 .backgroundColor(Color.Green) 776 } 777 .width(200).height(200) 778 .background(this.renderBackground) 779 .backgroundColor(Color.Gray) 780 } 781} 782``` 783 784 785 786### 示例4（设置组件背景提亮效果） 787 788该示例通过backgroundBrightness设置组件背景提亮效果。 789 790```ts 791// xxx.ets 792@Entry 793@Component 794struct BackgroundBrightnessDemo { 795 build() { 796 Column() { 797 Row() { 798 Text("BackgroundBrightness") 799 } 800 .width(200) 801 .height(100) 802 .position({ x: 100, y: 100 }) 803 .backgroundBlurStyle(BlurStyle.Thin, { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT}) 804 .backgroundBrightness({rate:0.5,lightUpDegree:0.5}) // 背景提亮效果 805 } 806 .width('100%') 807 .height('100%') 808 .backgroundImage($r('app.media.image')) 809 .backgroundImageSize(ImageSize.Cover) 810 } 811} 812``` 813 814效果图如下： 815 816rate和lightUpDegree参数值为0.5,0.5： 817 818 819 820修改rate和lightUpDegree参数值为0.5,-0.1： 821 822 823 824去掉backgroundBrightness的设置，效果如下： 825 826 827 828### 示例5（设置模糊属性） 829 830该示例提供了模糊属性的实现方法。通过blur设置内容模糊，通过backdropBlur设置背景模糊。 831 832```ts 833// xxx.ets 834@Entry 835@Component 836struct BlurEffectsExample { 837 build() { 838 Column({ space: 10 }) { 839 // 对字体进行模糊 840 Text('font blur').fontSize(15).fontColor(0xCCCCCC).width('90%') 841 Flex({ alignItems: ItemAlign.Center }) { 842 Text('original text').margin(10) 843 Text('blur text') 844 .blur(5).margin(10) 845 Text('blur text') 846 .blur(10, undefined).margin(10) // 内容模糊半径为5，禁用系统自适应优化策略。 847 Text('blur text') 848 .blur(15).margin(10) 849 }.width('90%').height(40) 850 .backgroundColor(0xF9CF93) 851 852 853 // 对背景进行模糊 854 Text('backdropBlur').fontSize(15).fontColor(0xCCCCCC).width('90%') 855 Text() 856 .width('90%') 857 .height(40) 858 .fontSize(16) 859 .backdropBlur(3) 860 .backgroundImage($r('app.media.image')) 861 .backgroundImageSize({ width: 1200, height: 160 }) 862 }.width('100%').margin({ top: 5 }) 863 } 864} 865``` 866 867 868 869### 示例6（设置文字异形模糊效果） 870 871该示例通过blendMode和backgroundEffect实现文字异形模糊效果。<br/> 872如果出现漏线问题，开发者应首先确保两个blendMode所在组件大小严格相同。如果确认相同，可能是组件边界落在浮点数坐标上导致，可尝试设置[pixelRound](ts-universal-attributes-pixelRoundForComponent.md#pixelround)通用属性，使产生的白线、暗线两侧的组件边界对齐到整数像素坐标上。 873 874```ts 875// xxx.ets 876@Entry 877@Component 878struct Index { 879 @State shColor: Color = Color.White; 880 @State sizeDate: number = 20; 881 @State rVal: number = 255; 882 @State gVal: number = 255; 883 @State bVal: number = 255; 884 @State aVal: number = 0.1; 885 @State rad: number = 40; 886 @State satVal: number = 0.8; 887 @State briVal: number = 1.5; 888 build() { 889 Stack() { 890 Image($r('app.media.image')) 891 Column() { 892 Column({ space: 0 }) { 893 Column() { 894 Text('11') 895 .fontSize(144) 896 .fontWeight(FontWeight.Bold) 897 .fontColor('rgba(255,255,255,1)') 898 .fontFamily('HarmonyOS-Sans-Digit') 899 .maxLines(1) 900 .lineHeight(120 * 1.25) 901 .height(120 * 1.25) 902 .letterSpacing(4 * 1.25) 903 Text('42') 904 .fontSize(144) 905 .fontWeight(FontWeight.Bold) 906 .fontColor('rgba(255,255,255,1)') 907 .fontFamily('HarmonyOS-Sans-Digit') 908 .maxLines(1) 909 .lineHeight(120 * 1.25) 910 .height(120 * 1.25) 911 .letterSpacing(4 * 1.25) 912 .shadow({ 913 color: 'rgba(0,0,0,0)', 914 radius: 20, 915 offsetX: 0, 916 offsetY: 0 917 }) 918 Row() { 919 Text('10月16日') 920 .fontSize(this.sizeDate) 921 .height(22) 922 .fontWeight('medium') 923 .fontColor('rgba(255,255,255,1)') 924 Text('星期一') 925 .fontSize(this.sizeDate) 926 .height(22) 927 .fontWeight('medium') 928 .fontColor('rgba(255,255,255,1)') 929 } 930 } 931 .blendMode(BlendMode.DST_IN, BlendApplyType.OFFSCREEN) 932 .pixelRound({ 933 start: PixelRoundCalcPolicy.FORCE_FLOOR , 934 top: PixelRoundCalcPolicy.FORCE_FLOOR , 935 end: PixelRoundCalcPolicy.FORCE_CEIL, 936 bottom: PixelRoundCalcPolicy.FORCE_CEIL 937 }) 938 } 939 .blendMode(BlendMode.SRC_OVER, BlendApplyType.OFFSCREEN) 940 .backgroundEffect({ 941 radius: this.rad, 942 saturation: this.satVal, 943 brightness: this.briVal, 944 color: this.getVolumeDialogWindowColor() 945 }) 946 .justifyContent(FlexAlign.Center) 947 .pixelRound({ 948 start: PixelRoundCalcPolicy.FORCE_FLOOR , 949 top: PixelRoundCalcPolicy.FORCE_FLOOR , 950 end: PixelRoundCalcPolicy.FORCE_CEIL, 951 bottom: PixelRoundCalcPolicy.FORCE_CEIL 952 }) 953 } 954 } 955 } 956 getVolumeDialogWindowColor(): ResourceColor | string { 957 return `rgba(${this.rVal.toFixed(0)}, ${this.gVal.toFixed(0)}, ${this.bVal.toFixed(0)}, ${this.aVal.toFixed(0)})`; 958 } 959} 960``` 961 962 963 964### 示例7（模糊效果对比） 965 966该示例对比了backgroundEffect、backDropBlur和backgroundBlurStyle三种不同的模糊效果。 967 968```ts 969// xxx.ets 970@Entry 971@Component 972struct BackGroundBlur { 973 private imageSize: number = 150; 974 975 build() { 976 Column({ space: 5 }) { 977 // backgroundBlurStyle通过枚举值的方式设置模糊参数 978 Stack() { 979 Image($r('app.media.test')) 980 .width(this.imageSize) 981 .height(this.imageSize) 982 Column() 983 .width(this.imageSize) 984 .height(this.imageSize) 985 .backgroundBlurStyle(BlurStyle.Thin) 986 } 987 988 // backgroundEffect 可以自定义设置 模糊半径，亮度，饱和度等参数 989 Stack() { 990 Image($r('app.media.test')) 991 .width(this.imageSize) 992 .height(this.imageSize) 993 Column() 994 .width(this.imageSize) 995 .height(this.imageSize) 996 .backgroundEffect({ radius: 20, brightness: 0.6, saturation: 15 }) 997 } 998 999 // backdropBlur 只能设置模糊半径和灰阶参数 1000 Stack() { 1001 Image($r('app.media.test')) 1002 .width(this.imageSize) 1003 .height(this.imageSize) 1004 Column() 1005 .width(this.imageSize) 1006 .height(this.imageSize) 1007 .backdropBlur(20, { grayscale: [30, 50] }) 1008 } 1009 } 1010 .width('100%') 1011 .padding({ top: 5 }) 1012 } 1013} 1014``` 1015 1016 1017 1018### 示例8（设置P3色域背景效果） 1019 1020该示例通过backgroundColor设置P3色域背景效果。 1021 1022```ts 1023// xxx.ets 1024// 设置P3色域时需要在ets/entryability/EntryAbility.ets中，通过setColorSpace接口将当前窗口设置为广色域。 1025import { ColorMetrics } from '@kit.ArkUI'; 1026 1027@Entry 1028@Component 1029struct P3BackgroundDemo { 1030 @State p3Color: ColorMetrics = ColorMetrics.colorWithSpace(ColorSpace.DISPLAY_P3, 0, 0.3, 0.8, 1); 1031 1032 build() { 1033 Column({ space: 5 }) { 1034 Text('background color with colorMetrics').fontSize(9).width('90%').fontColor(0xCCCCCC) 1035 Row().width('90%').height(50).backgroundColor(this.p3Color) 1036 } 1037 .width('100%') 1038 .height('100%') 1039 } 1040} 1041``` 1042 1043 1044 1045### 示例9（设置组件背景扩展） 1046 1047该示例通过background实现组件背景扩展到父组件的安全区。 1048 1049```ts 1050import { LengthMetrics } from '@kit.ArkUI'; 1051 1052@Entry 1053@Component 1054struct BackgroundExtension { 1055 @Builder 1056 myImages() { 1057 Column() { 1058 Image($r('app.media.startIcon')) 1059 .width('100%') 1060 .height('100%') 1061 } 1062 } 1063 1064 build() { 1065 Column({space: 10}) { 1066 Stack() { 1067 // CustomBuilder类型的背景设置了ignoresLayoutSafeAreaEdges属性，背景扩展到父组件安全区 1068 Column() 1069 .size({ width: '100%', height: '100%' }) 1070 .border({ width: 1, color: Color.Red }) 1071 .background( 1072 this.myImages(), 1073 { align: Alignment.Center , ignoresLayoutSafeAreaEdges: [ LayoutSafeAreaEdge.START, LayoutSafeAreaEdge.TOP ] } 1074 ) 1075 } 1076 .size({ width: 300, height: 300 }) 1077 .backgroundColor('#004aaf') 1078 .safeAreaPadding(LengthMetrics.vp(50)) 1079 1080 Stack() { 1081 // ResourceColor类型的背景未设置ignoresLayoutSafeAreaEdges属性，背景默认扩展到父组件安全区 1082 Column() 1083 .size({ width: '100%', height: '100%' }) 1084 .border({ width: 1, color: Color.Red }) 1085 .background('#d5d5d5', { align: Alignment.Center }) 1086 } 1087 .size({ width: 300, height: 300 }) 1088 .backgroundColor('#707070') 1089 .safeAreaPadding(LengthMetrics.vp(50)) 1090 } 1091 .margin(10) 1092 } 1093} 1094``` 1095 1096
