diff --git a/zh-cn/application-dev/reference/apis/js-apis-call.md b/zh-cn/application-dev/reference/apis/js-apis-call.md index 87292d1fb7776837bfaeded57c2a7376bd7c2e9c..4b67f61a0c4270e6764eb411710754b43c1c9702 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-call.md +++ b/zh-cn/application-dev/reference/apis/js-apis-call.md @@ -1,13 +1,16 @@ # 拨打电话 +该模块提供呼叫管理功能，包括拨打电话、跳转到拨号界面、获取通话状态、格式化电话号码等。 + +如需订阅通话状态请使用[`observer.on('callStateChange')`](js-apis-observer.md#observeroncallstatechange)。 + >**说明：** > >本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 - ## 导入模块 -``` +```js import call from '@ohos.telephony.call'; ``` @@ -15,7 +18,7 @@ import call from '@ohos.telephony.call'; dial\(phoneNumber: string, callback: AsyncCallback\): void -拨打电话，使用callback方式作为异步方法。 +拨打电话。使用callback异步回调。 **需要权限**：ohos.permission.PLACE\_CALL，该权限为系统权限 @@ -23,14 +26,14 @@ dial\(phoneNumber: string, callback: AsyncCallback\): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | ---------------------------- | ---- | ------------------------------------------------- | -| phoneNumber | string | 是 | 电话号码。 | -| callback | AsyncCallback<boolean> | 是 | 回调函数：
- true：成功。
- false：失败。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ---------------------------- | ---- | --------------------------------------- | +| phoneNumber | string | 是 | 电话号码。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数，返回true为成功，false为失败。 | **示例：** -``` +```js call.dial("138xxxxxxxx", (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); @@ -41,7 +44,7 @@ call.dial("138xxxxxxxx", (err, data) => { dial\(phoneNumber: string, options: DialOptions, callback: AsyncCallback\): void -拨打电话，可设置通话参数，使用callback方式作为异步方法。 +拨打电话，可设置通话参数。使用callback异步回调。 **需要权限**：ohos.permission.PLACE\_CALL，该权限为系统权限 @@ -49,15 +52,15 @@ dial\(phoneNumber: string, options: DialOptions, callback: AsyncCallback- true：成功。
- false：失败。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ---------------------------- | ---- | --------------------------------------- | +| phoneNumber | string | 是 | 电话号码。 | +| options | [DialOptions](#dialoptions) | 是 | 通话参数，选择为语音通话还是视频通话。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数，返回true为成功，false为失败。 | **示例：** -``` +```js call.dial("138xxxxxxxx", { extras: false }, (err, data) => { @@ -70,7 +73,7 @@ call.dial("138xxxxxxxx", { dial\(phoneNumber: string, options?: DialOptions\): Promise -拨打电话，可设置通话参数，使用promise方式作为异步方法。 +拨打电话，可设置通话参数。使用Promise异步回调。 **需要权限**：ohos.permission.PLACE\_CALL，该权限为系统权限 @@ -78,20 +81,20 @@ dial\(phoneNumber: string, options?: DialOptions\): Promise **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | ----------- | ---- | ------------------------------------------- | -| phoneNumber | string | 是 | 电话号码。 | -| options | DialOptions | 是 | 通话参数，参考[DialOptions](#dialoptions)。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | --------------------------- | ---- | -------------------------------------- | +| phoneNumber | string | 是 | 电话号码。 | +| options | [DialOptions](#dialoptions) | 是 | 通话参数，选择为语音通话还是视频通话。 | **返回值：** -| 类型 | 说明 | -| ---------------------- | --------------------------------- | -| Promise<boolean> | 以Promise形式返回拨打电话的结果。 | +| 类型 | 说明 | +| ---------------------- | ------------------------------------------------------------ | +| Promise<boolean> | 以Promise形式返回拨打电话的结果，返回true为成功，false为失败。 | **示例：** -``` +```js let promise = call.dial("138xxxxxxxx", { extras: false }); @@ -106,9 +109,7 @@ promise.then(data => { makeCall(phoneNumber: string, callback: AsyncCallback\): void -跳转到拨号界面，并显示拨号的号码，使用callback方式作为异步方法。 - -本接口在Openharmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 +跳转到拨号界面，并显示待拨出的号码。使用callback异步回调。 **系统能力**：SystemCapability.Applications.Contacts @@ -121,7 +122,7 @@ makeCall(phoneNumber: string, callback: AsyncCallback\): void **示例：** -``` +```js call.makeCall("138xxxxxxxx", err => { console.log(`makeCall callback: err->${JSON.stringify(err)}`); }); @@ -132,9 +133,7 @@ call.makeCall("138xxxxxxxx", err => { makeCall(phoneNumber: string): Promise\ -跳转到拨号界面，并显示拨号的号码，使用Promise方式作为异步方法。 - -本接口在Openharmony 3.1 Release版本仅为接口定义，暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。 +跳转到拨号界面，并显示待拨出的号码。使用Promise异步回调。 **系统能力**：SystemCapability.Applications.Contacts @@ -152,7 +151,7 @@ makeCall(phoneNumber: string): Promise\ **示例：** -``` +```js let promise = call.makeCall("138xxxxxxxx"); promise.then(() => { console.log(`makeCall success`); @@ -165,7 +164,7 @@ promise.then(() => { hasCall\(callback: AsyncCallback\): void -判断是否存在通话，使用callback方式作为异步方法。 +判断是否存在通话。使用callback异步回调。 **系统能力**：SystemCapability.Telephony.CallManager @@ -173,11 +172,11 @@ hasCall\(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback<boolean> | 是 | 回调函数：
- true：当前存在通话。
- false：当前不存在通话。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示当前存在通话，false表示当前不存在通话。 | **示例：** -``` +```js call.hasCall((err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); @@ -188,7 +187,7 @@ call.hasCall((err, data) => { hasCall\(\): Promise -判断是否存在通话，使用Promise方式作为异步方法。 +判断是否存在通话。使用Promise异步回调。 **系统能力**：SystemCapability.Telephony.CallManager @@ -200,7 +199,7 @@ hasCall\(\): Promise **示例：** -``` +```js let promise = call.hasCall(); promise.then(data => { console.log(`hasCall success, promise: data->${JSON.stringify(data)}`); @@ -214,7 +213,7 @@ promise.then(data => { getCallState\(callback: AsyncCallback\): void -获取通话状态，使用callback方式作为异步方法。 +获取当前通话状态。使用callback异步回调。 **系统能力**：SystemCapability.Telephony.CallManager @@ -222,11 +221,11 @@ getCallState\(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------------------- | ---- | ------------------------------------ | -| callback | AsyncCallback<[CallState](#callstate)> | 是 | 回调函数：异步返回获取到的通话状态。 | +| callback | AsyncCallback<[CallState](#callstate)> | 是 | 回调函数，异步返回获取到的通话状态。 | **示例：** -``` +```js call.getCallState((err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); @@ -237,19 +236,19 @@ call.getCallState((err, data) => { getCallState\(\): Promise -获取通话状态，使用Promise方式作为异步方法。 +获取当前通话状态。使用Promise异步回调。 **系统能力**：SystemCapability.Telephony.CallManager **返回值：** -| 类型 | 说明 | -| -------------------------------------- | ----------------------------------------- | -| Promise<[CallState](#callstate)> | 以Promise形式异步返回获取通话状态的结果。 | +| 类型 | 说明 | +| -------------------------------------- | --------------------------------------- | +| Promise<[CallState](#callstate)> | 以Promise形式异步返回获取到的通话状态。 | **示例：** -``` +```js let promise = call.getCallState(); promise.then(data => { console.log(`getCallState success, promise: data->${JSON.stringify(data)}`); @@ -262,7 +261,7 @@ promise.then(data => { hasVoiceCapability(): boolean -检查当前设备是否具备语音通话能力，该方法是同步方法。 +检查当前设备是否具备语音通话能力。 **系统能力**：SystemCapability.Telephony.CallManager @@ -270,9 +269,9 @@ hasVoiceCapability(): boolean | 类型 | 说明 | | ------- | ------------------------------------------------------------ | -| boolean | - true：设备具备语音通话能力
- false：设备不具备语音通话能力 | +| boolean | 返回true表示设备具备语音通话能力，返回false表示设备不具备语音通话能力。 | -``` +```js let result = call.hasVoiceCapability(); console.log(`hasVoiceCapability: ${JSON.stringify(result)}`); ``` @@ -281,7 +280,7 @@ console.log(`hasVoiceCapability: ${JSON.stringify(result)}`); isEmergencyPhoneNumber\(phoneNumber: string, callback: AsyncCallback\): void -判断是否是紧急电话号码，使用callback方式作为异步方法。 +判断是否是紧急电话号码。使用callback异步回调。 **系统能力**：SystemCapability.Telephony.CallManager @@ -290,11 +289,11 @@ isEmergencyPhoneNumber\(phoneNumber: string, callback: AsyncCallback\) | 参数名 | 类型 | 必填 | 说明 | | ----------- | ---------------------------- | ---- | ------------------------------------------------------------ | | phoneNumber | string | 是 | 电话号码。 | -| callback | AsyncCallback<boolean> | 是 | 回调函数，返回判断是否是紧急电话号码的结果：
- true：是紧急电话号码。
- false：不是紧急电话号码。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示是紧急电话号码，返回false表示不是紧急电话号码。 | **示例：** -``` +```js call.isEmergencyPhoneNumber("138xxxxxxxx", (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); @@ -305,21 +304,21 @@ call.isEmergencyPhoneNumber("138xxxxxxxx", (err, data) => { isEmergencyPhoneNumber\(phoneNumber: string, options: EmergencyNumberOptions, callback: AsyncCallback\): void -判断是否是紧急电话号码，使用callback方式作为异步方法。 +根据电话号码参数，判断是否是紧急电话号码。使用callback异步回调。 **系统能力**：SystemCapability.Telephony.CallManager **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | ---------------------------- | ---- | ------------------------------------------------------------ | -| phoneNumber | string | 是 | 电话号码。 | -| options | EmergencyNumberOptions | 是 | 电话号码参数，参考[EmergencyNumberOptions](#emergencynumberoptions7)。 | -| callback | AsyncCallback<boolean> | 是 | 回调函数，返回判断是否是紧急电话号码的结果：
- true：是紧急电话号码。
- false：不是紧急电话号码。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | +| phoneNumber | string | 是 | 电话号码。 | +| options | [EmergencyNumberOptions](#emergencynumberoptions7) | 是 | 电话号码参数。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示是紧急电话号码，返回false表示不是紧急电话号码。 | **示例：** -``` +```js call.isEmergencyPhoneNumber("112", {slotId: 1}, (err, value) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); @@ -330,16 +329,16 @@ call.isEmergencyPhoneNumber("112", {slotId: 1}, (err, value) => { isEmergencyPhoneNumber\(phoneNumber: string, options?: EmergencyNumberOptions\): Promise -判断是否是紧急电话号码，使用promise方式作为异步方法。 +根据电话号码参数，判断是否是紧急电话号码。使用Promise异步回调。 **系统能力**：SystemCapability.Telephony.CallManager **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | ---------------------- | ---- | ------------------------------------------------------------ | -| phoneNumber | string | 是 | 电话号码。 | -| options | EmergencyNumberOptions | 是 | 电话号码参数，参考[EmergencyNumberOptions](#emergencynumberoptions7)。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | -------------------------------------------------- | ---- | -------------- | +| phoneNumber | string | 是 | 电话号码。 | +| options | [EmergencyNumberOptions](#emergencynumberoptions7) | 是 | 电话号码参数。 | **返回值：** @@ -349,7 +348,7 @@ isEmergencyPhoneNumber\(phoneNumber: string, options?: EmergencyNumberOptions\): **示例：** -``` +```js let promise = call.isEmergencyPhoneNumber("138xxxxxxxx", {slotId: 1}); promise.then(data => { console.log(`isEmergencyPhoneNumber success, promise: data->${JSON.stringify(data)}`); @@ -362,7 +361,9 @@ promise.then(data => { formatPhoneNumber\(phoneNumber: string, callback: AsyncCallback\): void -格式化电话号码，使用callback方式作为异步方法。 +格式化电话号码。使用callback异步回调。 + +电话号码格式化后为标准数字字串，例如：“138 xxxx xxxx”、“0755 xxxx xxxx”。 **系统能力**：SystemCapability.Telephony.CallManager @@ -375,32 +376,33 @@ formatPhoneNumber\(phoneNumber: string, callback: AsyncCallback\): void **示例：** -``` +```js call.formatPhoneNumber("138xxxxxxxx", (err, data) => { console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); }); ``` - ## call.formatPhoneNumber7+ formatPhoneNumber\(phoneNumber: string, options: NumberFormatOptions, callback: AsyncCallback\): void -格式化电话号码，可设置格式化参数，使用callback方式作为异步方法。 +格式化电话号码，可设置格式化参数。使用callback异步回调。 + +电话号码格式化后为标准数字字串，例如：“138 xxxx xxxx”、“0755 xxxx xxxx”。 **系统能力**：SystemCapability.Telephony.CallManager **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | -| phoneNumber | string | 是 | 电话号码。 | -| options | NumberFormatOptions | 是 | 格式化参数，参考[NumberFormatOptions](#numberformatoptions7)。 | -| callback | AsyncCallback<string> | 是 | 回调函数，返回格式化电话号码的结果。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | -------------------------------------------- | ---- | ------------------------------------ | +| phoneNumber | string | 是 | 电话号码。 | +| options | [NumberFormatOptions](#numberformatoptions7) | 是 | 格式化参数，如国家码。 | +| callback | AsyncCallback<string> | 是 | 回调函数，返回格式化电话号码的结果。 | **示例：** -``` +```js call.formatPhoneNumber("138xxxxxxxx",{ countryCode: "CN" }, (err, data) => { @@ -413,16 +415,18 @@ call.formatPhoneNumber("138xxxxxxxx",{ formatPhoneNumber\(phoneNumber: string, options?: NumberFormatOptions\): Promise -格式化电话号码，可设置格式化参数，使用promise方式作为异步方法。 +格式化电话号码，可设置格式化参数。使用Promise异步回调。 + +电话号码格式化后为标准数字字串，例如：“138 xxxx xxxx”、“0755 xxxx xxxx”。 **系统能力**：SystemCapability.Telephony.CallManager **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ----------- | ------------------- | ---- | ------------------------------------------------------------ | -| phoneNumber | string | 是 | 电话号码。 | -| options | NumberFormatOptions | 是 | 格式化参数，参考[NumberFormatOptions](#numberformatoptions7)。 | +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | -------------------------------------------- | ---- | ---------------------- | +| phoneNumber | string | 是 | 电话号码。 | +| options | [NumberFormatOptions](#numberformatoptions7) | 是 | 格式化参数，如国家码。 | **返回值：** @@ -432,7 +436,7 @@ formatPhoneNumber\(phoneNumber: string, options?: NumberFormatOptions\): Promise **示例：** -``` +```js let promise = call.formatPhoneNumber("138xxxxxxxx", { countryCode: "CN" }); @@ -447,11 +451,9 @@ promise.then(data => { formatPhoneNumberToE164\(phoneNumber: string, countryCode: string, callback: AsyncCallback\): void -将电话号码格式化为E.164表示形式，使用callback方式作为异步方法。 +将电话号码格式化为E.164表示形式。使用callback异步回调。 -需要格式化的电话号码需要与传入国家码相匹配，如中国电话号码需要传入国家码CN，否则格式化后的电话号码为null。 - -支持所有国家码。 +待格式化的电话号码需要与传入的国家码相匹配，如中国电话号码需要传入国家码CN，否则格式化后的电话号码为null。 **系统能力**：SystemCapability.Telephony.CallManager @@ -465,7 +467,7 @@ formatPhoneNumberToE164\(phoneNumber: string, countryCode: string, callback: Asy **示例：** -``` +```js call.formatPhoneNumberToE164("138xxxxxxxx",{ countryCode: "CN" }, (err, data) => { @@ -478,9 +480,9 @@ call.formatPhoneNumberToE164("138xxxxxxxx",{ formatPhoneNumberToE164\(phoneNumber: string, countryCode: string\): Promise -将电话号码格式化为E.164表示形式，使用promise方式作为异步方法。 +将电话号码格式化为E.164表示形式。使用Promise异步回调。 -需要格式化的电话号码需要与传入国家码相匹配，如中国电话号码需要传入国家码CN，否则格式化后的电话号码为null。 +待格式化的电话号码需要与传入的国家码相匹配，如中国电话号码需要传入国家码CN，否则格式化后的电话号码为null。 支持所有国家码。 @@ -501,7 +503,7 @@ formatPhoneNumberToE164\(phoneNumber: string, countryCode: string\): Promise { **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------------------------------------ | -| slotId | number | 否 | 卡槽ID：
- 0：卡槽1。
- 1：卡槽2。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------------------------------- | +| slotId | number | 否 | 卡槽ID：
- 卡槽1：`0`。
- 卡槽2：`1`。 | ## NumberFormatOptions7+ @@ -553,4 +555,4 @@ promise.then(data => { | 参数名 | 类型 | 必填 | 说明 | | ----------- | ------ | ---- | ---------------------------------------------------------- | -| countryCode | string | 否 | 国家码，支持所有国家的国家码，如：中国（CN）。默认为：CN。 | \ No newline at end of file +| countryCode | string | 否 | 国家码，支持所有国家的国家码，如：CN（中国）。默认为：CN。 | \ No newline at end of file