问答专区-华为/鸿蒙开发者论坛-华为开发者联盟

设备/环境：SGT-AL10 · HarmonyOS 7.0.0.105 · API 26 · DevEco Studio（hms SDK，UIDesignKit 声明 6.1.0(23)/6.1.1(24)）；应用 metadata 已配置 ohos.arkui.UIMaterial.state = "enable"；targetAPIVersion ≥ 26；entry 模块；系统设置"沉浸光感" = 强（最高档）。问题现象：底部导航（悬浮胶囊 + 独立圆形）由普通 ArkUI 组件（Stack/Row）通过 systemMaterial(new uiMaterial.ImmersiveMaterial(...)) 接入沉浸式系统材质。HarmonyOS 7.0.0.105 SP6 系统更新之前：胶囊呈现真实玻璃质感（折射/光晕/通透）。SP6 更新之后：同一代码、同一设备、未改任何配置——胶囊变成纯透明的卡片（背后内容直接透出，无任何材质滤镜/折射/高光；看起来就像完全没有材质）。已按官方文档验证：按"沉浸光感"官方指南示例 1 的写法复刻（Column/Stack + .backgroundColor(Color.Transparent) 写在 .systemMaterial(...) 之前 + borderRadius + 顺序正确），同样失效。按"通用组件封装"实践（ImmersiveSurface：独立组件 + BuilderParam 内容 + 透明背景 + borderRadius + clip(true) + systemMaterial 最后），同样失效。运行时探针证据（关键）：deviceInfo.apiAvailable('26.0.0') = true；uiMaterial.getMaterialInfo().state = 1（≠ DISABLE）→ 应用侧门全过；new uiMaterial.ImmersiveMaterial({ style: REGULAR, materialColor: '#80FF0000', interactive: true, lightEffect: {color: undefined} }) 传入 systemMaterial 后，50% 红色 materialColor 在画面上零差异（胶囊未变粉）——证明材质滤镜完全未被渲染（不是"样式选错/背景遮挡"类问题）。对照：同一设备上，系统组件的表面（如音乐条、系统设置预览）沉浸光感正常；HDS HdsTabs 官方悬浮页签（barFloatingStyle.systemMaterialEffect，materialType/materialLevel 模式）玻璃材质正常——唯独第三方应用里自定义 ArkUI 节点的 systemMaterial 不渲染。求助点：自定义 ArkUI 组件（Stack/Row/Column 等普通容器）的 systemMaterial 在 7.0.0.105(SP6) 是否被限制/降级？是否已有已知问题或需要新的启用条件？应用侧如何判定设备的沉浸光感算力档位（低/中/高）与全局材质等级？官方指南示例 5 提到 uiMaterial.getGlobalMaterialLevel() / uiMaterial.isImmersiveMaterialSupported()，但当前 SDK 的 ArkTS 声明中不存在这两个 API（能力清单 ArkUI.json 中有声明，since 26.0.0）——这是声明回退还是需要更高 SDK 补丁？如果自定义组件的材质确实无法恢复，官方推荐的自定义底部导航正确载体是什么（HDS 已确认可用，但存在自定义页签内容/动画限制）？代码片段（完整：普通 ArkUI 组件 + 沉浸光感）以下 = 生产组件中"普通 ArkUI 组件 + 材质接入"的完整相关代码（约 120 行）。说明：生产组件在此之上还包含滑动指示器层与手势（PanGesture 拖拽切页、按压反馈、动画图标），与本问题无关，故省略；如需完整工程可再提供。import { uiMaterial } from '@kit.ArkUI'; import { deviceInfo } from '@kit.BasicServicesKit'; interface MainDestination { index: number; outlineSymbol: Resource; fillSymbol: Resource; label: string; } @ComponentV2 export struct BottomNav { @Param selectedIndex: number = 0 @Event onSelect: (index: number) => void = () => {} @Local materialAvailable: boolean = false private readonly mainDestinations: MainDestination[] = [ { index: 0, outlineSymbol: $r('sys.symbol.message'), fillSymbol: $r('sys.symbol.message_fill'), label: 'Chat' }, { index: 1, outlineSymbol: $r('sys.symbol.person_crop_circle_fill_1'), fillSymbol: $r('sys.symbol.person_crop_circle_fill_1'), label: 'Contacts' }, { index: 2, outlineSymbol: $r('sys.symbol.gearshape'), fillSymbol: $r('sys.symbol.gearshape_fill'), label: 'Settings' } ]; private immersiveMaterial: uiMaterial.ImmersiveMaterial | undefined = undefined; aboutToAppear(): void { try { this.materialAvailable = deviceInfo.apiAvailable('26.0.0'); if (this.materialAvailable) { const info = uiMaterial.getMaterialInfo(); this.materialAvailable = info.state !== uiMaterial.MaterialState.DISABLE; } this.immersiveMaterial = this.materialAvailable ? new uiMaterial.ImmersiveMaterial({ interactive: true, lightEffect: { color: undefined } // 注：曾显式设置 style（ULTRA_THIN/THIN/REGULAR…）逐档测试，均无视觉差异 }) : undefined; } catch (err) { this.materialAvailable = false; this.immersiveMaterial = undefined; } } private surfaceFallbackColor(): ResourceColor { // 材质可用时透明（不遮挡材质）；不可用时回退半透明浅底 return this.materialAvailable ? Color.Transparent : $r('sys.color.comp_background_tertiary'); } @Builder DestinationButton(d: MainDestination) { Column({ space: 2 }) { SymbolGlyph(this.selectedIndex === d.index ? d.fillSymbol : d.outlineSymbol) .fontSize(22) .fontColor([this.selectedIndex === d.index ? $r('sys.color.icon_emphasize') : $r('sys.color.icon_primary')]) Text(d.label) .fontSize(10) .fontColor(this.selectedIndex === d.index ? $r('sys.color.icon_emphasize') : $r('sys.color.icon_primary')) } .justifyContent(FlexAlign.Center) .layoutWeight(1) .height('100%') .backgroundColor(Color.Transparent) .onClick(() => { this.onSelect(d.index); }) .accessibilityGroup(true) .accessibilityText(d.label) .accessibilitySelected(this.selectedIndex === d.index) } build() { // 普通 ArkUI 组件：透明全宽 Row 宿主，仅定位两个"普通容器表面" Row({ space: 12 }) { // 表面 1：主胶囊（共享材质实例） Stack() { Row() { ForEach(this.mainDestinations, (d: MainDestination) => { this.DestinationButton(d) }, (d: MainDestination) => `${d.index}`) } .width('100%') .height('100%') } .layoutWeight(1) .height(56) // 普通容器 + 普通属性 .borderRadius(28) .clip(true) .shadow({ radius: 24, color: 'rgba(0,0,0,0.16)', offsetX: 0, offsetY: 6 }) .backgroundColor(this.surfaceFallbackColor()) // ← 写在 systemMaterial 之前（官方顺序） .systemMaterial(this.immersiveMaterial!) // ← 通用属性接入沉浸式系统材质 // 表面 2：独立圆形（同一材质实例） Stack() { Stack() { Text('A').fontSize(22).fontWeight(FontWeight.Medium).fontColor(Color.White) } .alignContent(Alignment.Center) .width(44) .height(44) .borderRadius(22) .backgroundColor('#0A59F7') } .alignContent(Alignment.Center) .width(56) .height(56) .borderRadius(28) .clip(true) .shadow({ radius: 24, color: 'rgba(0,0,0,0.16)', offsetX: 0, offsetY: 6 }) .backgroundColor(this.surfaceFallbackColor()) .systemMaterial(this.immersiveMaterial!) .onClick(() => { this.onSelect(3); }) .accessibilityGroup(true) .accessibilityText('Profile') } .width('100%') .padding({ left: 20, right: 20 }) .margin({ bottom: this.systemInsetVp() + 8 }) // 底部安全区留白 .backgroundColor(Color.Transparent) .hitTestBehavior(HitTestMode.Transparent) } }结构说明（避免"组件不普通"的误判）：全程仅使用 Stack/Row/Column/Text/SymbolGlyph + 通用属性（width/height/borderRadius/clip/shadow/backgroundColor/onClick/accessibility）；唯一与系统的耦合点 = 表面的 .backgroundColor(Color.Transparent) 与 .systemMaterial(...)；两个表面共享一个 uiMaterial.ImmersiveMaterial 实例（aboutToAppear 中创建）。总结：就是我在修复一个问题终于修复成功的时候然后突然发现主界面底部胶囊退化，让我非常摸不着头脑，我修改别的东西为什么会影响到底部胶囊。想来想去，唯一怀疑的线索也只有昨天下午进行的一次系统更新。

社区

社区

HarmonyOS 5

HarmonyOS 6

DevEco Studio

UI

HarmonyOS

ArkUI (方舟UI框架)

HarmonyOS 7

App开发

Ability框架