react-native-immersive-material 为 React Native 鸿蒙应用桥接 API 26 系统材质、点光源和设备材质等级查询。配套项目 rnoh-spatial-audio-studio 用播控卡片与悬浮菜单演示接入,在真机与模拟器上验证策略切换、RN 子控件触控和 30 轮属性更新耗时。
配套实战项目已开源在 abaoge/rnoh-spatial-audio-studio,第三方库统一使用官方社区仓库 oh-react-native/react-native-immersive-material,有问题可到第三方库仓库提 Issue,也可以来 鸿蒙系统 React Native 开源社区 交流。

前言

我做了一个播控卡片与快捷菜单的交互页面,想试试鸿蒙系统光感能力怎样接进 React Native。页面用彩球和竖条模拟复杂背景,曲目、EQ 和校准按钮只更新界面状态,没有接入音频播放或声学校准。最初的卡片采用固定的半透明深色背景和细边框:背景纹理仍然清晰可见,切到浅色舞台后配色也不协调,点按时缺少额外的光效反馈。

我先把普通透明度叠色与系统材质分开核对,再基于 RNOH 0.84.6 封装了 react-native-immersive-material,把 uiMaterial 与 UIDesignKit 接成可嵌套 RN 子组件的容器。接入后,两端都能切换配置、显示边缘光效并响应内部按钮;真机返回 SMOOTH 等级,自适应策略关闭双边缘流光,模拟器返回 EXQUISITE,策略开启流光。30 轮原生配置更新的平均耗时分别为 887.6 us 和 501.6 us,两端的单次最大值分别为 1805.8 us 与 2051.2 us。这些记录验证了桥接与交互链路;背景模糊、自动反色和实际帧率,需要分别看系统条件与测量范围。

一、使用场景与真实痛点

1.1 播控卡片与悬浮菜单为什么卡在“伪玻璃”上

这个演示页面把几种操作放在同一个场景里:切换曲目名称、打开或关闭 EQ 状态、展开快捷菜单,以及在深浅背景之间切换。我要验证的是,原生材质容器包住 RN 文本和按钮后,外层的配置更新、边缘光效与内层的点击能否共存。菜单中的“空间声场重校准”等名称是演示选项,点击后只回写选择结果。

起点是一张固定配色的半透明卡片。这里有三个需要分别处理的问题:

  1. 透明度与系统材质用途不同:rgba() 做颜色混合,本身不会让背景变模糊。调底色和文字颜色就能改善阅读对比度;若要调用鸿蒙的系统材质,还需要原生接口。
  2. 系统材质与流光需要明确的启用策略:我希望页面先读取设备材质等级,再决定是否启用附加流光。这是本库的策略选择,是否降低渲染开销仍需要单独测量。
  3. 外层光效不能挡住内层按钮:原生容器需要把触摸交给 RN 子树,同时发出可观察的交互回执。按钮可用是这次接入必须验证的结果。

HarmonyOS API 26 的 @ohos.arkui.uiMaterial 提供 ImmersiveMaterial、五档样式及设备材质等级查询,@kit.UIDesignKit 提供点光源与双边缘流光组件。我把这些接口桥接成统一容器,补齐 RN 页面调用这些系统能力的入口。

1.2 我做的光感容器解决了什么

这张播控卡片需要把鸿蒙的材质等级、系统光效和 RN 按钮接到同一个容器里,于是我用 RNOH 0.84.6 做了 react-native-immersive-material。

页面把原来的卡片外壳换成 ImmersiveMaterialSurface,卡片里的标题和按钮仍由 React Native 渲染。启用 adaptive 时,库根据系统返回的材质等级选择光效策略。本文的 SMOOTH 真机保留系统材质请求并关闭双边缘流光,EXQUISITE 模拟器在收到流光请求且 HDS 能力可用时开启流光。两端可以沿用同一套页面代码。

我也把触控和回执做进了容器。用户点「下一曲」时,触摸经原生层转交给 RN 子树,曲目状态仍由业务页面更新。调试时,页面可以从回执看到库选了哪档策略,以及原生同步处理花了多久。这样同一个容器既能包住常驻卡片,也能用在弹出的菜单里,页面只处理各自的交互。

库版本为 0.1.0,采用 MIT 许可。配套项目 rnoh-spatial-audio-studio 用这个库搭了深浅两种背景、快捷菜单和配置切换测试。源码入口见 官方社区库与独立实战项目。

1.3 从点按到打开光感菜单

点按「弹出沉浸光感快捷菜单」后,RN 页面在当前窗口挂上浮层,并把菜单项放进光感容器。容器挂载 RN 子控件,按设备材质等级和页面请求配置系统材质与光效。图 1 上方是同一台手机打开菜单前后的界面示意,下方是这次操作经过的三层。

同一台直板手机打开光感菜单前后的界面及三层调用流程

图1 菜单流程

选中一项后,RN 页面记录选项并收起浮层。曲目、菜单状态和内容区衬底都由应用管理。光感容器负责材质、光效和触控转发,可以用同一套接入方式包住不同的页面内容。

二、真机与模拟器双端运行效果与实测数据

2.1 双端运行环境与硬件算力分级的真实差异

很多与图形材质相关的接口,只在单一设备上跑一次很容易漏掉硬件分级分支。我在华为畅享 100 Pro Max 真机和本地 HarmonyOS API 26 直板手机模拟器上直接运行实战工程 rnoh-spatial-audio-studio(版本 1.0.0),两台设备的环境参数与首屏探针回执对照如下:

核对维度真机实测端(华为畅享 100 Pro Max)模拟器实测端(API 26 直板手机模拟器)
设备标识与型号YEW-AL80(真机 USB 连接)Mate 90 Pro 镜像(本地虚拟设备)
屏幕物理像素分辨率1128 × 24441280 × 2832
React Native / RNOH0.84.1 / 0.84.6(开启 C-API 与 Fabric)0.84.1 / 0.84.6(开启 C-API 与 Fabric)
DevEco Studio26.0.0.86526.0.0.865
编译 SDKHarmonyOS 26.0.0,SDK 包 26.0.0.105 Release同左
系统软件版本YEW-AL80 7.0.0.100(SP9C00E100R9P4)emulator 7.0.0.107(SP8DEVC00E999R4P11)
模拟器镜像不适用HarmonyOS-7.0.0/phone_all_arm,7.0.0.107
sdkApiVersion2626
immersiveMaterialSupportedtrue ✅true ✅
globalMaterialLevel2(SMOOTH 流畅算力档)0(EXQUISITE 高精算力档)
materialState / materialType0(DEFAULT) / 20(DEFAULT) / 2
hdsMaterialSupportedfalse(返回空列表 "")true(返回 "IMMERSIVE")
hdsEffectAvailabletrue ✅true ✅
首屏 probeDurationUs522.5 us617 us
adaptive 模式自动决策adaptive_smooth(开系统材质、关双边缘流光)adaptive_full(请求系统材质 + 开双边缘流光)

表1 双端探针

🔍 同样是 API 26,两端的材质等级和 HDS 材质枚举并不一致,因此我没有仅凭 API 版本选择效果。globalMaterialLevel 是系统提供的设备材质配置,不是实时 CPU 跑分;模拟器返回 EXQUISITE,不能解释为宿主机算力更强。库在 SMOOTH 下关闭附加流光,是根据等级制定的默认策略,表中数据没有测量它带来的帧率或功耗变化。

2.2 暗夜声场舞台同屏对比与子组件触控穿透验证

打开实战工程首页后,主舞台上方是用 <ImmersiveMaterialSurface> 承载的「晨光海岸 · 空间声场」播控主卡,中部左右并排放置了「空间光感材质」与「普通半透明层」两张同屏对照卡,底部提供五档玻璃厚度、点光源反馈与边缘流光开关;顶部回执栏实时显示 RNImmersiveMaterial.getMaterialCapabilities() 的探测状态与微秒级配置耗时。

真机空间声场播控首屏:空间光感材质与普通半透明层同屏对照

图2 真机首屏

先看真机首屏画面(图 2):上方播控主卡与左侧「空间光感材质」对照卡透出底层冷暖声场光晕并带有柔和边缘亮线,右侧普通半透明层则仅做静态底色平铺。核对顶部回执栏时,真机默认命中 adaptive_smooth/regular(首屏探测耗时 522.5 us)。这里的 regular 是传入的样式,不足以证明五档模糊效果都已呈现。官方说明 SMOOTH 使用底色、边框和阴影实现材质,样式厚度只影响中、高等级;因此这张真机截图不能作为 regular 背景散焦的证据。uiMaterial 接口说明

模拟器暗夜极光首屏:EXQUISITE 策略与双边缘流光

图3 模拟器首屏

同一份代码在模拟器上的首屏画面(图 3)显示 EXQUISITE 等级、HDS 材质枚举 IMMERSIVE,探测耗时 617 us。状态行是 adaptive_full/regular、流光开启、配置更新耗时 1150.8 us,卡片边缘能看到双色流光带。截图和回执可以核对当前策略及可见边缘效果,但不能据此确认背景折射的实现路径或实际渲染帧率。

真机切至 system 模式并验证内部 RN 按钮切歌与光感脉搏

图4 触控与流光

容器能否复用,还要看内部 RN 控件是否可点击。在真机测试中(图 4),我先切到显式请求流光的 system 模式,状态变为 system/regular,配置更新耗时 377.7 us。随后点击「下一曲」与「通透 EQ」:曲目名称切到「松林雨后 · 双耳声景」且开关文字更新,证明这两个按钮的事件到达了业务层。onInteractionPulse 同时回传抬手坐标 (262.3, 146.3)、配置值 bright,以及 responseDurationUs=3063.3。该耗时从 ArkTS 触摸处理函数入口计到事件发出前,包含调用 C++ 转发接口与坐标处理;它不覆盖 JS 回调执行、后续绘制或屏幕呈现,不能称为端到端触控延迟。

2.3 明亮浅色舞台、悬浮光感菜单与 30 轮连续切换基准

除了深色背景,音乐与工具类应用还经常面临浅色主题或封面背景变亮的场景。我将舞台切换为「明亮白纸」并回到 adaptive 模式继续观察真机与模拟器的表现。

真机明亮白纸背景与卡片配色

图5 浅色背景

切到明亮白纸背景(图 5)后,对照卡仍保留固定深色底,实验卡的文字与按钮随页面主题变化,配置更新耗时为 534.5 us。源码根据 backdrop 选择文字颜色,这部分可读性来自应用配色。colorInvert 还受系统等级和资源颜色条件约束,不能让这里的硬编码颜色自动反转。沉浸光感常见问题

库暴露的五个样式值与系统枚举一一对应,表 2 是参数映射。它们适合用来表达不同厚度请求,不代表已经在 SMOOTH 真机上测到了五种视觉差异。

immersiveStyle 参数系统枚举厚度语义
ultra_thinImmersiveStyle.ULTRA_THIN超薄
thinImmersiveStyle.THIN薄
regularImmersiveStyle.REGULAR常规
thickImmersiveStyle.THICK厚
ultra_thickImmersiveStyle.ULTRA_THICK超厚

表2 五档材质

接着点击播控舞台右上角的「声场偏好」,在卡片内展开请求厚实样式与边缘光效的快捷光感菜单,并在真机上录下了切换玻璃厚度、点光源档位与声场菜单的连续交互:

真机展开空间音频快捷光感菜单

图6 真机菜单

模拟器悬浮快捷光感菜单运行画面

图7 模拟器菜单

真机连续切换材质厚度、点光源与声场快捷菜单交互动图

图8 交互动效

图 6 与图 7 展示了真机与模拟器两端的快捷光感菜单,图 8 记录的是真机上的连续切换交互。菜单内容区使用深色半透明衬底,外侧保留边缘光带。点击「空间声场重校准」或「返回播控」后,面板收起并回写当前声场状态;这里验证的是菜单选择、切换与状态同步,没有执行真实声学校准。

最后点击「30x 材质切换耗时基准」,用 45 ms 的定时步进请求 30 次属性变化,在五档厚度与三档光效之间切换。45 ms 只是请求间隔,约每秒 22.2 次,不是逐帧负载,也不保证实际调度间隔恒定。ArkTS 侧记录配置处理函数内部耗时,通过 onMaterialApplied 回传;下面保留原始完成态画面和 HiLog。

真机回写菜单选择并完成 30 轮连续材质切换

图9 真机压测

模拟器回写菜单选择并完成 30 轮材质切换

图10 模拟器压测

真机与模拟器双端 HiLog 原始结构化遥测日志对照

图11 双端日志

测量项与统计口径真机(YEW-AL80)模拟器(API 26)结果解读
连续切换有效样本数30 / 30 次30 / 30 次两端均取得 30 条配置回执
原生配置更新平均耗时887.6 us501.6 us同步处理区间的算术平均值
95 分位耗时(P95)1438.3 us1424.8 us按演示程序的排序索引取值
单次最大耗时1805.8 us2051.2 us单次尖峰受当次线程调度影响
完整样本范围299.2—1805.8 us221.1—2051.2 us保留全部 30 条样本,不排除高值
菜单交互结果选中结果回写选中结果回写只验证界面状态,不代表声学校准

表3 切换统计

💡 applyDurationUs 从 syncFromDescriptor 内开始能力查询前计时,到修饰器构造、状态赋值和同步流光控制调用结束为止,计时结束后才发送回执。ArkUI 后续属性应用、节点挂载、渲染与显示不在这个区间内;首轮流光还要等 .onAppear 再启动。effectiveStyle、hdsFlowActive 和预设 reason 描述代码选择的策略,不能替代可见效果或帧率测量。

这组数据按各端默认 adaptive 分支采集:真机关闭流光,模拟器开启流光,不能当作同条件优化前后对照。P95 沿用程序的 sorted[Math.floor(n * 0.95)],30 条时取升序第 29 条。保留完整样本范围(真机 299.2—1805.8 us、模拟器 221.1—2051.2 us)能直接看到偶发高值;由于日志没有线程调度跟踪,无法单凭微秒回执定位尖峰原因。流光配置中的 60 是期望帧率,没有 FPS 或掉帧数据,不能用这些局部耗时推断满帧或未跨帧。

三、跨端架构原理与核心源码剖析

3.1 双通道桥接架构与渲染交互时序

为了让 React Native 既能“先看清硬件底牌”,又能“像普通 <View> 一样嵌套业务子组件”,react-native-immersive-material 采用了 TurboModule + Fabric C-API 自定义容器 的双通道架构:

react-native-immersive-material 跨端分层架构图

图12 分层架构

页面可通过 TurboModule 读取设备能力和推荐预设。Fabric 将容器属性传给 ArkTS,容器用响应式修饰器更新材质与点光源,并把触控事件交给 ContentSlot 中的 RN 子树。图 13 展示了两条通道的调用关系。

沉浸材质探测、动态挂载与触控脉冲完整时序图

图13 渲染时序

3.2 设备材质等级如何决定流光策略

TurboModule 的 getMaterialCapabilities() 把 API 版本、材质支持状态、全局等级和 HDS 光效可用性返回给 RN。这样首页可以展示探测结果,而容器更新时会从同一套探测逻辑拿到策略输入。类型定义和 Codegen 生成的绑定分别留在包的 TurboModule 与 Fabric 规格文件中。

我把策略放在 ImmersiveMaterialHelpers.ets 的 resolveEffectiveMaterialDecision。函数接收页面的模式、厚度和光效请求,以及设备探测结果,然后决定是否请求系统材质、点光源和双边缘流光。样式和光效参数在入参处归一化。代码如下,注释说明了几处判断。

export function resolveEffectiveMaterialDecision(
  requestedMode: string | undefined,
  requestedStyle: string | undefined,
  requestedFlow: boolean,
  requestedLightMode: string | undefined,
  caps: RNImmersiveMaterial.MaterialCapabilities,
): EffectiveMaterialDecision {
  const mode = requestedMode === 'legacy' || requestedMode === 'system' || requestedMode === 'adaptive'
    ? requestedMode
    : 'adaptive';
  const style = normalizeImmersiveStyleName(requestedStyle);
  const lightMode = normalizeLightEffectMode(requestedLightMode);

  // 对照组清除系统材质和光效,保留 RN 自己的卡片样式。
  if (mode === 'legacy') {
    return {
      effectiveMode: 'legacy',
      effectiveStyle: style,
      useSystemMaterial: false,
      useHdsFlow: false,
      useVisualLight: false,
      detail: '对照基线:已显式关闭系统材质与光学着色器,仅渲染 RN 自绘半透明伪玻璃。',
    };
  }

  // 版本、能力和系统材质状态共同决定是否申请系统材质。
  const canUseImmersive =
    caps.sdkApiVersion >= 26 && caps.immersiveMaterialSupported && caps.materialState !== 2;
  if (mode === 'adaptive' && canUseImmersive && caps.globalMaterialLevel === 2) {
    // SMOOTH 的 adaptive 分支保留系统材质请求,关闭双边缘流光。
    return {
      effectiveMode: 'adaptive_smooth',
      effectiveStyle: style,
      useSystemMaterial: true,
      useHdsFlow: false,
      useVisualLight: lightMode !== 'none' && caps.hdsEffectAvailable,
      detail: `算力自适应 SMOOTH:启用 ${style} 系统材质并自动收起高开销边缘流光。`,
    };
  }

  // 其余策略仍需页面请求和 HDS 可用,才会开启双边缘流光。
  return {
    effectiveMode: canUseImmersive ? (mode === 'system' ? 'system' : 'adaptive_full') : 'fallback_visual',
    effectiveStyle: style,
    useSystemMaterial: canUseImmersive,
    useHdsFlow: requestedFlow && caps.hdsEffectAvailable,
    useVisualLight: lightMode !== 'none' && caps.hdsEffectAvailable,
    detail: canUseImmersive
      ? `API 26 系统材质生效:分级=${caps.globalMaterialLevelLabel} · 厚度=${style} · 流光=${requestedFlow && caps.hdsEffectAvailable ? '开启' : '关闭'}`
      : `当前端不支持 uiMaterial(level=${caps.globalMaterialLevelLabel}),已平滑回退到 UIDesignKit 光效壳层。`,
  };
}

这里的等级 2 对应 SMOOTH。进入 adaptive_smooth 后,系统材质继续请求,双边缘流光关闭,点光源仍按页面光效请求与 HDS 可用性决定。显式选择 system 时,流光由页面开关和 HDS 能力控制。回执里的 effectiveStyle 记录策略选用的样式,实际可见效果仍取决于第二章列出的材质等级和系统条件。

3.3 原生容器怎样接回 RN 的点击

ImmersiveMaterialSurface.ets 用 ContentSlot 挂载 C-API 托管的 RN 子树。在它下方,流光节点设为 HitTestMode.None,让内部按钮的触摸可以交给外层容器处理。容器在 handleTouchEvent 中把事件转给 C++,再按需要向 JS 发出触控回执。

private handleTouchEvent(event: TouchEvent): void {
  const startUs = nowMicros();
  // 先把完整触摸序列交给 C-API,RN 的 Pressable 才能识别点击。
  try {
    this.ctx.rnInstance.postTouchEventMessageToCpp(this.tag, event);
  } catch {
    // 实例释放时,原生触摸转发可能抛出异常。
  }
  // 业务触控回执只记录按下和抬起。
  if (event.type !== TouchType.Down && event.type !== TouchType.Up) {
    return;
  }
  // 手指抬起后可能已离开 touches,优先从 changedTouches 取坐标。
  const primaryTouch =
    event.changedTouches && event.changedTouches.length > 0
      ? event.changedTouches[0]
      : event.touches && event.touches.length > 0
        ? event.touches[0]
        : undefined;
  const px = primaryTouch ? Math.max(0, Math.round(primaryTouch.x * 10) / 10) : 0;
  const py = primaryTouch ? Math.max(0, Math.round(primaryTouch.y * 10) / 10) : 0;
  // 在发出回执前结束计时,度量本函数的原生同步处理。
  const responseUs = Math.max(0.1, Math.round((nowMicros() - startUs) * 10) / 10);

  this.ctx.rnInstance.emitComponentEvent(this.tag, 'interactionPulse', {
    phase: event.type === TouchType.Down ? 'down' : 'up',
    pointerX: px,
    pointerY: py,
    lightMode: this.effectiveModeVal === 'legacy' ? 'none' : this.lightEffectModeVal,
    edgeFlowLight: this.edgeFlowActive,
    responseDurationUs: responseUs,
  });
}

转发发生在事件类型判断之前,因此移动等中间事件也能送入 RN。回执只报告按下和抬起,抬起时优先读变化中的触点。页面可以把按钮状态变化和这条回执一起核对,判断触摸有没有进到业务层。计时截止于发出回执之前,JS 处理和屏幕呈现发生在这个计时范围之外。

同一个原生组件还管理材质和光效的更新。配置变化时,syncFromDescriptor 重新创建并赋值响应式修饰器,由 ArkUI 应用系统材质和视觉效果。切回对照态时,修饰器会清除已有材质及光效。流光控制器等节点挂载后再启动,在节点卸载时停止。这些处理对应第四章的局部刷新与光效残留问题。

四、真实踩坑记录与技术边界

接通 API 26 原生容器并拆分实战工程时,我遇到了几处编译、挂载与触控问题。下面结合错误信息和代码解释处理方法,也交代哪些现象还没有足够证据。

4.1 🐛 坑点一:在 .ts 文件导入 @kit.UIDesignKit 触发 10311005 编译拦截

最初我按照常规 TurboModule 习惯,把能力探测辅助函数写在 ImmersiveMaterialHelpers.ts、把模块实现写在 RNImmersiveMaterialTurboModule.ts。执行 hvigorw assembleHar 时,ArkTS 编译器直接报错中断:

10311005 ArkTS Compiler Error: Identifier 'hdsEffect' comes from '@hms.hds.hdsBaseComponent.d.ets' which can not be imported in .ts file.

原因与解决:HarmonyOS SDK 中 @kit.UIDesignKit 的底层声明文件采用 .d.ets 格式(包含 @Component 视觉组件结构体等扩展语法),ArkTS 编译器严格禁止在纯 .ts 模块中静态导入扩展声明符号。我将这两个实现文件统一改为 .ets 后缀,让模块根目录的 ts.ts 只负责重导出 ./src/main/ets/generated/ts 里的纯 TS Codegen 胶水,而将自定义原生组件与类统一放在模块入口 index.ets 中导出,HAR 编译立刻恢复通过。

4.2 🐛 坑点二:Codegen 字段命名为 package 触发 es2abc 严格模式 10705000 报错

HAR 编译刚过,接着构建宿主应用 HAP 时,es2abc 字节码打包阶段又抛出了一个意想不到的语法错误:

10705000 Syntax Error: Unexpected strict mode reserved keyword [RNImmersiveMaterial.ts:4:16]

原因与解决:打开 Codegen 自动生成的 generated/turboModules/RNImmersiveMaterial.ts 一看,原来我在 MaterialCapabilities 类型里定义了一个字段叫 package: string。Codegen 在将其转换为 ArkTS 命名空间声明时,触发了 es2abc 严格模式对 ECMAScript 保留字的语法检查。我将强类型接口中的字段名改为 packageName: string 重新生成代码,仅在 getCapabilities() 返回的序列化 JSON 字符串里同时保留新旧两个键名做兼容,彻底消除了字节码编译报错。

4.3 🐛 坑点三:C-API 架构下 wrappedRNChildrenBuilder 闪退与子按钮点击失灵

第一次把 HAP 装上真机启动时,应用首屏刚渲染到 <ImmersiveMaterialSurface> 就直接闪退,抓取日志定位到异常栈:

Error: Couldn't find descriptorWrapper at RNComponentDataSource.ets:56 / EtsRNOHContext.ets:283

原因与解决:RNOH 0.84.6 默认在宿主入口启用了高性能 enableCAPIArchitecture: true。旧版纯 ArkTS 架构常用的 wrappedRNChildrenBuilder 依赖 ArkTS 侧 DescriptorRegistry 为所有子组件创建包装器,而在 C-API 架构下,RN 标准视图、文本与可按压子组件直接在 C++ 层构建为原生 ArkUI_NodeHandle 树,根本不会注册进 RNComponentDataSource。

改成 ContentSlot(this.ctx.getContentForTag(this.tag)) 后,真机首屏顺利渲染出了完整的播控卡片子树,但紧接着我发现卡片里的「下一曲」按钮点不动。排查 RNOH 触摸分发机制后发现,当自定义 @Component 包裹节点槽位时,触摸事件停在了外层 ArkTS 容器上,没有进入 C++ TouchEventDispatcher。补上触摸回调转发 postTouchEventMessageToCpp(this.tag, event) 并给底层 HdsVisualComponent 加上 HitTestMode.None 后,真机与模拟器上的内部按钮点击全部恢复灵敏响应。

4.4 🐛 坑点四:局部刷新与计时边界

检查连续切换时,我分别处理了状态更新与计时问题:

  1. 修饰器状态与流光挂载顺序:普通私有成员的内部变化不能直接驱动 ArkUI 局部更新。我把修饰器改为 @State,每次重新配置都赋一个新实例;流光控制器则等 .onAppear 确认节点挂载后再启动,卸载时停止。本次两端各 30 条回执和交互记录验证了这些路径,但回执数量不等于每次变化都完成了屏幕呈现。
  2. 用单调时钟度量间隔:Unix 纪元纳秒约为 1.79 × 10¹⁸,确实超过 number 的安全整数范围,但这个数量级的浮点间距约为 256 ns,即 0.256 us,不能单凭它解释百微秒差值归零。旧零值的根因尚未由日志确定。采用 getUptime 的主要理由是避免墙钟校时干扰;纳秒单位本身不保证纳秒精度。当前实现异常时回退到 Date.now() * 1000,此时只有毫秒级读数,且仍受墙钟调整影响;耗时的 0.1 us 下限只是数值保护,不是可测精度。

4.5 ⚠️ 坑点五:菜单背景与窗口边界

快捷菜单还需要处理背景层次和关闭后的状态:

  1. 先控制窗口变量:本例使用同窗口的 StyleSheet.absoluteFillObject 浮层,让菜单与彩色舞台处于同一页面。当前证据验证了这条路径,没有提供 Modal 与同窗口浮层的同条件测量,因此不能把窗口方案概括为性能或稳定性结论。迁移到 Modal 时,需要重新验证背景采样、触控和关闭时的资源释放。
  2. 文字可读性由内容层兜住:我给菜单内容区设置了 rgba(15, 23, 42, 0.84) 衬底,外侧留出边缘光带。两端截图中背景纹理仍可见,真机的 SMOOTH 等级也不能用于证明 thick 散焦;没有渲染跟踪证据时,不把差异归因于“真机 GPU”和“模拟器软件合成器”。切回 legacy 时,代码用 uiMaterial.Material.empty 清除系统材质,并重置 HDS 光效,避免前一次配置残留。

4.6 🧩 坑点六:双仓库外部依赖消费与非鸿蒙端属性剥离

把实战项目 rnoh-spatial-audio-studio 从三方库仓库独立拆出时,公开源码仓库为遵循洁净入库规范不提交二进制 .har 产物,如果实战宿主工程直接引用预编译包就会在全新克隆后编译报错;同时非鸿蒙端回退组件 FallbackSurface 初版把 materialMode、onMaterialApplied 等自定义原生属性直接通过剩余参数透传给了宿主 <View>。我在实战工程 package.json 中直接关联公开三方库 Git 依赖,并让 harmony/entry/oh-package.json5 指向 node_modules/react-native-immersive-material/harmony/immersive_material 源码模块参与联合编译(Metro 打包器自动识别并重定向鸿蒙三方包导入),同时在该回退组件中按属性白名单剥离全部材质专属字段,完成了两个独立仓库的依赖安装与契约测试。宿主仍需按 README 配置原生注册和本地签名;非鸿蒙回退只做了单测,未做 Android、iOS 运行回归。

五、结论与可直接复用的接入建议

react-native-immersive-material 给 RN 页面提供了鸿蒙系统材质、光效和设备等级查询入口。此次验证覆盖了 API 26 上的配置切换、RN 子控件点击与回执,不把默认策略描述为已经验证的性能优化。接入播控卡片或快捷菜单时,可以按以下方式复用。

5.1 添加依赖与注册原生模块

在 RN 工程根目录添加官方库的 Git 依赖。

npm install --legacy-peer-deps 'git+https://atomgit.com/oh-react-native/react-native-immersive-material.git'

在鸿蒙宿主的 oh-package.json5 中关联 @rnoh/react-native-immersive-material 源码模块。随后注册 ArkTS Package、组件 Builder 和 C++ Package,保证 RN 的组件名能找到对应原生实现。完整文件和 CMake 配置见官方社区库的 README 与 Example。

5.2 用光感容器包住现有按钮

注册完成后,可以直接把业务按钮放进光感容器。这个最小示例用 onNextTrack 接收页面已有的切歌回调。开启 edgeFlowLight 表示页面请求流光,最终仍由 adaptive 按设备能力选择。

import React from 'react';
import { Pressable, Text } from 'react-native';
import { ImmersiveMaterialSurface } from 'react-native-immersive-material';

export function NextTrackCard({ onNextTrack }: { onNextTrack: () => void }) {
  return (
    <ImmersiveMaterialSurface
      materialMode="adaptive"
      immersiveStyle="regular"
      lightEffectMode="soft"
      edgeFlowLight
      cornerRadius={20}
      style={{ height: 80, justifyContent: 'center' }}>
      {/* 点击回调留在 RN 页面,容器负责材质与触控转发。 */}
      <Pressable onPress={onNextTrack}>
        <Text style={{ color: '#F8FAFC', padding: 12 }}>下一曲</Text>
      </Pressable>
    </ImmersiveMaterialSurface>
  );
}

菜单场景可用同一组件包裹浮层内的 RN 菜单项,菜单开关和选项状态继续由页面管理。需要确认策略时,给容器加上 onMaterialApplied 回调读取 effectiveMode 与 hdsFlowActive。

5.3 适用边界与双仓库获取指引

  • 运行版本与回退边界:本篇只验证 HarmonyOS API 26。鸿蒙平台始终加载原生入口,库中的 API 检查不能保证 API 26 以下设备安全启动;静态 Kit 导入与控制器初始化需要另行适配。只有非鸿蒙入口使用剥离专属属性后的普通 View,Android、iOS 尚未做运行回归。
  • 先核对效果条件:SMOOTH 下不把样式值当作五档背景模糊证据。文本可读性由页面颜色和衬底保证,不能仅设置 colorInvert 就期待硬编码颜色自动反转。系统组件适用范围、等级与资源条件以 uiMaterial 文档 为准;本库的 Stack 容器实验不代表所有系统材质效果均受支持。
  • 按需启用流光:先从少量焦点卡片或菜单接入,检查目标设备的可见效果、触控与渲染开销,再决定同屏数量。局部配置耗时不能替代帧率和功耗测量。
  • 源码获取:通用库与极简 Example 统一使用官方仓库 oh-react-native/react-native-immersive-material,完整演示页面与采样逻辑见 rnoh-spatial-audio-studio v1.0.0。本文使用的库版本为 0.1.0,接入时按官方仓库 README 选择对应版本与配置。

小结

从一张半透明卡片做到能切换策略、显示边缘光效并承载 RN 按钮的原生容器,我最有用的收获是把“传入参数”“系统选择”和“屏幕效果”分开核对。两端各 30 条配置回执与实际点击记录说明桥接链路已经跑通;SMOOTH 与 EXQUISITE 的差异也提醒我,接口返回支持,并不意味着每种效果都会出现。把状态清理、挂载顺序和触控转发处理好,再保留应用自己的配色与可读性保障,这个容器才有明确的复用边界。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐