来电场景
====

#### 场景介绍

应用接收到来自网络的音/视频通话，称为来电场景。

来电场景的效果图展示如下：

| **语音来电** | **视频来电** | **视频来电（不支持语音接听**） |
| :-- | :-- | :-- |
| ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cc/v3/h91_igZ4RwOCy3gC9HCFsg/zh-cn_image_0000002594669118.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=30EFC7469E6B7A66FB4074A17C70CB5678BDF0BFB6AE3194CC5F73713E89216A) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/06/v3/gExybtxYS2uYDNjoXMD0Vw/zh-cn_image_0000002594829046.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=A19D2DCD736D5929E93F88729BC712BC05261988F8E5A1BA5490CE499B7F30AD) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/49/v3/iGMJDfLOS4-83QdfewbpZw/zh-cn_image_0000002625188493.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=2E2586EF58B2AC224D911252EB5275762CF2AA56CBF4BFD866DBA93D004E347B) |
| **通话中** | **锁屏语音来电** | **锁屏视频来电** |
| ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c4/v3/5NpdhcXQTx2CNufP-5Y3lg/zh-cn_image_0000002625108637.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=CA17E91BB05F7A1D936871995863F4328D6838C4009C22B0ABDF22696CCE50FF) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/23/v3/Ce-_xTDKSAqXEOKhW2sOng/zh-cn_image_0000002594669120.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=2611B920D722BFC808B5ADD168E59705084CB56E3BCB60C3C76D8C5367F302B4) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c0/v3/RL1KV_N2QuCtNbxZhxeAiQ/zh-cn_image_0000002594829048.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=AEC902BCB310614968EEA9C78069F253319750E020D55E539F702EC3D5B698BB) |

#### 约束与限制

来电场景支持Phone、Tablet设备，并从6.0(20)版本开始支持Wearable设备，6.1.1(24)版本开始支持PC/2in1设备。

#### 业务流程

#### \[h2\]来电场景：接听流程图

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ef/v3/SPkU2PFPTGO8_sAs0D1Njw/zh-cn_image_0000002625188495.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=22DDD7C7BED4E20EA0ADEA949BA102CBDF3E95822DD5768C610AA72FD9532103)

#### \[h2\]来电场景：拒接流程图

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/96/v3/Ct7yrKkjRyu6JNDmXLK7Qg/zh-cn_image_0000002625108639.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=099BB02077E1C196A367C1618906FCAF482065976B9945AD3A661A10B3209C87)

#### 接口说明

来电场景的接口，由[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<VoipCallUiEventInfo>): void | 订阅voipCallUiEvent事件。 |
| off(type: 'voipCallUiEvent', callback?: Callback<VoipCallUiEventInfo>): void | 取消订阅voipCallUiEvent事件。 |
| reportIncomingCall(voipCallAttribute: VoipCallAttribute): Promise<ErrorReason> | 上报来电。 |
| reportCallAudioEventChange(callId: string, callAudioEvent: CallAudioEvent): Promise<void> | 上报音频事件。 |
| reportCallStateChange(callId: string, callState: VoipCallState): Promise<void> | 上报通话状态改变。 |
| reportCallStateChange(callId: string, callState: VoipCallState, callType: VoipCallType): Promise<void> | 上报通话状态改变，并指定通话类型。 |

#### 开发步骤

1.  导入相关依赖。
    
    import { voipCall } from '@kit.CallServiceKit';
    import { image } from '@kit.ImageKit';
    import { hilog } from '@kit.PerformanceAnalysisKit';
    
2.  为了感知到用户在横幅通知上做的接听、挂断、静音与解除静音等操作，应用需要注册voipCallUiEvent事件。建议在上报来电之前注册。
    
    示例代码如下：
    
    // 注册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)。
    
    如果当时应用在后台，系统会展示来电横幅。
    
    示例代码如下：
    
    // 构造上报来电的参数
    let voipCallAttribute: voipCall.VoipCallAttribute = {
      callId: '1234567890',
      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)指定是否允许语音接听，示例代码如下：
    
    // 构造上报来电的参数
    let voipCallAttribute: voipCall.VoipCallAttribute = {
      callId: '1234567890',
      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)状态，系统会更新通话横幅。
        
        示例代码如下：
        
        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/e6/v3/nk582c8ST2ulBD-Sl9fw2Q/zh-cn_image_0000002594669122.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=8C373A99A5AA3C0E50030D85056AD53ECD5A1A98A93D22110E1E6E2E98CE0283) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c0/v3/9_IpazwoQZeQBEu4WtlcjA/zh-cn_image_0000002625108637.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=D412C51BDF2873C418CDFCA49752EC8EEC866D5D806F7E9CE2397CF37DD1274A) |
        
        ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/62/v3/xbVJjXZERVSsTOKo4_FsQA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=932E5A133FB5C8BC22BB79C038D900FD941194E91640DE8CE78D0EBF64A69071)
        
        通话接听时，上报两次状态的好处是：
        
        因为网络等原因，从用户点击接听，到通话真正被接通的时间间隔可能比较长（比如，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)状态。
    
    示例代码如下：
    
    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步。
    
    拒接的示例代码如下：
    
    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)音频状态。
    
    示例代码如下：
    
    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/14/v3/AT24GHxxQTClox-r9_hfqQ/zh-cn_image_0000002594829050.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=A647745FC7713330E5864AE8265D58ACF9A444809DA0687D75ED96C635DD34C3) | ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/14/v3/tL0s2FjEReKcU3CUQlSgQQ/zh-cn_image_0000002625108637.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073600Z&HW-CC-Expire=86400&HW-CC-Sign=C26C429920AFC7AC356EE7737E1022AACCD324D1D974F915164E4842130FAD12) |
    
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)状态，系统会取消横幅通知。
    
    示例代码如下：
    
    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事件。
    
    示例代码如下：
    
    // 解除voipCallUiEvent事件
    voipCall.off('voipCallUiEvent', callback => {
      hilog.info(0x0000, 'CallDemo', \`Succeeded in unRegistering voipCallUiEvent, callId: ${callback.callId}\`);
    });