Call Service Kit 实况窗扬声器按键 UI 状态同步方案
问题描述
问题现象
在去电实况窗通知(正在呼叫)场景中,扬声器按键的 UI 状态不受控,表现为:
- 每次上报"呼叫中"时,扬声器按键显示状态与上一次"呼叫中"的 last 状态一致
- 即使用户通过 AudioRenderer 改变音频输出设备,实况窗中的按键 UI 也不会实时更新
- 按键状态与实际的音频输出设备不同步
实施效果展示
1. 待机中状态

- 呼叫状态: 待机中
- 扬声器状态: 已关闭(听筒模式)
- 操作按钮: "开始呼叫" 可用(绿色),其他按钮禁用
2. 呼叫中状态

- 呼叫状态: 呼叫中...
- 扬声器状态: 已关闭(听筒模式)
- 操作按钮: "开始呼叫" 禁用,"切换扬声器" 和 "结束通话" 可用
- 实况窗预览: 显示 "Jack 呼叫中..."
3. 通话中 - 听筒模式

- 呼叫状态: 通话中
- 扬声器状态: 已关闭
- 当前音频输出设备: 听筒
- 音频设备状态: EARPIECE (活跃)
- 实况窗预览: 扬声器按钮为灰色(未激活)
4. 通话中 - 扬声器模式

- 呼叫状态: 通话中
- 扬声器状态: 已开启
- 当前音频输出设备: 扬声器
- 音频设备状态: SPEAKER (活跃)
- 实况窗预览: 扬声器按钮为蓝色(已激活)
- 操作按钮: "切换听筒" 可用
关键功能说明
状态同步机制
- 呼叫状态流转: 待机中 → 呼叫中... → 通话中 → 待机中
- 扬声器状态同步:
点击"切换扬声器"按钮 → 更新 ViewModel 状态 → 同步更新实况窗预览 UI
点击"刷新设备状态"按钮 → 重新查询 AudioRoutingManager → 更新本地状态
- 按钮联动:
通话中时,扬声器按钮文本动态切换("切换扬声器" ↔ "切换听筒")
实况窗预览中的扬声器图标实时响应状态变化(灰色 ↔ 蓝色)
实况窗预览模拟
Demo 页面中包含一个实况窗预览组件,模拟真实去电实况窗通知的效果:
- 显示来电者名称(Jack)
- 显示呼叫状态(待机中/呼叫中/通话中)
- 提供操作按钮:麦克风、挂断、扬声器
- 关键: 扬声器按钮的视觉状态(颜色/图标)与实际音频输出设备保持同步
问题分析
核心原因
- 实况窗 UI 与主应用状态隔离
实况窗是独立的通知视图,无法直接访问主应用的 @State 状态
实况窗的 UI 更新需要依赖 wantAgent 或状态广播机制
- Call Service Kit 的状态缓存机制
"呼叫中"状态上报时,Call Service Kit 会使用缓存的设备状态
未实时查询当前音频输出设备,导致显示上一次的状态快照
- 音频设备变更事件未传递到实况窗
AudioRenderer.on('outputDeviceChangeWithInfo') 的监听在主应用中
实况窗无法接收设备变更通知,无法触发 UI 刷新
解决方案
核心架构设计
采用 MVI (Model-View-Intent) 架构 + AudioKit 实现状态同步:
┌─────────────────────────────────────────────────┐
│ CallDemoPage │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ ViewModel │◄──►│ AudioRoutingManager │ │
│ │ │ │ │ │
│ │ - sendIntent│ │ - getDevices() │ │
│ │ - viewState │ │ - setAudioDevice() │ │
│ └──────────────┘ └──────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ @State UI │ │AudioRenderer │ │
│ │ │ │ │ │
│ │ - 扬声器按钮│ │-on('outputDevice│ │
│ │ - 状态显示 │ │ ChangeWithInfo')│ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────┘
完整实现方案(基于 MVI 架构)
结合 MVI 架构模式与 AudioKit 实现完整的扬声器状态同步方案。
核心代码文件
- UI 层: CallDemoPage.ets (561行)
- ViewModel 层: CallDemoViewModel.ets (191行)
- MVI 基类: ObservedData.ets、ViewIntent.ets、ViewState.ets
CallDemoPage 关键实现
import { audio } from '@kit.AudioKit';
import { BasePageHelper } from '../common/BasePageHelper'
import {
CallDemoViewModel,
CallStateIntent,
SpeakerToggleIntent,
Success
} from '../mvi/viewmodel/CallDemoViewModel'
@Entry({ routeName: 'pages/CallDemoPage' })
@Component
struct CallDemoPage {
private basePage: BasePageHelper = new BasePageHelper()
private viewModel: CallDemoViewModel = new CallDemoViewModel()
// AudioRoutingManager 实例
private audioRoutingManager: audio.AudioRoutingManager | null = null
// UIContext
@State private uiContext: UIContext | null = null
// 扬声器状态(本地状态,用于 UI 显示)
@State private isSpeakerOn: boolean = false
// 呼叫状态文本
@State private callStateText: string = '待机中'
// 是否正在通话
@State private isCalling: boolean = false
aboutToAppear() {
// 设置沉浸式状态栏
BasePageHelper.setImmersiveStatusBar({
statusBarColor: '#00428E',
statusBarContentColor: '#ffffff',
isStatusBarLightIcon: true
})
// 1. 获取 AudioManager 实例
const audioManager = audio.getAudioManager()
// 2. 获取 AudioRoutingManager 实例
this.audioRoutingManager = audioManager.getRoutingManager()
// 3. 初始化状态
this.updateSpeakerState()
// 4. 监听 ViewModel 状态变化
const stateChangeListener = () => { this.onViewModelStateChange() }
this.viewModel.viewState.subscribe(stateChangeListener)
}
aboutToDisappear() {
// 页面销毁时释放资源
this.basePage.destroy()
this.viewModel.onCleared()
// 移除 ViewModel 状态监听
const stateChangeListener = () => { this.onViewModelStateChange() }
this.viewModel.viewState.unsubscribe(stateChangeListener)
}
/**
* ViewModel 状态变化回调
*/
private onViewModelStateChange(): void {
const state = this.viewModel.viewState.value
if (state instanceof Loading) {
if (this.uiContext) {
this.basePage.showLoading(this.uiContext, '处理中...')
}
} else {
this.basePage.hideLoading()
}
if (state instanceof Failure) {
this.basePage.showToast((state as Failure).message)
}
if (state instanceof Success) {
const successState = state as Success
if (successState.data?.callState !== undefined) {
this.callStateText = successState.data.callState
}
if (successState.data?.isSpeakerOn !== undefined) {
this.isSpeakerOn = successState.data.isSpeakerOn
}
}
}
/**
* 更新扬声器状态
*/
private async updateSpeakerState(): Promise<void> {
if (!this.audioRoutingManager) {
return
}
try {
// 获取所有输出设备(异步方法,返回 Promise)
const devices: Array<audio.AudioDeviceDescriptor> =
await this.audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG)
// 检查是否有扬声器设备
let speakerActive: boolean = false
for (const device of devices) {
if (device.deviceType === audio.DeviceType.SPEAKER) {
speakerActive = true
break
}
}
this.isSpeakerOn = speakerActive
console.info(TAG, `扬声器状态更新: ${this.isSpeakerOn}, 设备数量: ${devices.length}`)
} catch (error) {
console.error(TAG, `获取设备状态失败: ${error}`)
}
}
/**
* 切换扬声器
*/
private toggleSpeaker() {
if (!this.isCalling) {
this.basePage.showToast('请先开始通话')
return
}
// 发送 Intent 切换扬声器
this.viewModel.sendUIIntent(new SpeakerToggleIntent(!this.isSpeakerOn))
// 更新本地状态
this.isSpeakerOn = !this.isSpeakerOn
this.basePage.showToast(this.isSpeakerOn ? '已切换到扬声器' : '已切换到听筒')
}
}
注意: 实际代码包含完整的 UI 构建(build() 方法)、实况窗预览组件(MockLiveView)、各种卡片组件等,共 561 行。以上仅展示核心业务逻辑。
关键实现细节
1. AudioKit 正确导入方式
// ✅ 正确:使用命名空间导入
import { audio } from '@kit.AudioKit';
// ❌ 错误:audioManager 不是命名导出
// import { audioManager } from '@kit.AudioKit';
// ✅ 正确:通过 audio 命名空间获取实例
const audioManager = audio.getAudioManager();
const audioRoutingManager = audioManager.getRoutingManager();
2. AudioRoutingManager 设备查询(异步)
// ✅ 正确:getDevices 是异步方法,返回 Promise<Array<audio.AudioDeviceDescriptor>>
const devices: Array<audio.AudioDeviceDescriptor> =
await audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG);
// ❌ 错误:不能同步调用
// const devices = audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG);
3. 实况窗预览模拟(非真实 AudioRenderer)
当前 Demo 页面通过 UI 状态管理模拟实况窗效果,未使用真实的 AudioRenderer:
// ✅ 当前实现:通过 MVI 状态管理同步 UI
private toggleSpeaker() {
// 发送 Intent 切换扬声器
this.viewModel.sendUIIntent(new SpeakerToggleIntent(!this.isSpeakerOn))
// 更新本地状态
this.isSpeakerOn = !this.isSpeakerOn
this.basePage.showToast(this.isSpeakerOn ? '已切换到扬声器' : '已切换到听筒')
}
// ❌ 未实现:真实的 AudioRenderer 设备切换
// if (this.audioRoutingManager && this.audioRenderer) {
// const deviceType = this.isSpeakerOn
// ? audio.DeviceType.SPEAKER
// : audio.DeviceType.EARPIECE
// await this.audioRenderer.setAudioDevice(deviceType)
// }
说明: 如需集成真实的通话功能,需要在 toggleSpeaker() 中添加 AudioRenderer.setAudioDevice() 调用,并监听 outputDeviceChangeWithInfo 事件。
4. MVI 架构状态管理
// ViewModel 层:管理状态和业务逻辑
export class CallDemoViewModel {
private readonly _viewState: CallDemoObservedData = new CallDemoObservedData(new Init())
readonly viewState: ObservedData<CallDemoViewState> = this._viewState
sendUIIntent(intent: CallDemoViewIntent): void {
if (intent instanceof SpeakerToggleIntent) {
this.handleSpeakerToggleIntent(intent)
}
}
private handleSpeakerToggleIntent(intent: SpeakerToggleIntent): void {
this.currentState = new CallDemoData(
this.currentState.callState,
intent.isSpeakerOn,
Date.now()
)
this._viewState.updateValue(new Success(this.currentState))
}
}
// View 层:订阅状态变化并更新 UI
this.viewModel.viewState.subscribe((state) => {
if (state instanceof Success) {
this.isSpeakerOn = state.data.isSpeakerOn
}
})
关键注意事项
3. 集成真实 AudioRenderer(扩展方案)
如需在实际通话场景中切换音频设备,需要集成 AudioRenderer:
// 在 CallDemoPage 中添加 AudioRenderer 成员变量
private audioRenderer: audio.AudioRenderer | null = null
// 初始化 AudioRenderer
private async initAudioRenderer(): Promise<void> {
const audioStreamInfo: audio.AudioStreamInfo = {
samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000,
channels: audio.AudioChannel.CHANNEL_1,
sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
}
const audioRendererInfo: audio.AudioRendererInfo = {
content: audio.ContentType.CONTENT_TYPE_SPEECH,
usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION,
rendererFlags: 0
}
this.audioRenderer = await audio.createAudioRenderer(audioStreamInfo, audioRendererInfo)
// 监听设备变更事件
const outputDeviceCallback = (info: audio.OutputDeviceChangeInfo) => {
console.info(TAG, `设备变更: ${info.deviceType}, 原因: ${info.reason}`)
if (info.reason === audio.DeviceChangeReason.DEVICE_UNAVAILABLE) {
this.audioRenderer?.pause()
}
}
this.audioRenderer.on('outputDeviceChangeWithInfo', outputDeviceCallback)
}
// 在 toggleSpeaker 中切换设备
private async toggleSpeaker() {
if (!this.isCalling) {
this.basePage.showToast('请先开始通话')
return
}
// 发送 Intent 切换扬声器
this.viewModel.sendUIIntent(new SpeakerToggleIntent(!this.isSpeakerOn))
// 更新本地状态
this.isSpeakerOn = !this.isSpeakerOn
// 切换 AudioRenderer 设备
if (this.audioRenderer) {
const deviceType = this.isSpeakerOn
? audio.DeviceType.SPEAKER
: audio.DeviceType.EARPIECE
await this.audioRenderer.setAudioDevice(deviceType)
}
this.basePage.showToast(this.isSpeakerOn ? '已切换到扬声器' : '已切换到听筒')
}
// 通话结束时清理
private cleanupAudioRenderer() {
if (this.audioRenderer) {
this.audioRenderer.off('outputDeviceChangeWithInfo')
this.audioRenderer.stop()
this.audioRenderer.release()
this.audioRenderer = null
}
}
注意: 上述代码为扩展示例,当前 Demo 未实现真实的 AudioRenderer 集成。
2. 实况窗更新频率限制
- 实况窗数据更新不能过于频繁(建议至少间隔 1 秒)
- 使用防抖机制避免频繁更新:
let updateTimer: number = 0;
function debouncedUpdateLiveView() {
if (updateTimer) {
clearTimeout(updateTimer);
}
updateTimer = setTimeout(async () => {
await updateLiveViewData();
}, 1000); // 1 秒延迟
}
3. Call Service Kit 的状态更新时机
- 呼叫中(CALL_STATE_DIALING):状态上报频繁,需注意更新频率
- 通话中(CALL_STATE_ACTIVE):设备变更才需要更新 UI
- 呼叫结束:及时清除状态监听和音频路由
提示: 如集成真实通话功能,需在 call.on('callStateChange') 中处理设备清理。
4. 权限要求
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.MICROPHONE",
"reason": "$string:microphone_reason",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.INTERNET",
"reason": "$string:internet_reason",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
}
]
}
}
完整实现示例
文件结构
entry/src/main/ets/
├── pages/
│ └── CallDemoPage.ets # 演示页面(UI层)
├── mvi/
│ ├── base/
│ │ ├── ObservedData.ets # 响应式数据基类
│ │ ├── ViewIntent.ets # Intent基类
│ │ └── ViewState.ets # State基类
│ └── viewmodel/
│ └── CallDemoViewModel.ets # 业务逻辑层
CallDemoViewModel.ets(ViewModel 层)
import { ViewIntent } from '../base/ViewIntent'
import { ViewState } from '../base/ViewState'
import { ObservedData } from '../base/ObservedData'
/**
* 呼叫状态数据
*/
export class CallDemoData {
callState: string = '待机中'
isSpeakerOn: boolean = false
timestamp: number = 0
constructor(callState?: string, isSpeakerOn?: boolean, timestamp?: number) {
if (callState !== undefined) this.callState = callState
if (isSpeakerOn !== undefined) this.isSpeakerOn = isSpeakerOn
if (timestamp !== undefined) this.timestamp = timestamp
else this.timestamp = Date.now()
}
}
/**
* Intent - 呼叫状态变更
*/
export class CallStateIntent extends ViewIntent {
callState: string
constructor(callState: string) {
super()
this.callState = callState
}
}
/**
* Intent - 扬声器切换
*/
export class SpeakerToggleIntent extends ViewIntent {
isSpeakerOn: boolean
constructor(isSpeakerOn: boolean) {
super()
this.isSpeakerOn = isSpeakerOn
}
}
// 状态类型定义
@Observed
export class Init extends ViewState<CallDemoData> {}
@Observed
export class Loading extends ViewState<CallDemoData> {}
@Observed
export class Success extends ViewState<CallDemoData> {
constructor(data: CallDemoData) {
super(data)
}
}
@Observed
export class Failure extends ViewState<CallDemoData> {
readonly message: string
constructor(message: string) {
super()
this.message = message
}
}
export type CallDemoViewState = Success | Failure | Init | Loading
export type CallDemoViewIntent = CallStateIntent | SpeakerToggleIntent
/**
* Call Demo ObservedData
* 自定义 ObservedData 子类,暴露 updateValue 方法供 ViewModel 使用
*/
@Observed
class CallDemoObservedData extends ObservedData<CallDemoViewState> {
constructor(value: CallDemoViewState) {
super(value)
}
public updateValue(value: CallDemoViewState): void {
super.updateValue(value)
}
}
/**
* Call Demo ViewModel
* 管理呼叫状态和扬声器状态的 MVI 模式
*/
export class CallDemoViewModel {
private currentState: CallDemoData = new CallDemoData()
private readonly _viewState: CallDemoObservedData = new CallDemoObservedData(new Init())
readonly viewState: ObservedData<CallDemoViewState> = this._viewState
/**
* 发送 UI Intent
*/
sendUIIntent(intent: CallDemoViewIntent): void {
if (intent instanceof CallStateIntent) {
this.handleCallStateIntent(intent)
} else if (intent instanceof SpeakerToggleIntent) {
this.handleSpeakerToggleIntent(intent)
}
}
/**
* 处理呼叫状态变更 Intent
*/
private handleCallStateIntent(intent: CallStateIntent): void {
this.currentState = new CallDemoData(
intent.callState,
this.currentState.isSpeakerOn,
Date.now()
)
this._viewState.updateValue(new Success(this.currentState))
}
/**
* 处理扬声器切换 Intent
*/
private handleSpeakerToggleIntent(intent: SpeakerToggleIntent): void {
this.currentState = new CallDemoData(
this.currentState.callState,
intent.isSpeakerOn,
Date.now()
)
this._viewState.updateValue(new Success(this.currentState))
}
public onCleared(): void {
console.info('清理 ViewModel 资源')
}
}
ObservedData.ets(响应式数据基类)
export abstract class ObservedData<T> {
/*View 只有读取 ViewModel 返回的状态权限*/
private _value: T
/*状态变更回调列表*/
private callbacks: Array<(value: T) => void> = []
protected constructor(value: T) {
this._value = value;
}
/*提供给 View 可读状态*/
get value(): T {
return this._value
}
/*只能 ViewModel 内部更改状态*/
protected updateValue(value: T) {
this._value = value
// 通知所有订阅者
this.callbacks.forEach(callback => callback(value))
}
/*订阅状态变更*/
subscribe(callback: (value: T) => void): void {
this.callbacks.push(callback)
}
/*取消订阅*/
unsubscribe(callback: (value: T) => void): void {
const index = this.callbacks.indexOf(callback)
if (index > -1) {
this.callbacks.splice(index, 1)
}
}
}
实施效果
通过上述方案,可以解决以下问题:
✅ 实况窗中的扬声器按键 UI 实时同步音频输出设备状态
✅ 不再显示上一次"呼叫中"的缓存状态
✅ 用户点击按键时,通过 MVI 架构立即更新 UI 状态
✅ 页面销毁时自动清理 ViewModel 资源,避免内存泄漏
✅ 使用 MVI 架构实现清晰的状态管理和单向数据流
注意: 当前 Demo 通过 UI 状态管理模拟实况窗效果。如需集成真实通话功能,需添加 AudioRenderer 设备切换逻辑(见上文"集成真实 AudioRenderer"章节)。
常见问题
Q1: 为什么实况窗 UI 不实时更新?
A: 实况窗是独立的通知视图,需要通过 liveView.updateLiveViewData 主动推送数据更新,无法自动响应主应用的状态变化。
Q2: audioManager 和 AudioRoutingManager 有什么区别?
A:
- audioManager: AudioKit 的入口点,通过 audio.getAudioManager() 获取
- AudioRoutingManager: 音频路由管理器,通过 audioManager.getRoutingManager() 获取,负责设备管理和路由控制
Q3: getDevices() 为什么是异步方法?
A: 查询音频设备可能涉及系统底层硬件枚举,需要异步执行以避免阻塞 UI 线程。返回类型为 Promise<Array<audio.AudioDeviceDescriptor>>。
Q4: 如何避免频繁更新导致的性能问题?
A: 使用防抖机制(debounce),限制更新频率为至少 1 秒间隔。
Q5: ArkTS 不支持 Function.bind() 怎么办?
A: 使用箭头函数替代:
// ❌ 错误
this.viewModel.viewState.subscribe(this.onStateChange.bind(this))
// ✅ 正确
const listener = () => { this.onStateChange() }
this.viewModel.viewState.subscribe(listener)
参考资料
- Call Service Kit 开发指南
华为 HarmonyOS 开发者 - 通话服务 - LiveView 实况窗开发
华为 HarmonyOS 开发者 - 实况窗服务 - AudioKit 音频管理
华为 HarmonyOS 开发者 - 音频服务 - MVI 架构设计模式
Google Android 开发者 - 架构指南
版本要求
- HarmonyOS API Version: 11+
- Call Kit: @kit.CallKit
- Audio Kit: @kit.AudioKit
- LiveView Kit: @kit.LiveViewKit(可选,用于自定义实况窗)
- ArkUI: @kit.ArkUI









































苏公安网备 32011402010933号