HarmonyOS 7.0 / API 26 空间音频能力检测：耳机切换时播放策略怎么稳定降级

这篇只拆一个具体点：空间音频能力检测与播放链路降级。版本边界先放前面：下面的写法面向 HarmonyOS 7.0 / API 26。工程里如果还在混用旧 SDK、旧模拟器镜像或旧设备系统，先不要直接照搬代码，先把版本对齐。

这个问题为什么值得单独拆

空间音频的风险不是开关做不出来，而是耳机、外放、蓝牙设备切换后能力状态会变。只记一个布尔值，设备一换就可能出现 UI 显示开启但播放链路已经不支持。

这类问题的麻烦点是：代码经常能编译，页面第一次打开也像是正常的，但一到折叠屏、多窗口、后台恢复、跨设备入口或审核机型上，行为就开始不稳定。我的处理方式不是先改 UI，而是先把能力边界、触发条件、失败原因和兜底方案拆开。

先对齐官方能力边界

这里要避免一个常见误区：看到 7.0 新能力就直接在页面里调用。更稳的做法是先做一层能力判断，判断通过再进入新能力分支，判断失败就明确走兜底，日志里也要能看出失败原因。

两个容易复现的场景

场景一：用户戴支持空间音频的耳机进入播放页

复现方式不要做得太复杂。先把页面打开到目标状态，再连续触发两次能力入口。这个时候重点看三个点：状态有没有丢、资源有没有重复申请、失败时有没有明确原因。

场景二：播放中断开耳机切到外放

第二个场景更接近线上：用户不会按开发者预设路径操作，他会切后台、恢复、换方向、分屏、拖拽、锁屏再回来。只看单次点击，问题很容易被遮住。

拆法：先决策，再执行，再兜底

我会把实现拆成三层：

1. 能力判断层：只判断版本、设备形态、入口参数和依赖状态。
2. 执行层：只负责调用具体 API，不混入页面展示逻辑。
3. 兜底层：能力不可用时给旧方案、提示或延迟重试，不让页面进入半坏状态。

这样拆的好处是后面升级 SDK 或换设备时，不需要在每个页面里翻 if 判断。页面只拿一个明确结果：能用、不能用、为什么不能用。

Demo：把能力判断收口到一个 guard

type CheckStatus = 'idle' | 'running' | 'passed' | 'failed';

interface FeatureCheckResult {
  scene: string;
  status: CheckStatus;
  reason: string;
  costMs: number;
}

class HarmonyFeatureGuard {
  private readonly apiLevel: number;
  private readonly deviceMode: string;

  constructor(apiLevel: number, deviceMode: string) {
    this.apiLevel = apiLevel;
    this.deviceMode = deviceMode;
  }

  canUseFeature(featureName: string): FeatureCheckResult {
    const start = Date.now();
    if (this.apiLevel < 26) {
      return {
        scene: featureName,
        status: 'failed',
        reason: '当前 API 低于 26，先走兼容方案，避免线上行为不一致',
        costMs: Date.now() - start,
      };
    }

    if (!this.deviceMode || this.deviceMode.length === 0) {
      return {
        scene: featureName,
        status: 'failed',
        reason: '设备形态未知，不能直接启用多端相关能力',
        costMs: Date.now() - start,
      };
    }

    return {
      scene: featureName,
      status: 'passed',
      reason: '版本、设备形态和入口状态都满足，可以进入新能力分支',
      costMs: Date.now() - start,
    };
  }
}

@Entry
@Component
struct DemoPage {
  @State private message: string = '等待检测';
  private guard: HarmonyFeatureGuard = new HarmonyFeatureGuard(26, 'foldable');

  private runCheck(): void {
    const result = this.guard.canUseFeature('HarmonyOS 7.0 capability');
    this.message = `${result.status}: ${result.reason}`;
    console.info(`[feature-check] scene=${result.scene}, status=${result.status}, cost=${result.costMs}ms`);
  }

  build() {
    Column({ space: 12 }) {
      Text(this.message).fontSize(18).fontWeight(FontWeight.Medium)
      Button('执行能力检测').onClick(() => this.runCheck())
    }.padding(20).width('100%')
  }
}

这个 Demo 只做一件事：先判断能力条件，再把结果交给页面。页面不直接关心 API 细节，也不把版本判断散落在 build 里。后面要接真实页面时，可以把 HarmonyFeatureGuard 放到公共模块里复用。

异常日志应该长什么样

[guard] status=failed, reason=api-level-too-low
[guard] status=failed, reason=stale-context
[guard] status=passed, cost=4ms

日志不要只打印“失败了”。至少要带上 scene、status、reason 和耗时。否则出了问题以后，只能靠猜。

验证矩阵

跑完后应该看到的结果

case: api26_supported -> passed
case: api25_fallback -> passed
case: stale_context_blocked -> passed
case: duplicate_action_ignored -> passed

我会怎么选方案

我的选择是第三种。只要这个能力会被多个页面用到，就不要把判断逻辑塞在页面里。页面只负责展示，能力边界、异常兜底、版本判断放到独立函数或组件里。这样后面改 SDK、换设备、补兼容逻辑，影响面会小很多。

排查顺序

1. 先看 SDK 和设备 API 版本，不一致就不要继续猜页面代码。
2. 再看入口参数和设备形态，很多问题不是 UI 写错，而是能力条件根本不满足。
3. 再看日志里的失败原因，日志只打印 failed 没有 reason，后面一定会浪费时间。
4. 最后再把能力判断抽出去，页面只消费结果，不直接散落版本判断。

可以怎么复用

这个写法可以继续扩成一个小工具：输入 featureName、apiLevel、deviceMode、entryState，输出 passed / failed / fallback 和 reason。页面层只根据结果更新 UI。这样做虽然前期多写几行代码，但后面接更多 HarmonyOS 7.0 能力时，判断逻辑不会越写越散。

最后总结

空间音频要把能力检测、设备变化、UI 状态和播放策略绑定起来，不能只靠一个开关状态。

这类特性真正有价值的地方，不是知道一个新名字，而是知道它在什么场景该用、什么时候不该用、怎么复现问题、怎么把修复沉淀成可复用代码。后面再接复杂页面时，先把这个小 Demo 跑通，基本能避开一半低级返工。

可收藏的检查清单

这张表适合直接放进项目自测单。写 HarmonyOS 7.0 / API 26 的新能力，不要只测“点一下能不能用”，更要测版本不满足、设备切换、页面销毁和重复触发。