HarmonyOS 7.0 / API 26 空间音频适配实战：耳机、外放和多设备切换时声音状态如何稳住
先把问题摆出来
空间音频这类能力看起来是音效问题，落到应用里其实是状态管理问题。用户可能先用耳机听，再切到外放，又把页面接续到平板或鸿蒙电脑。如果页面只记一个 enabled，声音效果和 UI 状态很容易对不上。
这篇只盯一个能力点：空间音频。我不把它写成概念说明，而是按排查路径写：问题怎么出现，怎么复现，代码怎么落地，边界怎么验，最后怎么封装成以后能复用的写法。
版本边界和适用场景
| 项目 | 本文口径 |
|---|---|
| 系统范围 | HarmonyOS 7.0 / API 26 及以上能力适配 |
| 适合页面 | 音视频详情页、播放页、课程页、直播回放页、多设备接续页 |
| 常见风险 | 耳机切换后模式错乱、外放仍保留耳机策略、多设备接续后 UI 显示和实际声音不一致 |
| 验收目标 | 设备变化有日志、模式可降级、接续后状态可恢复、异常场景不影响播放主流程 |
这里要先定边界。很多页面问题不是 ArkUI 写错了，而是版本能力、设备形态、生命周期、异步任务混在一起后，状态没有被分层。只要边界不清楚，代码就会越补越乱。
常见错误：把能力适配写成一个布尔开关
刚开始最容易写成下面这样。能跑，但后面会很难维护。
interface FeatureSwitch { enabled: boolean; deviceType: string; scene: string; } class BadFeatureAdapter { buildState(input: FeatureSwitch): string { if (!input.enabled) { return 'fallback'; } if (input.deviceType === 'phone') { return 'phone-mode'; } if (input.deviceType === 'tablet') { return 'tablet-mode'; } return 'default-mode'; } }问题在于它只关心“开没开”，没有记录为什么进入这个分支。等页面出现抖动、丢状态、审核截图异常或者多设备表现不一致时，只能靠猜。
改法：把输入、策略和结果拆开
我更倾向于把适配拆成三层：输入层只收集事实，策略层做判断，结果层给 UI 或任务调度使用。这样改完以后，日志能看懂，单测也能写。
type DeviceShape = 'phone' | 'foldable' | 'tablet' | 'pc'; type FeatureScene = 'preview' | 'editing' | 'handoff' | 'review'; interface FeatureContext { apiVersion: number; deviceShape: DeviceShape; scene: FeatureScene; widthVp: number; heightVp: number; lowPowerMode: boolean; } interface FeatureDecision { mode: 'full' | 'compact' | 'safe' | 'off'; reason: string; shouldRecordMetric: boolean; } export class FeaturePolicy { decide(ctx: FeatureContext): FeatureDecision { if (ctx.apiVersion < 26) { return { mode: 'off', reason: 'api-version-not-ready', shouldRecordMetric: true }; } if (ctx.lowPowerMode) { return { mode: 'safe', reason: 'low-power-protect-frame', shouldRecordMetric: true }; } if (ctx.deviceShape === 'foldable' && ctx.widthVp >= 720) { return { mode: 'full', reason: 'foldable-wide-layout', shouldRecordMetric: true }; } if (ctx.scene === 'review') { return { mode: 'safe', reason: 'review-screenshot-stable-first', shouldRecordMetric: true }; } return { mode: 'compact', reason: 'default-compact', shouldRecordMetric: false }; } }这个写法的重点不是类名，而是结果里带 reason。以后日志里看到 `review-screenshot-stable-first`，就知道页面为什么选择安全模式，不需要再翻一堆 if。
案例一：页面首屏不能因为新能力变慢
第一类问题是音频模式和设备类型绑定太死。耳机断开后，如果策略没有重新计算，页面仍然显示空间音频已开启，用户听到的却是普通外放。
class StartupProbe { private marks: Record<string, number> = {}; mark(name: string): void { this.marks[name] = Date.now(); } cost(from: string, to: string): number { return (this.marks[to] ?? 0) - (this.marks[from] ?? 0); } } const probe = new StartupProbe(); const policy = new FeaturePolicy(); probe.mark('page-enter'); const decision = policy.decide({ apiVersion: 26, deviceShape: 'foldable', scene: 'preview', widthVp: 840, heightVp: 720, lowPowerMode: false }); probe.mark('policy-ready'); console.info('feature-mode', decision.mode); console.info('feature-reason', decision.reason); console.info('policy-cost', probe.cost('page-enter', 'policy-ready'));验收时我会看三个值：mode 是否符合预期，reason 是否能解释分支，policy-cost 是否足够小。策略判断应该是轻量逻辑，不能把耗时任务塞进去。
案例二：多设备切换时不能丢上下文
第二类问题是多设备接续。播放页迁移到另一个设备后，不能只恢复播放进度，还要恢复声音策略和降级原因。
interface ViewSnapshot { route: string; selectedId: string; scrollOffset: number; featureMode: FeatureDecision['mode']; updatedAt: number; } class SnapshotStore { private current: ViewSnapshot | undefined; save(snapshot: ViewSnapshot): void { this.current = { ...snapshot, updatedAt: Date.now() }; } restore(): ViewSnapshot | undefined { if (!this.current) { return undefined; } return { ...this.current }; } } const store = new SnapshotStore(); store.save({ route: 'detail-preview', selectedId: 'card-10086', scrollOffset: 460, featureMode: decision.mode, updatedAt: Date.now() }); const restored = store.restore(); console.info('restore-route', restored?.route); console.info('restore-feature-mode', restored?.featureMode);这里要防的不是“能不能保存一个对象”，而是设备形态变化后，页面上下文有没有跟着回来。比如折叠屏从半屏切到展开，或者平板分屏宽度变化，用户看到的内容不应该突然回到默认态。
两种实现方式对比
| 方案 | 好处 | 坑点 | 我会放在哪里 |
|---|---|---|---|
| 页面里直接 if/else | 写起来最快 | 分支越来越多，日志看不懂 | 只适合临时验证 |
| 独立 Policy 类 | 能单测，能记录 reason | 要先设计输入输出 | 推荐用于正式代码 |
| Store 里直接保存全部状态 | 恢复简单 | 容易保存脏数据 | 只保存必要字段 |
| Snapshot 分层保存 | 边界清楚 | 需要设计字段 | 适合多设备和复杂页面 |
我的选择是 Policy + Snapshot。Policy 负责判断能力怎么开，Snapshot 负责保存页面上下文。二者不要混在一起。
封装成可以复用的入口
export class HarmonyFeatureRuntime { private readonly policy = new FeaturePolicy(); private readonly snapshots = new SnapshotStore(); prepare(ctx: FeatureContext): FeatureDecision { return this.policy.decide(ctx); } saveView(snapshot: ViewSnapshot): void { this.snapshots.save(snapshot); } restoreView(): ViewSnapshot | undefined { return this.snapshots.restore(); } }这样封装之后，页面只需要关心三件事：准备策略、保存现场、恢复现场。以后换成另一个 HarmonyOS 7.0 能力点，也可以沿用这套排查方式。
检查清单
- API 版本边界有没有写清楚，低版本是否有兜底。
- 新能力是否会影响首屏、滑动、弹窗、页面返回。
- 日志里能不能看出选择某个模式的原因。
- 多设备切换后，页面上下文能不能恢复。
- 代码是否能单独跑策略测试，而不是必须打开完整页面才知道结果。
最后总结
空间音频适配不要只写成开关。更稳的做法是把设备形态、输出通道、省电状态和页面场景都放进策略输入，再把结果和原因写进快照。这样耳机、外放和多设备切换都能查到原因，也更容易在测试阶段复现问题。
