design.md 4.7 KB
Context
当前 spectrum-visualizer 能力仅支持 4 种频谱效果，且效果切换与效果渲染逻辑耦合较高。此次变更需要在不破坏现有 4 种效果体验的前提下，扩展可选效果数量，并保证播放中实时切换稳定、渲染性能可控、用户上次选择可恢复。
约束条件：
- ArkTS UI 和渲染逻辑位于
entry/src/main/ets/view/与entry/src/main/ets/viewmodel/。 - 频谱数据来源与播放链路不变，不引入新的音频解码协议或外部依赖。
- 中低端设备需避免因效果分支增多导致掉帧或明显功耗上升。
Goals / Non-Goals
Goals:
- 将频谱效果扩展为可配置的效果集合，支持后续继续新增。
- 统一效果元数据（ID、名称、默认参数、渲染策略），避免在页面中硬编码分支。
- 支持播放过程中无感切换效果，并记住用户最近一次选择。
- 为每个效果定义最小性能边界（刷新频率、点数/条数上限、降级策略）。
Non-Goals:
- 不修改音频 PCM/FFT 数据获取链路。
- 不引入在线下载效果、主题商店或脚本化效果系统。
- 不重做整体播放器 UI 布局，仅在现有入口扩展效果选择体验。
Decisions
- 建立效果注册表（Effect Registry）而非继续使用
switch/case扩展。 - 方案：以统一结构维护效果定义（
effectId、展示名、参数默认值、渲染函数引用、性能等级）。 - 原因：新增效果只需注册配置与渲染实现，减少 UI 与渲染层的重复改动。
- 备选方案：继续在现有渲染组件中追加条件分支。
不采用原因：分支增长会快速增加维护成本，且难以统一做性能控制。
采用“共享数据输入 + 效果独立渲染器”的分层。
方案：FFT/幅值数据由现有链路统一提供，不同效果仅消费标准化频谱帧。
原因：避免每个效果重复处理原始数据，降低行为不一致风险。
备选方案：每个效果自行拉取并处理数据。
不采用原因：会造成重复计算和状态分散，切换时更易出现抖动。
增加效果状态持久化字段并设置兼容回退。
方案：保存
selectedEffectId；启动时若配置不存在或无效，回退到历史默认效果。原因：保障升级后配置兼容，避免因效果下线或重命名导致页面异常。
备选方案：不持久化，每次启动使用默认效果。
不采用原因：用户体验不稳定，无法满足“记忆和恢复”目标。
引入统一性能守卫。
方案：按效果定义最大刷新率与采样点上限，在帧耗时过高时触发降级（降低刷新率/简化细节）。
原因：新增效果后，性能风险主要来自复杂绘制路径；统一守卫可避免逐个临时修补。
备选方案：仅做人工测试，不加运行时守卫。
不采用原因：设备差异大，纯人工验证无法覆盖全部场景。
Risks / Trade-offs
- [效果数量增加导致选择复杂度上升] → 通过分组命名和默认推荐效果降低决策成本。
- [部分高复杂度效果在低端设备掉帧] → 为每个效果设性能等级并启用运行时降级。
- [注册表与现有逻辑并存期间出现双源状态] → 迁移阶段保留单一状态入口（仅
selectedEffectId为真源）。 - [历史配置兼容问题] → 增加配置合法性校验，非法值自动回退并记录日志。
Migration Plan
- 新增效果注册表与标准化渲染接口，保持现有 4 种效果先接入新接口。
- 扩展效果切换 UI，读取注册表动态渲染选项。
- 添加
selectedEffectId持久化与启动恢复逻辑。 - 逐步接入新增效果并启用性能守卫。
- 完成真机冒烟：切换稳定性、后台恢复、中低端设备帧率/功耗观察。
回滚策略：
- 若出现严重性能或崩溃问题，可在配置层禁用新增效果，仅保留原 4 种已验证效果；
- 保留旧默认效果回退逻辑，确保用户可继续播放与可视化。
Open Questions
- 首批新增效果的目标数量是否固定（例如从 4 扩展到 8）？
- 效果命名和分组是否需要产品/UI 设计参与统一规范？
- 性能守卫的阈值是否需要按设备档位做差异化配置？
Implementation Notes (2026-02-08)
- 已完成代码实现：效果注册表、动态特效选择、新增脉冲特效、渲染性能守卫、
selectedSpectrumEffectId持久化与兼容回退。 - 风险记录更新：性能守卫阈值基于通用策略，仍需真机分档验证后再微调。
- 当前验证结果：已完成静态代码检查与文件级自检；真机冒烟（切页、暂停恢复、中低端性能）待执行。