@bingtang-rn/react-native-blur-view for HarmonyOS

本项目基于 @danielsaraldi/react-native-blur-view 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 1.0.0 | 3.0.0 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/react-native-blur-view

使用

import { BlurView, VibrancyView, BlurTarget } from '@danielsaraldi/react-native-blur-view';

// 基本模糊效果
<BlurView type="light" radius={10} style={styles.blur}>
  <Text>Blurred background</Text>
</BlurView>

// Vibrancy 效果（鸿蒙端降级为模糊 View）
<VibrancyView type="material" effectStyle="label" radius={20}>
  <Text>Vibrant text</Text>
</VibrancyView>

// 模糊目标（鸿蒙端降级为普通 View）
<BlurTarget ref={targetRef} style={styles.target}>
  <Text>Target area</Text>
</BlurTarget>

import 时使用原库名 '@danielsaraldi/react-native-blur-view'，而非鸿蒙包名。

平台差异：

• HarmonyOS 上 VibrancyView 降级为带模糊效果的 View（无 iOS UIVibrancyEffect），effectStyle 映射到不同 BlurStyle
• HarmonyOS 上 BlurTarget 降级为普通 View，blurTarget / targetId 属性被忽略（backgroundBlurStyle 自动模糊背后内容）
• downscaleFactor 属性在 HarmonyOS 上被忽略（Android 专用性能参数）
• reducedTransparencyFallbackColor 属性在 HarmonyOS 上被忽略（iOS 无障碍特性）
• androidColor 属性在 HarmonyOS 上被忽略（Android 专用）
• BlurType 的 -light/-dark 后缀变体在 HarmonyOS 上映射到同一 BlurStyle 基础值（不区分色彩模式变体）

权限要求：

• 无需任何权限

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-blur-view": "file:../../node_modules/@bingtang-rn/react-native-blur-view/harmony/blur_view.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-blur-view/src/main/cpp" ./blur_view)

target_link_libraries(rnoh_app PUBLIC blur_view)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "BlurViewPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<BlurViewPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { BlurViewPackage } from '@bingtang-rn/react-native-blur-view/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new BlurViewPackage(ctx),
  ];
}

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | BlurView | 模糊效果组件 | type: BlurType, radius: number, overlayColor: ColorValue | — | ✅ 完全支持 | | BlurView.type | 模糊类型（21 种） | BlurType | — | ✅ 完全支持 | | BlurView.radius | 模糊半径 0~100 | number (默认 10) | — | ✅ 完全支持 | | BlurView.overlayColor | 自定义叠加色 | ColorValue | — | ✅ 完全支持 | | BlurView.downscaleFactor | 缩小因子 | number (默认 6) | — | ⚠️ 鸿蒙端忽略（Android 专用） | | BlurView.reducedTransparencyFallbackColor | 减少透明度替代色 | ColorValue (默认 'white') | — | ⚠️ 鸿蒙端忽略（iOS 专用） | | BlurView.androidColor | Android 叠加色 | ColorValue | — | ⚠️ 鸿蒙端忽略（Android 专用） | | BlurView.blurTarget | 关联 BlurTarget | RefObject<View> | — | ⚠️ 鸿蒙端忽略（Android 专用） | | VibrancyView | 活力模糊组件 | type, effectStyle, radius, overlayColor | — | ⚠️ 部分支持 | | VibrancyView.type | 模糊类型 | BlurType (默认 'light') | — | ✅ 完全支持 | | VibrancyView.effectStyle | 活力效果样式 | EffectStyle (默认 'label') | — | ⚠️ 部分支持（降级为不同 BlurStyle 映射） | | VibrancyView.radius | 模糊半径 | number (默认 10) | — | ✅ 完全支持 | | VibrancyView.overlayColor | 自定义叠加色 | ColorValue | — | ✅ 完全支持 | | VibrancyView.reducedTransparencyFallbackColor | 减少透明度替代色 | ColorValue (默认 'white') | — | ⚠️ 鸿蒙端忽略（iOS 专用） | | BlurTarget | 模糊目标组件 | ViewProps | — | ⚠️ 部分支持（降级为普通 View） |

平台差异

• VibrancyView：HarmonyOS 无 UIVibrancyEffect 概念，effectStyle 映射到 BlurStyle 枚举近似实现
• BlurTarget：HarmonyOS backgroundBlurStyle 直接模糊组件背景，无需指定目标区域

未实现功能

| API | 原因 | |-----|------| | BlurView.downscaleFactor | Android 专用性能参数，鸿蒙 backdropBlur 无需此参数 | | BlurView.reducedTransparencyFallbackColor | iOS 无障碍「减少透明度」特性，鸿蒙无对应系统级设置 API | | BlurView.androidColor | Android 专用叠加色覆盖 | | BlurView.blurTarget / targetId | Android 专用 BlurTarget 关联机制 | | VibrancyView 的 iOS UIVibrancyEffect | 鸿蒙无对应 API，已降级为 backgroundBlurStyle + backdropBlur | | BlurType -light/-dark 模式变体 | 鸿蒙 BlurStyle 无 colorMode 关联变体 |

使用限制

• 无需声明任何权限

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无（或列出已知问题）

开源协议

本项目基于 MIT License，详见 LICENSE 文件。