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

设备/环境：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 中创建）。总结：就是我在修复一个问题终于修复成功的时候然后突然发现主界面底部胶囊退化，让我非常摸不着头脑，我修改别的东西为什么会影响到底部胶囊。想来想去，唯一怀疑的线索也只有昨天下午进行的一次系统更新。

会话列表出现整页重刷、输入框失焦、滚动位置跳变，根源在于键值生成函数（keyGenerator）选用了会发生变化的服务端 ID：临时消息先用占位 ID 入列，服务端回包后 ID 被替换，ArkUI 框架在 diff 时认为该数组项被整体替换，于是销毁旧组件、创建新组件；如果键值生成函数缺省，框架默认键值为 index + '__' + JSON.stringify(item)，任何字段（包括 serverId）变化都会改变键值，进一步放大重建范围。组件重建会连带丢失组件内部状态（焦点、展开态等），大量重建还会引起布局抖动导致滚动位置异常。解决思路是引入"本地稳定主键"：每条消息在本地创建时就分配一个永不变化的 localId（如 UUID），键值生成函数固定返回 localId；服务端 ID 只作为消息模型的一个普通可变字段，回包后"就地更新"该字段而不是替换整个对象。由于键值不变，框架只会复用原组件并刷新变化的部分，不会重建。示例代码以下示例基于 API 12 及以上版本的 V2 状态装饰器（@ObservedV2/@Trace/@ComponentV2/@Local），可直接放入一个 .ets 页面运行：import { util } from '@kit.ArkTS' // 消息发送状态 enum MsgStatus { SENDING = 0, // 已发出，等待服务端确认 SENT = 1, // 服务端已确认 FAILED = 2 // 发送失败 } // 消息模型：localId 为本地稳定主键（创建后永不变化），serverId 为可空的服务端 ID @ObservedV2 class ChatMessage { // localId 不参与状态更新，声明为只读即可 readonly localId: string readonly content: string readonly fromMe: boolean // serverId 与 status 会被就地修改，用 @Trace 修饰以实现属性级局部刷新 @Trace serverId: string | null = null @Trace status: MsgStatus = MsgStatus.SENDING constructor(localId: string, content: string, fromMe: boolean) { this.localId = localId this.content = content this.fromMe = fromMe } } // 消息气泡：@Param 接收 @ObservedV2 对象，其 @Trace 属性变化可被精确观察到 @ComponentV2 struct MessageBubble { @Param msg: ChatMessage = new ChatMessage('', '', true) build() { Row() { if (this.msg.fromMe) { Blank() } Column({ space: 4 }) { Text(this.msg.content) .fontSize(16) .padding(10) .borderRadius(12) .backgroundColor(this.msg.fromMe ? '#007DFF' : '#F1F3F5') .fontColor(this.msg.fromMe ? Color.White : Color.Black) if (this.msg.fromMe) { // 状态角标：serverId 补齐前后，仅此处的 UI 局部刷新，组件本身不重建 Text(this.msg.status === MsgStatus.SENDING ? '发送中' : (this.msg.status === MsgStatus.FAILED ? '发送失败' : '已送达')) .fontSize(10) .fontColor('#999999') } } .alignItems(this.msg.fromMe ? HorizontalAlign.End : HorizontalAlign.Start) if (!this.msg.fromMe) { Blank() } } .width('100%') } } @Entry @ComponentV2 struct ChatPage { // 消息列表：数组引用变化（push）触发 ForEach diff，diff 依据是 localId @Local messages: ChatMessage[] = [] // 输入框草稿：独立于列表状态，列表刷新不影响焦点 @Local draft: string = '' private scroller: Scroller = new Scroller() // 本地 ID 自增序号，与时间戳组合保证唯一 private localSeq: number = 0 aboutToAppear(): void { // 初始化历史消息（实际项目中来自本地数据库或服务端） this.messages = [ new ChatMessage(this.genLocalId(), '你好，昨天讨论的方案', false), new ChatMessage(this.genLocalId(), '已经发出邮件了', true) ] // 历史消息视为已确认 this.messages.forEach((msg: ChatMessage) => { msg.serverId = 'srv-' + msg.localId msg.status = MsgStatus.SENT }) } // 生成本地稳定主键：时间戳 + 自增序号，也可用 util.generateRandomUUID(true) private genLocalId(): string { this.localSeq += 1 return `local-${Date.now()}-${this.localSeq}` } // 按 localId 查找消息，用于服务端回包后定位 private findMessage(localId: string): ChatMessage | undefined { return this.messages.find((msg: ChatMessage) => msg.localId === localId) } // 按 serverId 去重，用于接收推送消息时合并 private hasServerId(serverId: string): boolean { return this.messages.some((msg: ChatMessage) => msg.serverId === serverId) } // 发送消息：先插入临时态，回包后就地补齐 serverId private sendMessage(): void { const content: string = this.draft.trim() if (content.length === 0) { return } this.draft = '' const localId: string = this.genLocalId() // 1. 立即插入临时消息：新 key（localId），ForEach 只为它创建一个新组件，其余项不动 this.messages.push(new ChatMessage(localId, content, true)) this.scrollToBottom() // 2. 模拟网络请求：实际项目中应把 localId 作为 clientMsgId 随请求带给服务端 setTimeout(() => { const target: ChatMessage | undefined = this.findMessage(localId) if (target === undefined) { return } // 3. 就地更新：localId（即键值）不变，组件不重建，仅状态角标局部刷新 target.serverId = 'srv-' + localId target.status = MsgStatus.SENT }, 1500) } // 接收对方消息：按 serverId 去重后追加 private onReceiveMessage(serverId: string, content: string): void { if (this.hasServerId(serverId)) { return } const msg: ChatMessage = new ChatMessage(this.genLocalId(), content, false) msg.serverId = serverId msg.status = MsgStatus.SENT this.messages.push(msg) this.scrollToBottom() } private scrollToBottom(): void { this.scroller.scrollToIndex(this.messages.length - 1, false, ScrollAlign.BOTTOM) } build() { Column() { // 消息列表区域 List({ scroller: this.scroller, space: 8 }) { // 关键：键值生成函数固定返回 localId，与服务端 ID 解耦 ForEach(this.messages, (item: ChatMessage) => { ListItem() { MessageBubble({ msg: item }) } }, (item: ChatMessage) => item.localId) } .layoutWeight(1) .width('100%') .padding({ left: 16, right: 16 }) .backgroundColor('#FFFFFF') // 输入框区域：位于 List 之外，列表刷新不会导致其重建或失焦 Row({ space: 8 }) { TextInput({ text: this.draft, placeholder: '输入消息...' }) .layoutWeight(1) .height(40) .onChange((value: string) => { this.draft = value }) Button('发送') .height(40) .onClick(() => { this.sendMessage() }) } .width('100%') .padding(12) .backgroundColor('#F5F5F5') } .width('100%') .height('100%') } }补充说明键值设计的三条硬性要求是唯一性、一致性、稳定性。localId 在消息生命周期内永不变化，天然满足；服务端 ID 只作为普通字段存在，永远不参与键值计算。临时态与服务端态的映射通过"请求携带 clientMsgId（即 localId），回包按 clientMsgId 定位"完成，服务端主动推送的消息则按 serverId 去重后以新 localId 入列，两条通路互不干扰。关于三个具体现象的对应处理：整页重 build：键值稳定后，ForEach 的 diff 只会为新增消息创建一个组件，已有项全部复用。注意切勿在键值中混入 index 或 JSON.stringify(item)，前者在头部插入时导致全部错位重建，后者在任何字段变化时都会改变键值。输入框失去焦点：本质是输入框所在组件被销毁重建。除了键值稳定外，还应把输入框放在列表结构之外（如示例中独立于 List 的 Row），并避免让承载输入框的父组件依赖会频繁变化的状态变量。滚动位置跳变：组件大规模重建会引起布局重算导致锚点丢失。键值稳定后 List 的滚动位置在数据追加时默认保持不变；需要"跟随最新消息"时，用 Scroller 的 scrollToIndex 主动控制，可结合 onReachEnd/onScrollIndex 判断用户是否位于底部，仅在底部时才自动跟随，避免打断用户阅读历史消息。若会话消息量较大（数百条以上），建议将 ForEach 升级为 LazyForEach 配合 IDataSource，或使用 Repeat 组件的 .key() 属性（写法为 Repeat(this.messages).each(...).key((item) => item.localId)）。此时数据变更要使用精确通知：新增用 onDataAdd、单条修改用 onDataChange，切勿在每次更新时调用 onDataReloaded，否则同样会触发全量重建，前述键值设计将失去意义。

社区

社区

HarmonyOS 5

HarmonyOS 6

DevEco Studio

UI

HarmonyOS

ArkUI (方舟UI框架)

HarmonyOS 7

App开发

Ability框架