【HarmonyOS 7新能力｜005】沉浸光感入门实战：从能力边界到最小可运行链路
HarmonyOS 7 的沉浸光感方向，让界面不再只是"点击后变色"，而是根据手指或指针位置产生光斑、深度和形变反馈。效果看起来直观，工程实现却容易失控：事件与绘制耦合、坐标越界、离开后无法复位、高频刷新造成抖动，以及不同窗口尺寸下形变幅度不一致。
本文以一张可交互卡片为最小场景，建立"接收指针---坐标归一---距离计算---光强映射---形变---恢复"的完整链路。文中的数学函数和 ArkTS 类型属于应用侧建议实现，不代表华为官方 API；具体组件、属性、设备范围与版本行为应以 HarmonyOS 7 / API 26 官方资料为准。
一、沉浸光感不是装饰层
光效应服务于交互状态：告诉用户当前指针在哪里、哪个区域可操作、按压是否生效以及离开后界面是否恢复。若光斑只为"炫"，却遮挡正文、降低对比度或让按钮边界不清楚，反而损害体验。
最小场景只处理单张卡片。输入包括卡片尺寸、局部坐标和事件状态；输出包括光斑中心、光强、形变深度和恢复进度。业务点击事件仍由卡片处理，光效不能吞掉触摸、改变可访问性语义或扩大点击区域。
接入前应明确三条边界：光效不传递用户隐私；低性能或减少动态效果场景可降级；无输入时必须回到稳定静止状态。
二、先定义可测试的状态契约
不要在事件回调里直接散落颜色、缩放和旋转值。先把输入转换为统一状态：
ts
interface PointerSample {
localX: number
localY: number
width: number
height: number
phase: 'enter' | 'move' | 'press' | 'release' | 'leave'
}
interface LightEffectState {
normalizedX: number
normalizedY: number
intensity: number
deformation: number
active: boolean
}这样事件来源、状态计算和渲染属性可以分别测试。页面只保存当前效果状态，不在 UI 树中执行复杂数学计算。对于触摸、鼠标和触控板，可先经过适配器转换成相同的局部坐标契约。
三、坐标归一必须处理边界
局部坐标应映射到稳定范围，例如 [-1, 1]。中心点为零，左上接近 (-1,-1)，右下接近 (1,1)。宽高为零、负数或坐标越界时必须提前处理。
ts
function clamp(value: number, min: number, max: number): number {
return Math.max(min, Math.min(max, value))
}
function normalize(value: number, size: number): number {
if (size <= 0) return 0
return clamp((value / size) * 2 - 1, -1, 1)
}归一化让相同算法适应不同卡片尺寸。不要用屏幕绝对坐标直接计算，否则页面滚动、窗口缩放或组件移动后，光斑会偏离手指。
四、把完整链路拆成六个阶段
接收指针后先校验输入，再归一化坐标；根据到中心的距离计算目标强度；将强度映射到光斑和形变；最后在释放或离开时恢复静止。每个阶段都应有单独函数，避免事件回调变成难以测试的巨型代码。
ts
function distanceFromCenter(x: number, y: number): number {
return Math.min(1, Math.sqrt(x * x + y * y))
}
function mapIntensity(distance: number): number {
const t = clamp(1 - distance, 0, 1)
return t * t * (3 - 2 * t)
}这里使用平滑插值只是示例，不是平台规定。真实项目应结合视觉规范和真机效果调整，不能杜撰统一推荐参数。
五、使用四层结构隔离事件与渲染
交互层接收指针、按压和离开事件；状态层负责坐标归一、目标状态与恢复状态；效果层计算光斑映射、非线性形变和降级结果；渲染适配层把结果转换为当前组件支持的属性或绘制能力。
text
features/immersive-light/
model/EffectContract.ets
service/EffectCalculator.ets
controller/EffectController.ets
adapter/RenderEffectAdapter.ets
component/InteractiveCard.ets页面组件只负责声明布局和绑定状态。复杂分支、节流和插值放进控制器或服务，符合 ArkUI 声明式结构，也便于替换不同渲染方案。
六、非线性形变要有上限
如果形变与指针距离线性增长，靠近边缘时容易突然倾斜。可以使用缓入缓出函数，让中心区域反馈柔和、边缘逐渐接近上限。无论函数如何设计，都要对形变、缩放和位移设置最大值，防止文字扭曲或卡片超出布局。
ts
function deformationByIntensity(intensity: number, maxDepth: number): number {
const safeIntensity = clamp(intensity, 0, 1)
const safeDepth = clamp(maxDepth, 0, 1)
return safeIntensity * safeIntensity * safeDepth
}文本密集卡片宜使用更小形变；纯图片卡片可以更明显。形变不能改变真实点击判定，也不能让选中态、禁用态和错误态难以识别。
七、恢复状态比跟随状态更容易出错
常见问题是手指离开后仍残留光斑，原因包括没有处理取消事件、多个动画同时写状态、旧事件迟到或页面销毁后回调仍执行。控制器应拥有唯一目标状态，新事件到达时取消或接管旧过渡。
ts
type EffectPhase = 'idle' | 'tracking' | 'pressed' | 'recovering'
interface EffectRuntime {
phase: EffectPhase
sequence: number
state: LightEffectState
}sequence 用于丢弃旧回调。离开、取消、页面不可见和组件销毁都应进入恢复或清理路径，不能只处理正常 release。
八、高频输入需要合并刷新
指针移动事件可能非常密集。每个事件都立即触发完整渲染，会造成无意义的状态写入。建议只保留最新坐标，在下一次允许的刷新时计算一次；若新旧状态差异很小，可跳过更新。
性能结论必须来自真实设备测量。文章不能写入未经验证的 FPS、耗时、GPU 或内存数字。测试时应记录设备、系统版本、窗口尺寸、卡片数量、输入方式和测量方法，并分别检查单卡片与列表场景。
列表场景还要避免每个卡片都订阅全局指针事件。只有当前命中的卡片进入活跃状态，其余卡片保持静止；卡片移出可见区域时解除监听。诊断时可以统计事件数量和实际状态提交次数，用二者差异判断合并是否有效，但最终阈值必须来自真实测量，而不是直接照搬示例。
九、动效降级必须保留功能
当设备能力、窗口模式或用户偏好不适合复杂动效时，可以关闭形变，仅保留轻微高亮或按压态。降级后的卡片仍需完成点击、选中、禁用和键盘焦点等核心功能。
不要通过设备型号硬编码"高端/低端"。优先使用平台公开能力、实际运行反馈或产品明确配置。降级切换应平滑，不能在交互过程中突然跳变，也不应修改业务状态。
降级策略需要被纳入设计验收：完整模式包含光斑与轻量形变，简化模式只保留高亮和按压反馈，静态模式保留边框、颜色或图标状态。三种模式都应传达相同语义，且正文对比度不能依赖光效增强。用户主动关闭动态效果后，应用应立即尊重设置并在后续页面保持一致。
十、最小验收清单
至少验证：中心、四边和四角坐标正确；坐标越界被钳制；宽高异常不会出现非数值；进入、移动、按压、释放、离开和取消均有状态；快速往返不会残留；滚动列表中光效不串卡；窗口缩放后位置正确；亮暗模式下文字对比度合格；关闭动效后功能仍完整。
还要检查多输入方式：触摸、鼠标、触控板和键盘焦点。触觉或光效不能成为唯一反馈，可访问性用户仍应通过文本、形状或系统状态理解结果。没有运行真机测试时，只能标注静态设计完成。
总结
沉浸光感的工程关键是把输入、状态和渲染解耦。通过局部坐标归一、平滑映射、形变上限、唯一恢复状态、刷新合并和动效降级，可以让视觉反馈稳定服务于交互，而不是成为不可控装饰。
真正可交付的效果还应做到：无论输入设备、窗口尺寸和主题如何变化，交互语义保持一致；出现异常时能够恢复静止；无法启用复杂动效时仍保留清晰、可操作的基础反馈。
本文提供的是建议架构与静态示例，不代表已经完成真机帧率、功耗、多设备或上架验证。具体实现前应核对 HarmonyOS 7 / API 26 官方接口与当前工程能力。