HarmonyOS6 foregroundBlurStyle 通用属性使用指南

文章目录

- [1. 核心特性](#1. 核心特性)
- [2. foregroundBlurStyle 完整参数说明](#2. foregroundBlurStyle 完整参数说明)
- - [2.1 基础语法](#2.1 基础语法)
  - [2.2 BlurStyle（模糊强度）](#2.2 BlurStyle（模糊强度）)
  - [2.3 ForegroundBlurStyleOptions（可选配置）](#2.3 ForegroundBlurStyleOptions（可选配置）)
- [3. 完整示例代码解析](#3. 完整示例代码解析)
- - [3.1 代码结构说明](#3.1 代码结构说明)
- [4. 运行前置条件](#4. 运行前置条件)
- - [4.1 环境配置](#4.1 环境配置)
  - [4.2 运行方式](#4.2 运行方式)
- 总结

1. 核心特性

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

2. foregroundBlurStyle 完整参数说明

2.1 基础语法

typescript 复制代码

foregroundBlurStyle(style: BlurStyle, options?: ForegroundBlurStyleOptions)

2.2 BlurStyle（模糊强度）

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

2.3 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为最大强度）

3. 完整示例代码解析

3.1 代码结构说明

以下代码实现了 foregroundBlurStyle 属性的多场景演示，包含单组件模糊、多强度对比等核心功能，使用本地图片避免网络加载问题，适配 ArkTS 严格类型检查规则：

typescript 复制代码

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

      // 核心：使用本地图片 + foregroundBlurStyle
      Image($r('app.media.bg')) // 替换为你的本地图片名
        .width(300)
        .height(350)
        .foregroundBlurStyle(
          2,                          // BlurStyle.Regular (常规模糊)
          {
            colorMode: 1,             // ThemeColorMode.LIGHT
            adaptiveColor: 0,         // AdaptiveColor.DEFAULT
            scale: 1.0
          }
        );

      // 多效果对比演示（使用本地小图）
      Text('Blur Style Comparison').fontSize(18).margin(10);
      Row({ space: 12 }) {
        // 无模糊
        Image($r('app.media.bg'))
          .width(80)
          .height(80);

        // Thin 模糊
        Image($r('app.media.bg'))
          .width(80)
          .height(80)
          .foregroundBlurStyle(0);

        // Regular 模糊
        Image($r('app.media.bg'))
          .width(80)
          .height(80)
          .foregroundBlurStyle(2);

        // Thick 模糊
        Image($r('app.media.bg'))
          .width(80)
          .height(80)
          .foregroundBlurStyle(3);
      }
    }
    .width('100%')
    .height('100%')
    .justifyContent(1) // 居中显示
    .padding(10);
  }
}

运行效果如下：

4. 运行前置条件

4.1 环境配置

DevEco Studio 版本 ≥ 4.0。

工程 API 版本配置（entry/build-profile.json5）：

json 复制代码

{
  "apiType": "stageMode",
  "compileSdkVersion": 10,
  "compatibleSdkVersion": 10
}

本地图片资源：将图片文件（如 bg.jpg/png）放入 entry/src/main/resources/base/media 目录。

4.2 运行方式

优先选择 API 10+ 远程模拟器/真机 运行（预览器偶有兼容性问题）。
运行前点击 DevEco Studio 右上角 Sync Now 同步资源。

总结

foregroundBlurStyle 是 HarmonyOS API 10+ 新增的前景模糊属性，支持4种模糊强度和主题色适配。
示例代码使用本地图片避免网络加载问题，可直接复用至实际项目。
数字值替代枚举的写法适配严格类型检查，无导入报错风险。
模糊效果仅作用于组件自身内容，区别于背景模糊类属性，是实现视觉层次感的重要手段。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！