HarmonyOS 7 沉浸光感设了却没效果？生效区域、Material.empty 和应用级开关怎么排查

给组件设置了材质，代码没有报错，屏幕上却看不到预期的光感效果。这个问题经常被当成颜色或透明度没调好，实际更可能是应用级能力被关闭、组件放错了区域，或者把 undefined 当成了“关闭材质”。

先确认 API 26 的能力边界

官方文档在 2026-09-06 更新了沉浸光感使能说明。应用级禁用相当于总闸；普通组件还受到 Navigation、NavDestination 标题栏或底部 Tabs 等区域约束；Material.empty 与 undefined 也不是同一个含义。

• 应用级显式禁用时，组件级设置不会让效果重新生效。
• Material.empty 表示明确关闭，undefined 表示恢复组件默认行为。
• Select 的触发按钮与弹出菜单材质需要分别处理。

案例一：内容区卡片设置材质后仍然没有变化

先不要继续调透明度，而是把运行条件转换为可测试的诊断输入。只有应用开关、设备能力、承载区域和材质值同时满足时，才进入视觉参数调整。

type Region = 'title' | 'tabsEnd' | 'dialog' | 'popup' | 'content'
interface LightInput { appEnabled: boolean; supported: boolean; region: Region; material: 'on' | 'empty' | 'default' }
function diagnose(input: LightInput): string[] {
  const reasons: string[] = []
  if (!input.appEnabled) reasons.push('应用级开关关闭')
  if (!input.supported) reasons.push('设备能力不支持')
  if (!['title', 'tabsEnd', 'dialog', 'popup'].includes(input.region)) reasons.push('区域不支持')
  if (input.material === 'empty') reasons.push('组件显式关闭材质')
  return reasons
}
console.assert(diagnose({ appEnabled: true, supported: true, region: 'content', material: 'on' }).includes('区域不支持'))

断言稳定复现了“接口有值但区域不支持”的情况，日志可以直接告诉开发者应先调整页面结构。

案例二：传入 undefined 后效果在页面重建时又出现

产品意图应分成开启、关闭、跟随默认三种状态。删除配置或传 undefined 只是回到默认，不是强制关闭。

type Intent = 'on' | 'off' | 'followDefault'
function resolveMaterial(intent: Intent): 'material' | 'empty' | undefined {
  if (intent === 'on') return 'material'
  if (intent === 'off') return 'empty'
  return undefined
}
console.assert(resolveMaterial('off') === 'empty')
console.assert(resolveMaterial('followDefault') === undefined)

映射函数固定了三种语义，页面重建、主题变化和配置恢复时都不会再把“关闭”和“默认”混用。

现象与判断对照

现象	优先检查	处理原则
完全无效果	应用级开关、设备能力	先检查总闸
标题栏有效、内容区无效	组件所在区域	按官方区域边界调整
关闭后又恢复	empty 与 undefined	显式输出 empty
Select 两处效果不一致	按钮与菜单配置	分别记录并设置

为什么选择这个实现

推荐使用“产品意图映射 + 条件诊断”，因为它把视觉问题拆成可以记录的工程状态。直接在每个页面散落 if 判断，短期少几行代码，后续却很难说明究竟是哪一层关闭了能力。

可复用边界

诊断器可以封装成页面无关的策略模块，输入只保留开关、区域、设备能力和材质意图。ArkUI 页面负责把系统状态转换成输入，不在策略层伪造系统对象。

验证记录

本地断言覆盖应用级关闭、内容区不支持、Material.empty 关闭以及 undefined 恢复默认四条路径。Select 的按钮与菜单状态也按两个字段分别记录。

本文的策略代码已在宿主 JavaScript 环境执行断言，用来验证状态、排序、去重或边界计算。它不等同于 HarmonyOS 7 API 26 工程编译，也不等同于真机系统能力验证；涉及系统回调、设备能力、窗口形态或跨应用 IPC 的部分，仍应在对应 SDK 与设备上完成端到端验收。

上线前检查清单

• targetSDKVersion 达到 26.0.0
• 应用级开关未禁用
• 组件处于支持的生效区域
• 关闭时使用 Material.empty
• Select 按钮与菜单分别验证
• 深浅色和多窗口形态完成真机检查

官方资料

• 沉浸光感使能开发指南
• 沉浸光感能力概述

沉浸光感不生效时，正确顺序是总开关、设备能力、承载区域、材质语义，最后才是视觉参数。把顺序固定下来，比反复调色更快。