先查询能力再观察具体控件材质实验页在 API 26 模拟器上运行真实uiMaterial接口。当前镜像返回supportedtrue、level0配套 SDK 中 0 对应EXQUISITE。这是当前镜像的查询结果不将它外推为所有模拟器或设备的材质等级。this.supportsupported${uiMaterial.isImmersiveMaterialSupported()}level${uiMaterial.getGlobalMaterialLevel()};页面选择 Slider 和 Switch 类型的 Toggle因为官方明确这两类组件的沉浸光感可在全页面生效。普通内容区域不能随意套用只允许标题栏或底部 TabBar 生效的其他组件规则。工程 targetSDKVersion 已设为 26.0.0实验采用组件级配置没有额外修改应用的全局材质开关。privatematerial:uiMaterial.MaterialnewuiMaterial.ImmersiveMaterial({style:uiMaterial.ImmersiveStyle.REGULAR});Slider 的systemMaterial根据页面状态选择这个材质或uiMaterial.Material.empty。Toggle 同时控制自身和 Slider 的材质请求。材质开启状态由State materialOn直接驱动因此点击后提示和属性一起更新。不要把状态变量命名为enabled它会与 ArkUI 组件已有方法冲突示例使用 materialOn 表达独立的材质状态。关闭效果要使用 emptyundefined表示恢复默认效果uiMaterial.Material.empty才是显式关闭。对于默认就开启材质的组件二者会产生不同结果不能用“清空参数”代替关闭。.systemMaterial(this.materialOn?this.material:uiMaterial.Material.empty)当前 Demo 可切换浅色和深色背景显示正在请求材质还是已显式关闭。模拟器已走通查询、开启、关闭与背景切换路径截图记录相同控件的实际页面。这里使用纯色背景尚不足以证明复杂图片后的折射、模糊和运动效果质量纹理背景、更多弹窗组件与功耗仍属于后续扩展。将最小实测扩展到展厅展品大图作为背景时工具栏既要融入画面又要让暂停、返回和收藏保持清楚。单纯降低背景透明度容易在某些图片上看不清文字而每个组件都加厚重底色又会遮挡内容。详情工具栏、注释弹窗与操作菜单应分别选择材质和层级再结合真实背景检查可读性。API 26 的具体组件支持和等级以配套指南为准手写模糊背景不能作为系统材质能力的验收结果。先分清内容层与操作层展品画面是内容层工具栏是持续操作层弹出的注释是临时阅读层。层级关系明确后再决定哪些区域需要透出背景哪些区域必须提供稳定的阅读底色。材质效果不能代替信息层级。主操作仍需要合适的文字、间距和状态反馈如果所有按钮都发亮用户反而难以找到当前最重要的动作。能力选择放在统一适配层不同设备、系统版本和组件可能支持不同效果。应用可以维护自己的材质意图由适配层根据真实能力选择系统实现并提供可读的基础样式。typeSurfaceRoletoolbar|annotation|menu;interfaceSurfaceIntent{role:SurfaceRole;textPriority:normal|high;allowBackgroundDetail:boolean;}这里没有定义系统材质枚举避免让业务代码依赖未经核实的名字。接入时再将 SurfaceIntent 映射到当前 SDK 的正式参数并记录支持与回退条件。用极端背景检查文字选择全亮、全暗、高频纹理和强色块四组背景在同一组件上检查文字与图标。默认示例图看起来漂亮并不能代表换成用户自己的照片后仍可读。注释长文更适合稳定阅读底层短工具栏可以允许更多背景参与。交互时如果材质动态变化也要保证文字不在过渡过程中消失或跳动。弹窗和菜单保留明确边界弹窗覆盖 3D 场景时需要明确焦点、关闭方式和背景是否继续响应。若背景仍可旋转用户滚动注释可能误触模型。材质只负责视觉输入与焦点由页面交互合同管理。打开注释 → 暂停背景手势 → 显示阅读层并设置焦点 关闭注释 → 恢复原入口焦点 → 恢复背景交互大字体或窄窗口下弹窗内容需要滚动和安全区域处理不能用缩小字体来勉强维持设计图比例。回退样式也属于设计结果设备不支持目标效果时使用明确的实色或基础表面样式保持同样的操作顺序与信息层级。回退不应突然改变按钮位置也不应隐藏关键动作。测试报告分别展示支持与回退分支。系统能力检测失败时记录原因不默认返回支持但用户界面仍应可以完成阅读与返回。视觉效果与渲染成本一起观察多个动态材质叠加在 3D 场景上可能增加渲染开销。固定相机路径和交互动作比较开启前后的帧时间与页面响应。测量时保持模型、背景和屏幕条件一致不把素材差异算成材质成本。当前 Demo 包含 Slider、Toggle、明暗背景切换和能力信息。向展厅扩展时可另建工具栏、注释弹窗与菜单样例分别完成可读性、焦点和性能对照再推广到其他页面。工具栏与阅读层采用不同决策表面初始选择触发回退的条件短工具栏能力允许时使用目标系统材质背景干扰文字或能力不可用长注释稳定阅读底色优先大字体下调整尺寸与滚动不降低字号操作菜单明确边界及焦点不因背景效果削弱选中与禁用状态全局套用同一种材质便于统一外观却会把阅读层和短操作层的矛盾一起带入按角色映射多一层配置但更容易稳定回退。先完成三种基础表面和焦点恢复再核对系统材质入口最后用固定 3D 路线比较开销。支持检测、视觉可读和任务可完成是三项独立验收不合并成一个“效果开启成功”。参考沉浸光感官方课程入口、HarmonyOS 7 新能力。接入依据开启沉浸光感、组件适配沉浸光感。材质开关和背景状态如何直接驱动控件控件绑定 materialOn关闭时显式使用 Material.empty。背景与各正文 Text 的 fontColor 使用同一 dark 状态按钮独立使用白色文字。支持探测失败时仍展示错误信息与基础控件不能以查询值代替真实材质效果检查。import{uiMaterial}fromkit.ArkUI;import{LabTheme}from../common/LabTheme;EntryComponentstruct MaterialLabPage{StatematerialOn:booleanfalse;Statecapable:booleanfalse;Statedark:booleanfalse;Statevalue:number40;Statesupport:string等待查询;privatematerial:uiMaterial.MaterialnewuiMaterial.ImmersiveMaterial({style:uiMaterial.ImmersiveStyle.REGULAR});aboutToAppear():void{try{this.capableuiMaterial.isImmersiveMaterialSupported();this.materialOnthis.capable;constlevel:numberuiMaterial.getGlobalMaterialLevel();this.supportsupported${this.capable}level${level};}catch(error){this.capablefalse;this.materialOnfalse;this.support(errorasError).message;}}build(){Column({space:22}){Text(24 · 组件沉浸光感).fontSize(26).fontWeight(FontWeight.Bold).fontColor(this.dark?Color.White:LabTheme.ink)Text(this.support).fontSize(16).id(materialSupport).fontColor(this.dark?Color.White:LabTheme.ink)Text(展厅音量).fontSize(20).fontColor(this.dark?Color.White:LabTheme.ink)Slider({value:this.value,min:0,max:100,step:1}).systemMaterial(this.materialOn?this.material:uiMaterial.Material.empty).onChange((value:number){this.valuevalue;})Text(音量${this.value}).fontSize(18).fontColor(this.dark?Color.White:LabTheme.ink)Toggle({type:ToggleType.Switch,isOn:this.materialOn}).systemMaterial(this.materialOn?this.material:uiMaterial.Material.empty).enabled(this.capable).onChange((value:boolean){this.materialOnthis.capablevalue;})Text(this.materialOn?已请求系统材质:已显式关闭材质).fontSize(18).fontColor(this.dark?Color.White:LabTheme.ink)Button(切换明暗背景).fontColor(Color.White).id(materialBackground).onClick((){this.dark!this.dark;})Text(比较相同控件在两种背景下的可读性。实际材质等级由设备决定。).fontSize(16).fontColor(this.dark?Color.White:LabTheme.ink)Blank()Button(返回目录).fontColor(Color.White).onClick((){this.getUIContext().getRouter().back();})}.padding(28).width(100%).height(100%).backgroundColor(this.dark?LabTheme.ink:LabTheme.background)}}exportclassLabTheme{staticreadonlybackground:string#F4F1EA;staticreadonlyink:string#16324B;staticreadonlyaccent:string#276E70;staticreadonlycard:string#FFFFFF;staticreadonlymuted:string#536677;}操作或边界应检查的结果关闭材质Slider 和 Toggle 同时使用 empty切换背景文字与背景成对切换能力查询失败展示错误基础交互仍保留能力探测返回 false 或抛出异常时materialOn 与 capable 同时归零开关禁用两个控件直接绑定 Material.empty。探测成功后才允许用户启用系统材质。真机能力值、明暗与开关对照2026-09-20HBN-AL80API 26回读 supportedtrue、level1页面开关为开启显示“已请求系统材质”Slider 值为 40。该设备等级与前述模拟器的 level0 不同适配层应使用实际查询值。旧实现将 foregroundColor 放在根 Column 上浅色状态下蓝按钮也显示深色文字。修订后移除父层前景色将 dark 对应的颜色直接绑定到正文 Text按钮继续显式设置白字。真机四种组合均完成操作与回读背景材质开关页面提示浅色开已请求系统材质深色开已请求系统材质深色关已显式关闭材质浅色关已显式关闭材质四组截图与开关状态分别核对材质能力值均为 supportedtrue、level1。纯色静态背景的切换覆盖基础交互与文字显示复杂纹理下的折射、运动效果和渲染成本仍需专门场景测量。