# 来电场景 ## 场景介绍 应用接收到来自网络的音/视频通话，称为来电场景。 来电场景的效果图展示如下： |**语音来电**|**视频来电**|**视频来电（不支持语音接听**）| |:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ee/v3/BhBESAy4TNCULvrd9aJQLQ/zh-cn_image_0000002794411329.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=7C1EC1DE1D5835E0D4624746207D1713C08CDCDE35DE93D0652CE10B0DFE69E9)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e6/v3/7nPPcvSHQl616K1IdAimdg/zh-cn_image_0000002764972610.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=0E781CB4A2B4E0F05E0E456DED003B248C1E59205A03140B088045EC4FA7715D)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/69/v3/EvZwvwx5RtaayhhkHEhjGQ/zh-cn_image_0000002765132536.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=5E352926896EA78FFE35E412C6D1347DFD071566850DBF4E7D9E4159516956B8)| |**通话中**|**锁屏语音来电**|**锁屏视频来电**| |![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f7/v3/YdmBqoEpQ2CGicVbhtBkCQ/zh-cn_image_0000002794491113.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=5868627C52B09A421399D5B8D3640AA9C703EC96FECBFA92ABB1A1B766CA9CD5)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/32/v3/6BNSeN-tTKCqUe9TXYg11g/zh-cn_image_0000002794411331.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=CB49FF5CE400BD970ADAEE552A0004197ED1BD88EFCF96D92B4ECDACCEF84DBB)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6c/v3/OU7GmNKpRqeUGlHH-XczGA/zh-cn_image_0000002764972612.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=62B1828318BADCFDD54CE33D3665CDBE394198ADC7015A780AFDE4B52666374B)| ## 约束与限制 来电场景支持Phone、Tablet设备，并从6.0.0(20)版本开始支持Wearable设备，6.1.1(24)版本开始支持PC/2in1设备。 ## 业务流程 ### 来电场景：接听流程图 ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/84/v3/tq_JY6jNRjivUNBPnyVmjw/zh-cn_image_0000002765132538.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=0D6373D4998E2494A95C0E0F858189603DD34B0ED79B9A110A864CA9153B8AC2) ### 来电场景：拒接流程图 ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/62/v3/pOXCyGwGQEaQhW1JhoiQbA/zh-cn_image_0000002794491115.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=AC48DD9AF0EA2CD2B517796F9C023C76830EBF248EE71246C6983B4517A39DDF) ## 接口说明 来电场景的接口，由[voipCall](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall)提供。更多接口信息详见[接口文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall)。 |接口名|描述| |:-----------------------------------------------------------------------------------------------------|:---------------------| |on(type: 'voipCallUiEvent', callback: Callback): void|订阅voipCallUiEvent事件。| |off(type: 'voipCallUiEvent', callback?: Callback): void|取消订阅voipCallUiEvent事件。| |reportIncomingCall(voipCallAttribute: VoipCallAttribute): Promise|上报来电。| |reportCallAudioEventChange(callId: string, callAudioEvent: CallAudioEvent): Promise|上报音频事件。| |reportCallStateChange(callId: string, callState: VoipCallState): Promise|上报通话状态改变。| |reportCallStateChange(callId: string, callState: VoipCallState, callType: VoipCallType): Promise|上报通话状态改变，并指定通话类型。| ## 开发步骤 1. 导入相关依赖。 ```typescript import { voipCall } from '@kit.CallServiceKit'; import { image } from '@kit.ImageKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; ``` 2. 为了感知到用户在横幅通知上做的接听、挂断、静音与解除静音等操作，应用需要注册voipCallUiEvent事件。建议在上报来电之前注册。 示例代码如下： ```typescript // 注册voipCallUiEvent事件 voipCall.on('voipCallUiEvent', callback => { hilog.info(0x0000, 'CallDemo', 'Succeeded in registering voipCallUiEvent'); }); ``` 3. 应用内部建立通话连接之后，需要向Call Service Kit上报来电，并携带通话信息，详见[VoipCallAttribute](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcallattribute)。 如果当时应用在后台，系统会展示来电横幅。 示例代码如下： ```typescript // 构造上报来电的参数 let voipCallAttribute: voipCall.VoipCallAttribute = { callId: 'callId123', voipCallType: voipCall.VoipCallType.VOIP_CALL_VOICE, userName: 'Callman', userProfile: image.createPixelMapSync(new ArrayBuffer(100), { size: { width: 90, height: 90 } }), abilityName: 'VoipCallAbility', voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_RINGING, showBannerForIncomingCall: true }; // 上报来电 voipCall.reportIncomingCall(voipCallAttribute).then(errorReason => { if (errorReason == voipCall.ErrorReason.ERROR_NONE) { hilog.info(0x0000, 'CallDemo', 'Succeeded in reporting the incoming call'); } else { hilog.error(0x0000, 'CallDemo', 'Failed to report the incoming call: %{public}d', errorReason); } }); ``` 对于视频通话，可以通过参数[isVoiceAnswerSupported](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcallattribute)指定是否允许语音接听，示例代码如下： ```typescript // 构造上报来电的参数 let voipCallAttribute: voipCall.VoipCallAttribute = { callId: 'callId123', voipCallType: voipCall.VoipCallType.VOIP_CALL_VIDEO, userName: 'Jack', userProfile: image.createPixelMapSync(new ArrayBuffer(100), { size: { width: 90, height: 90 } }), abilityName: 'VoipCallAbility', voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_RINGING, showBannerForIncomingCall: true, isVoiceAnswerSupported: false // 视频通话不支持语音接听 }; ``` 4. 接收到来电之后，用户可以选择接听或拒接。 接听有两种开发方式：上报两次状态、只上报一次状态。 * 上报两次状态（推荐）。 以语音通话为例，应用在接收到[VOIP_CALL_EVENT_VOICE_ANSWER](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcalluievent)事件回调之后，立即向Call Service Kit上报[VOIP_CALL_STATE_ANSWERED](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcallstate)状态，并同时执行应用内接听。 在完成应用内接听之后，再向Call Service Kit上报[VOIP_CALL_STATE_ACTIVE](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcallstate)状态，系统会更新通话横幅。 示例代码如下： ```typescript voipCall.on('voipCallUiEvent', callback => { if (callback?.voipCallUiEvent == voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_VOICE_ANSWER) { // 立即向Call Service Kit上报answered状态 voipCall.reportCallStateChange(callback.callId, voipCall.VoipCallState.VOIP_CALL_STATE_ANSWERED); // ...在应用内完成接听 // 应用内接听后，向Call Service Kit上报active状态 voipCall.reportCallStateChange(callback.callId, voipCall.VoipCallState.VOIP_CALL_STATE_ACTIVE); } }); ``` 接听过程的效果图展示如下： |**正在接通**|**接通后**| |:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/aa/v3/Adt9RibqSn-KKVF5p7Nzaw/zh-cn_image_0000002794411333.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=13B54BE806BD78B17D3942DDF6F2C679CE0D2E582168B9A01DD355652CE7BA17)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/39/v3/Nw2A4CDeQNeZLM5FH0HGQw/zh-cn_image_0000002794491113.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=6AC53297A626CE4B60170816E318995853E179CB7194E8E5000F8D9C7B1669D5)| > 说明 > > 通话接听时，上报两次状态的好处是： > > 因为网络等原因，从用户点击接听，到通话真正被接通的时间间隔可能比较长（比如，1s左右）。这段时间，如果横幅通知的样式不变，一直停留在来电状态，用户可能认为点击接听无响应，体验不好。 > > 上报两次状态，可以在接听的过程中，在界面上给用户以反馈。 * 只上报一次状态。 以语音通话为例，应用在接收到[VOIP_CALL_EVENT_VOICE_ANSWER](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcalluievent)事件回调之后，执行应用内接听。 一直到完成应用内接听后，再向Call Service Kit上报[VOIP_CALL_STATE_ACTIVE](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcallstate)状态。 示例代码如下： ```typescript voipCall.on('voipCallUiEvent', callback => { if (callback?.voipCallUiEvent == voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_VOICE_ANSWER) { // ...在应用内完成接听 // 应用内接听后，向Call Service Kit上报通话状态 voipCall.reportCallStateChange(callback.callId, voipCall.VoipCallState.VOIP_CALL_STATE_ACTIVE); } }); ``` 如果用户在横幅通知上点击拒接，则应用在接收到[VOIP_CALL_EVENT_REJECT](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcalluievent)事件回调之后，在应用内完成拒接，然后向Call Service Kit 上报[VOIP_CALL_STATE_DISCONNECTED](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcallstate)状态，系统会取消横幅通知。 拒接之后，应用可跳过5、6步，直接看第7步。 拒接的示例代码如下： ```typescript voipCall.on('voipCallUiEvent', callback => { if (callback?.voipCallUiEvent == voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_REJECT) { // ...应用内完成拒接 // 向Call Service Kit上报通话状态 voipCall.reportCallStateChange(callback.callId, voipCall.VoipCallState.VOIP_CALL_STATE_DISCONNECTED); } }); ``` 5. 在通话过程中，用户可以根据需要，可以静音或解除静音。 以静音为例，用户在横幅上点击静音，Call Service Kit会给应用回调[VOIP_CALL_EVENT_MUTED](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcalluievent)事件。 应用在完成静音后，应向Call Service Kit上报[AUDIO_EVENT_MUTED](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#callaudioevent)音频状态。 示例代码如下： ```typescript voipCall.on('voipCallUiEvent', callback => { if (callback?.voipCallUiEvent == voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_MUTED) { // 向Call Service Kit上报静音 voipCall.reportCallAudioEventChange(callback.callId, voipCall.CallAudioEvent.AUDIO_EVENT_MUTED); } else if (callback?.voipCallUiEvent == voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_UNMUTED) { // 向Call Service Kit上报解除静音 voipCall.reportCallAudioEventChange(callback.callId, voipCall.CallAudioEvent.AUDIO_EVENT_UNMUTED); } }); ``` 静音、解除静音的横幅通知效果图展示如下： |**静音**|**解除静音**| |:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7b/v3/PFKKghq8TMWVprSRjR1EOw/zh-cn_image_0000002764972614.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=23A229F23C0CA59697C169F49682692861BC48FCF2C549A98F71FEAD70BC5498)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/41/v3/BfV7FRujSj2jnHIRsWjLdg/zh-cn_image_0000002794491113.jpg?HW-CC-KV=V1&HW-CC-Date=20261015T104519Z&HW-CC-Expire=31536000000&HW-CC-Sign=D4A2E25055FE469C707373125D6C89AA5E69AA6E5D5FCF4FF31F2E7CAA51AC83)| 6. 用户在横幅点击挂断，Call Service Kit会给应用回调[VOIP_CALL_EVENT_HANGUP](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcalluievent)事件。 应用收到该事件后，应在应用内完成挂断，然后，向Call Service Kit上报[VOIP_CALL_STATE_DISCONNECTED](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/call-voipcall#voipcallstate)状态，系统会取消横幅通知。 示例代码如下： ```typescript voipCall.on('voipCallUiEvent', callback => { if (callback?.voipCallUiEvent == voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_HANGUP) { // ...应用内完成挂断 // 向Call Service Kit上报通话状态 voipCall.reportCallStateChange(callback.callId, voipCall.VoipCallState.VOIP_CALL_STATE_DISCONNECTED); } }); ``` 7. 通话结束后，应用不再需要感知到用户在通话横幅上的操作，可以解除voipCallUiEvent事件。 示例代码如下： ```typescript // 解除voipCallUiEvent事件 voipCall.off('voipCallUiEvent', callback => { hilog.info(0x0000, 'CallDemo', `Succeeded in unRegistering voipCallUiEvent, callId: ${callback.callId}`); }); ```