本文从“耳畔三国·将星落”源工程中已实现并完成真机回读的后台朗读链路提炼组件边界下文讨论的是可复用 API 设计不把源应用的运行证据表述成独立 OHPM 包已单独安装验证。朗读离开前台后仍需要一致的播放意图朗读页面退到后台后语音引擎、媒体会话和系统后台任务必须表达同一个播放意图。若只让语音引擎继续说话系统媒体控制与任务生命周期会脱节若只开后台任务页面又无法判断是否仍在播放。组件在启动后台任务前先更新媒体会话为播放状态再创建 WantAgent 并申请 AUDIO_PLAYBACK 模式。申请成功后才把 backgroundTaskRunning 写为 true避免界面把未成功的请求当作已进入后台。后台任务启动前先同步媒体会话async startAudioBackgroundTask(includeCover: boolean true): Promisevoid { const intentToken this.audioPlaybackIntentToken; if (!this.canContinueAudioPlayback(intentToken)) return; await this.updateMediaSessionState(avSession.PlaybackState.PLAYBACK_STATE_PLAY, includeCover); }每个异步链路都携带 audioPlaybackIntentToken。用户在等待期间暂停、切换段落或开始新朗读时旧请求即使稍后返回也不能覆盖当前状态检查令牌是比“最后一次回调胜出”更清晰的收束方式。为什么每次请求都带有意图令牌const agentInfo: wantAgent.WantAgentInfo { wants: [{ bundleName: context.abilityInfo.bundleName, abilityName: context.abilityInfo.name }], actionType: wantAgent.OperationType.START_ABILITY, requestCode: 3001 }; const agent await wantAgent.getWantAgent(agentInfo);停止时先同步暂停状态再停止后台运行最后在需要时销毁媒体会话。每步之后都重新检查意图令牌防止旧暂停动作把新播放误停。暂停、完成和失效请求如何收束关注点处理方式可观察结果朗读离开前台后仍需要一致的播放意图朗读页面退到后台后语音引擎、媒体会话和系统后台任务必须表达状态不依赖页面文案为什么每次请求都带有意图令牌每个异步链路都携带 audioPlaybackIntentT分支可回读组件 API 只暴露页面真正需要的能力组件对页面暴露开始、暂停、恢复和状态观察等稳定能力后台任务操作结果可核对组件对页面暴露开始、暂停、恢复和状态观察等稳定能力后台任务注册、WantAgent 和媒体会话细节留在组件内部。这样后续独立发布为 OHPM 包时调用方不必复制一套系统服务编排。组件 API 只暴露页面真正需要的能力await backgroundTaskManager.startBackgroundRunning( context, backgroundTaskManager.BackgroundMode.AUDIO_PLAYBACK, agent ); this.backgroundTaskRunning true;朗读页面退到后台后语音引擎、媒体会话和系统后台任务必须表达同一个播放意图。若只让语音引擎继续说话系统媒体控制与任务生命周期会脱节若只开后台任务页面又无法判断是否仍在播放。停止时先同步暂停状态再停止后台运行最后在需要时销毁媒体会话。每步之后都重新检查意图令牌防止旧暂停动作把新播放误停。从前台朗读到系统媒体卡片的观察点await this.stopAudioBackgroundTask( avSession.PlaybackState.PLAYBACK_STATE_PAUSE, intentToken ); this.mediaSession?.destroy(); this.mediaSession null;组件对页面暴露开始、暂停、恢复和状态观察等稳定能力后台任务注册、WantAgent 和媒体会话细节留在组件内部。这样后续独立发布为 OHPM 包时调用方不必复制一套系统服务编排。组件在启动后台任务前先更新媒体会话为播放状态再创建 WantAgent 并申请 AUDIO_PLAYBACK 模式。申请成功后才把 backgroundTaskRunning 写为 true避免界面把未成功的请求当作已进入后台。关键实现片段private async startAudioBackgroundTask(includeCover: boolean true): Promisevoid { const intentToken: number this.audioPlaybackIntentToken; if (!this.canContinueAudioPlayback(intentToken)) { return; } if (this.backgroundTaskRunning) { try { if (!this.canContinueAudioPlayback(intentToken)) { return; } await this.updateMediaSessionState(avSession.PlaybackState.PLAYBACK_STATE_PLAY, includeCover); } catch (err) { hilog.warn(DOMAIN, TAG, refresh media session while background running failed: %{public}s, JSON.stringify(err)); } return; } const context: common.UIAbilityContext this.getAbilityContext(); const agentInfo: wantAgent.WantAgentInfo { wants: [ { bundleName: context.abilityInfo.bundleName, abilityName: context.abilityInfo.name } ], actionType: wantAgent.OperationType.START_ABILITY, requestCode: 3001, actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] }; const agent await wantAgent.getWantAgent(agentInfo); if (!this.canContinueAudioPlayback(intentToken)) { return; } try { await this.updateMediaSessionState(avSession.PlaybackState.PLAYBACK_STATE_PLAY, includeCover); } catch (err) { hilog.warn(DOMAIN, TAG, prepare media session before background failed: %{public}s, JSON.stringify(err)); } if (!this.canContinueAudioPlayback(intentToken)) { await this.updateMediaSessionState(avSession.PlaybackState.PLAYBACK_STATE_PAUSE, false); return; } await backgroundTaskManager.startBackgroundRunning(context, backgroundTaskManager.BackgroundMode.AUDIO_PLAYBACK, agent); hilog.info(DOMAIN, TAG, audio background task started); if (!this.canContinueAudioPlayback(intentToken)) { try { await backgroundTaskManager.stopBackgroundRunning(context); } catch (err) { hilog.warn(DOMAIN, TAG, stop stale background audio failed: %{public}s, JSON.stringify(err)); } await this.updateMediaSessionState(avSession.PlaybackState.PLAYBACK_STATE_PAUSE, false); return; } this.backgroundTaskRunning true; } private async stopAudioBackgroundTask(playbackState: avSession.PlaybackState, intentToken: number this.audioPlaybackIntentToken): Promisevoid { if (intentToken ! this.audioPlaybackIntentToken) { return; } try { await this.updateMediaSessionState(playbackState, false); } catch (err) { hilog.warn(DOMAIN, TAG, update media session failed: %{public}s, JSON.stringify(err)); } if (intentToken ! this.audioPlaybackIntentToken) { return; } try { await backgroundTaskManager.stopBackgroundRunning(this.getAbilityContext()); } catch (err) { hilog.warn(DOMAIN, TAG, stop background audio failed: %{public}s, JSON.stringify(err)); } if (intentToken ! this.audioPlaybackIntentToken) { return; } this.backgroundTaskRunning false; } private async finalizePausedAudioSession(intentToken: number): Promisevoid { if (intentToken ! this.audioPlaybackIntentToken || this.isPlaying) { return; } await this.stopAudioBackgroundTask(avSession.PlaybackState.PLAYBACK_STATE_PAUSE, intentToken); if (intentToken ! this.audioPlaybackIntentToken || this.isPlaying) { return; } await this.updateMediaSessionState(avSession.PlaybackState.PLAYBACK_STATE_PAUSE, false); if (intentToken ! this.audioPlaybackIntentToken || this.isPlaying) { return; } } private async deactivateMediaSessionWhenPaused(): Promisevoid { if (this.mediaSession null || !this.mediaSessionActive || this.isPlaying) { return;后台任务启动前先同步媒体会话、为什么每次请求都带有意图令牌与暂停、完成和失效请求如何收束共同约束了这条处理链输入先被归类计算或异步调用只在定义的入口发生页面随后读取一个明确的结果。把这些判断分散在按钮回调里会让一次重进、一次重复点击或一次失败返回都变成难以定位的差异。组件 API 只暴露页面真正需要的能力不是事后补上的提示而是模型在边界条件下仍然要给出的答案。用户只需要看到可继续的操作模块内部则保留足够的状态来解释为什么当前结果是这样。实施取舍每个异步链路都携带 audioPlaybackIntentToken。用户在等待期间暂停、切换段落或开始新朗读时旧请求即使稍后返回也不能覆盖当前状态检查令牌是比“最后一次回调胜出”更清晰的收束方式。组件对页面暴露开始、暂停、恢复和状态观察等稳定能力后台任务注册、WantAgent 和媒体会话细节留在组件内部。这样后续独立发布为 OHPM 包时调用方不必复制一套系统服务编排。朗读离开前台后仍需要一致的播放意图所对应的数据不应依赖临时文本或视图顺序。将事实保留为字段、记录或令牌能够让同一动作在再次进入页面后得到一致的解释也为后续把能力收敛为轻量组件留下稳定边界。操作验证组件对页面暴露开始、暂停、恢复和状态观察等稳定能力后台任务注册、WantAgent 和媒体会话细节留在组件内部。这样后续独立发布为 OHPM 包时调用方不必复制一套系统服务编排。在验证过程中先观察初始状态再执行唯一的主题动作最后回读结果区或系统状态。若输入不满足条件页面应给出可理解的分支若条件恢复用户可以从当前页面再次发起操作而不需要退出并重新建立上下文。更多系统能力可参考 HarmonyOS 开发者文档。规则落到界面之前朗读离开前台后仍需要一致的播放意图不是展示层的装饰语而是决定输入如何进入状态、状态如何产生结果的约束。朗读页面退到后台后语音引擎、媒体会话和系统后台任务必须表达同一个播放意图。若只让语音引擎继续说话系统媒体控制与任务生命周期会脱节若只开后台任务页面又无法判断是否仍在播放。为什么每次请求都带有意图令牌需要把可复算的数据留在模型里每个异步链路都携带 audioPlaybackIntentToken。用户在等待期间暂停、切换段落或开始新朗读时旧请求即使稍后返回也不能覆盖当前状态检查令牌是比“最后一次回调胜出”更清晰的收束方式。组件 API 只暴露页面真正需要的能力要求页面把正常路径与异常路径放到同一个可观察范围中。组件对页面暴露开始、暂停、恢复和状态观察等稳定能力后台任务注册、WantAgent 和媒体会话细节留在组件内部。这样后续独立发布为 OHPM 包时调用方不必复制一套系统服务编排。当用户重复点击、修改输入或离开后再回来时结果应当来自已定义的状态和规则而不是依赖某一次组件渲染的偶然顺序。操作阶段应观察的字段通过条件初始化默认状态与输入不遗留上一轮结果主动作主题相关值变化与规则一致回读结果或提示可继续操作风险防护点处理结果重复动作单一状态入口不生成旁路数据无效输入条件分支返回明确提示页面重进受控恢复状态可解释状态变化应可复盘结果应可解释并且能在下一次操作时继续被用户使用。每一次状态迁移都应保留足够的业务语义用户能看懂当前结果维护者能从输入、规则和结果之间还原处理过程。把边界条件写成明确分支能够避免异常发生时把旧结果误当成新结果也让后续扩展不必回到页面里寻找隐式判断。