鸿蒙应用 VoIP 通话管理模块使用分享

最近老板抽风又突然提出一个需求：“我希望用户能够在应用中直接发起语音☎️或者视频通话，并且用户应该能看到来电提醒，以及支持挂断、静音等操作。”

心里骂完老板之后，也只能开始去整这个活，虽然这个任务看起来有些复杂，但实际上，我们可以利用鸿蒙的 voipCall 模块实现这些需求。

今天就来和大家分享如何使用这个模块，帮你实现这些功能，为用户提供一个流畅、可靠的通话体验。

主要也是帮大家踩个坑。方便后来有需求的同学可以直接上手，有需求的同学可以直接收藏、点赞～

模块简介
voipCall 模块主要提供应用的 VoIP 通话管理功能，包括上报来电状态、通话状态以及获取用户的交互事件️等功能。简单来说，如果你需要让用户在应用中实现拨打电话、接听电话、静音、开启扬声器等操作，voipCall 模块能够帮助你实现这些通话管理需求。通过对这些功能的灵活运用，你可以打造出更加智能化的通讯应用。

要使用这个模块，首先需要导入它：

import { voipCall } from '@kit.CallKit';

小注意：这个模块从鸿蒙系统版本 4.1.0 开始支持，所以请确保开发环境符合要求。

通话类型与状态 (VoipCallType 和 VoipCallState)
首先，我们来看看通话类型。voipCall 模块中定义了两种通话类型：

• 语音通话 (VOIP_CALL_VOICE): 数值为 0，用于普通的语音电话☎️。
• 视频通话 (VOIP_CALL_VIDEO): 数值为 1，用于视频通话。

这两种通话类型是 VoIP 通话中最基础的部分。根据用户的需求，可以在应用中灵活选择语音或视频通话，让用户的沟通方式更加多样化。

再来看通话状态。通话过程中，状态可能会发生多种变化，比如拨号中、通话中、挂断等。voipCall 模块提供了一些通话状态的枚举值，具体如下：

• 空闲状态 (VOIP_CALL_STATE_IDLE): 没有正在进行的通话。
• 来电状态 (VOIP_CALL_STATE_RINGING): 有来电，但用户尚未接听。
• 通话激活 (VOIP_CALL_STATE_ACTIVE): 通话已经接通✅。
• 保持通话 (VOIP_CALL_STATE_HOLDING): 通话处于保持状态⏸️。
• 通话断开 (VOIP_CALL_STATE_DISCONNECTED): 通话已经结束❌。
• 拨号中 (VOIP_CALL_STATE_DIALING): 正在呼出。
• 正在接听 (VOIP_CALL_STATE_ANSWERED): 用户正在接听电话。
• 正在断开 (VOIP_CALL_STATE_DISCONNECTING): 通话正在挂断中。

这些状态有助于管理通话的整个生命周期，确保应用能够根据不同状态进行合理处理，从而实现对用户行为的精确反馈。

例如，当通话状态为 RINGING 时，可以弹出一个来电提醒；当状态变为 ACTIVE 时，则可以更新界面以显示通话界面。

️用户点击事件管理 (VoipCallUiEvent)
除了实现通话功能，老板还希望应用能够处理用户在通话过程中的各种交互操作，比如接听、挂断✋、静音等。voipCall 模块提供了多个通话事件枚举值，帮助我们处理这些用户的操作：

• 语音接听 (VOIP_CALL_EVENT_VOICE_ANSWER): 用户接听了语音通话☎️。
• 视频接听 (VOIP_CALL_EVENT_VIDEO_ANSWER): 用户接听了视频通话。
• 拒接 (VOIP_CALL_EVENT_REJECT): 用户拒绝了来电。
• 挂断 (VOIP_CALL_EVENT_HANGUP): 用户挂断了通话✋。
• 静音 (VOIP_CALL_EVENT_MUTED): 用户将通话静音。
• 取消静音 (VOIP_CALL_EVENT_UNMUTED): 用户取消了静音。
• 开启扬声器 (VOIP_CALL_EVENT_SPEAKER_ON): 用户开启了扬声器。
• 关闭扬声器 (VOIP_CALL_EVENT_SPEAKER_OFF): 用户关闭了扬声器。

这些事件使我们能够及时响应用户的操作，例如更新 UI 界面️或调整音频设置️，以提供更好的用户体验。

示例代码：实现来电处理
接下来，我们来看看如何在应用中处理 VoIP 来电。这是最常见的场景之一：用户收到 VoIP 来电，我们需要向系统上报来电信息，并显示来电提醒。

import { voipCall } from '@kit.CallKit';// 监听用户的通话操作
voipCall.on('voipCallUiEvent', (data: voipCall.VoipCallUiEventInfo) => {console.info(`来电信息: CallId: ${data.callId}, 事件: ${data.voipCallUiEvent}, 错误原因: ${data.errorReason}`);
});// 上报来电信息
async function reportIncomingCall(callId, userName) {let callInfo = {callId: callId,voipCallType: voipCall.VoipCallType.VOIP_CALL_VOICE, // 语音通话☎️userName: userName,abilityName: 'ability',voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_RINGING};try {let error = await voipCall.reportIncomingCall(callInfo);if (error != voipCall.ErrorReason.ERROR_NONE) {console.error(`来电上报失败❌: ${error}`);} else {console.info('成功上报来电信息✅');}} catch (e) {console.error('上报来电时出错❗', e);}
}// 调用上报来电的函数
reportIncomingCall('callId123', '小明');

上面这个小示例中，我们首先监听了用户的通话事件，比如接听、挂断✋等，然后通过 reportIncomingCall 函数上报来电信息。当上报成功后，用户会看到来电提醒，可以选择接听或拒绝。这种实现方式可以有效地提升用户体验，确保用户不会错过重要来电。

此外，上报来电信息对于系统的通话管理至关重要。它确保系统能够跟踪每一个通话，从而为用户提供稳定可靠的通信体验。

️处理静音和扬声器事件
如果用户在通话过程中选择静音或者开启扬声器，我们该如何处理呢？voipCall 模块也提供了相关功能来支持这些操作。这些功能非常实用，可以让用户在通话过程中根据环境需求自由调整音频设置。

import { voipCall } from '@kit.CallKit';// 上报通话中的静音或扬声器事件
async function reportAudioEvent(callId, event) {try {await voipCall.reportCallAudioEventChange(callId, event);console.info('成功上报通话音频事件变更✅');} catch (e) {console.error('上报音频事件时出错❗', e);}
}// 例如：将通话静音
reportAudioEvent('callId123', voipCall.CallAudioEvent.AUDIO_EVENT_MUTED);

通过 reportCallAudioEventChange 函数，我们可以上报用户对通话的音频操作，比如静音、取消静音、开启扬声器或关闭扬声器。这样，应用能够根据用户的操作及时调整音频设置，确保通话体验符合用户的期望。

要注意哈，静音和扬声器的管理对于提高用户的通话体验至关重要。在嘈杂的环境中，用户可能会选择静音以减少背景噪音；在私密环境中，用户可能会选择关闭扬声器。这些操作的快速响应可以让应用更加智能化，符合用户对高质量通话体验的期望。

最后小总结
鸿蒙的 voipCall 模块为开发者提供了强大的 VoIP 通话管理功能。无论是处理来电提醒、管理通话状态，还是监听用户的交互操作️。

总之又完成了老板一个需求，希望各位看官未来不会踩坑～，有需要的同学的可以收藏、自取～～～