harmony 鸿蒙组件内容模糊

2025-06-12
浏览 (3)

组件内容模糊

为当前组件添加内容模糊效果。

说明：

从API version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

foregroundBlurStyle

foregroundBlurStyle(value: BlurStyle, options?: ForegroundBlurStyleOptions): T

为当前组件提供内容模糊能力。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	BlurStyle	是	内容模糊样式。
options	ForegroundBlurStyleOptions	否	可选参数，内容模糊选项。

返回值：

类型	说明
T	返回当前组件。

foregroundBlurStyle¹⁸⁺

foregroundBlurStyle(style: Optional<BlurStyle>, options?: ForegroundBlurStyleOptions): T

为当前组件提供内容模糊能力。与foregroundBlurStyle相比，style参数新增了对undefined类型的支持。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
style	Optional<BlurStyle>	是	内容模糊样式。当style的值为undefined时，恢复为无模糊的内容。
options	ForegroundBlurStyleOptions	否	可选参数，内容模糊选项。

返回值：

类型	说明
T	返回当前组件。

foregroundBlurStyle¹⁹⁺

foregroundBlurStyle(style: Optional<BlurStyle>, options?: ForegroundBlurStyleOptions, sysOptions?: SystemAdaptiveOptions): T

为当前组件提供内容模糊能力。与foregroundBlurStyle¹⁸⁺相比，新增了sysOptions参数，即支持系统自适应调节参数。

原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
style	Optional<BlurStyle>	是	内容模糊样式。当style的值为undefined时，恢复为无模糊的内容。
options	ForegroundBlurStyleOptions	否	可选参数，内容模糊选项。
sysOptions	SystemAdaptiveOptions	否	系统自适应调节参数。默认值：{ disableSystemAdaptation: false }

返回值：

类型	说明
T	返回当前组件。

ForegroundBlurStyleOptions对象说明

继承自BlurStyleOptions

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

BlurStyleOptions

内容模糊选项。

名称	类型	必填	说明
colorMode	ThemeColorMode	否	内容模糊效果使用的深浅色模式。默认值：ThemeColorMode.SYSTEM 原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
adaptiveColor	AdaptiveColor	否	内容模糊效果使用的取色模式。默认值：AdaptiveColor.DEFAULT 原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
blurOptions¹¹⁺	BlurOptions	否	灰阶模糊参数。默认值：grayscale: [0,0] 原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
scale¹²⁺	number	否	内容模糊效果程度。默认值：1.0 取值范围：[0.0, 1.0] 1.0表示模糊程度最高。 0.0表示模糊程度最低。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

AdaptiveColor¹⁰⁺枚举说明

取色模式。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	说明
DEFAULT	不使用取色模糊。使用默认的颜色作为蒙版颜色。采用非DEFAULT方式较耗时。
AVERAGE	使用取色模糊。将取色区域的颜色平均值作为蒙版颜色。

BlurOptions¹¹⁺

灰阶模糊参数。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
grayscale	[number, number]	是	灰阶模糊参数，两参数取值范围均为[0,127] 。对图像中的黑白色进行色阶调整，使其趋于灰色更为柔和美观，对图像中的彩色调整没有效果。参数一表示对黑色的提亮程度，参数二表示对白色的压暗程度，参数值越大调整效果越明显（黑白色变得越灰），有效值范围0-127。例如：设置参数为（20,20），图片中的黑色像素RGB:[0, 0, 0]会调整为[20,20,20]，白色像素RGB:[255,255,255]会调整为[235,235,235]（255-20），图像中的彩色像素维持不变。

示例

该示例主要演示通过foregroundBlurStyle为图片设置内容模糊效果。

// xxx.ets
@Entry
@Component
struct ForegroundBlurStyleDemo {
  build() {
    Column() {
      Text('Thin Material').fontSize(30).fontColor(0xCCCCCC)
      Image($r('app.media.bg'))
        .width(300)
        .height(350)
        .foregroundBlurStyle(BlurStyle.Thin,
          { colorMode: ThemeColorMode.LIGHT, adaptiveColor: AdaptiveColor.DEFAULT, scale: 1.0 })
    }
    .height('100%')
    .width('100%')
  }
}

zh-cn_image_background_blur_style