HarmonyOS ArkTS 前景模糊样式 foregroundBlurStyle 详解

核心特性

特性	说明
适用版本	HarmonyOS API 10+（Stage 模型）
支持组件	Image、Text、Button、Column、Row、Stack 等通用组件
核心能力	为组件内容添加前景模糊，支持 4 种模糊强度、主题色模式适配
类型要求	参数支持数字枚举替代（避免导入报错），适配严格类型检查

完整参数说明

基础语法

foregroundBlurStyle(style: BlurStyle, options?: ForegroundBlurStyleOptions)

模糊强度 (BlurStyle)

数字值	枚举值	说明
0	BlurStyle.Thin	轻薄模糊（最弱）
1	BlurStyle.Light	轻度模糊
2	BlurStyle.Regular	常规模糊（推荐）
3	BlurStyle.Thick	厚重模糊（最强）

可选配置 (ForegroundBlurStyleOptions)

| 参数名 | 数字值 | 枚举值 | 说明 | | --- | --- | --- | | colorMode | 0 | ThemeColorMode.DARK | 深色主题模式 | | colorMode | 1 | ThemeColorMode.LIGHT | 浅色主题模式（默认） | | adaptiveColor | 0 | AdaptiveColor.DEFAULT | 默认自适应颜色（推荐） | | adaptiveColor | 1 | AdaptiveColor.PRIMARY | 主色调自适应 | | adaptiveColor | 2 | AdaptiveColor.SECONDARY | 次色调自适应 | | scale | number | - | 模糊强度缩放比例，取值范围 0~1（1 为最大强度） |

代码实战解析

下面是一个完整的示例结构，演示了如何结合本地资源使用 foregroundBlurStyle。这里特意使用了本地图片路径来避免网络加载的不确定性，同时适配了 ArkTS 的严格类型检查。

@Entry
@Component
struct ForegroundBlurStyleDemo {
  build() {
    Column() {
      Text('Foreground Blur Style Demo')
        .fontSize(24)
        .()

      
      ($r())
        .()
        .()
        .(
          .,
          {
            : .,
            : .,
            : 
          }
        )

      
      ().().()
      ({ :  }) {
        
        ($r()).().()
        
        ($r()).().().(.)
        
        ($r()).().().(.)
        
        ($r()).().().(.)
      }
    }
    .()
    .()
    .(.)
    .()
  }
}