Expo 蜂窝网络

一个提供用户蜂窝服务提供商信息的 API。

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

Bundled version:

~7.1.5

expo-cellular 提供有关用户蜂窝服务提供商的信息，例如其唯一标识符、蜂窝连接类型，以及它是否允许在其网络上进行 VoIP 呼叫。

安装

Terminal

- npx expo install expo-cellular

If you are installing this in an existing React Native app, make sure to install expo in your project.

配置

Are you using this library in an existing React Native app?

如果你没有使用 Continuous Native Generation (CNG)，或者你正在手动使用原生 android 项目，那么你需要向项目的 AndroidManifest.xml 中添加 android.permission.READ_PHONE_STATE 权限。此权限用于 TelephonyManager。

android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.READ_PHONE_STATE" />

此库不需要更高风险的 READ_PRIVILEGED_PHONE_STATE 权限。

API

import * as Cellular from 'expo-cellular';

Constants

Deprecated: Use allowsVoipAsync() instead.

`Cellular.allowsVoip`

Android

iOS

Web

Type: boolean | null

Indicates if the carrier allows making VoIP calls on its network. On Android, this checks whether the system supports SIP-based VoIP API. See the Android documentation for more information.

On iOS, if you configure a device for a carrier and then remove the SIM card, this property retains the boolean value indicating the carrier’s policy regarding VoIP. If you then install a new SIM card, its VoIP policy boolean replaces the previous value of this property.

On web, this returns null.

Example

Cellular.allowsVoip; // true or false

Deprecated: Use getCarrierNameAsync() instead.

`Cellular.carrier`

Android

iOS

Web

Type: string | null

The name of the user’s home cellular service provider. If the device has dual SIM cards, only the carrier for the currently active SIM card will be returned. On Android, this value is only available when the SIM state is SIM_STATE_READY. Otherwise, this returns null.

On iOS, if you configure a device for a carrier and then remove the SIM card, this property retains the name of the carrier. If you then install a new SIM card, its carrier name replaces the previous value of this property. The value for this property is null if the user never configured a carrier for the device.

On web, this returns null.

Example

Cellular.carrier; // "T-Mobile" or "Verizon"

Deprecated: Use getIsoCountryCodeAsync() instead.

`Cellular.isoCountryCode`

Android

iOS

Web

Type: string | null

The ISO country code for the user’s cellular service provider. On iOS, the value is null if any of the following apply:

The device is in airplane mode.
There is no SIM card in the device.
The device is outside of cellular service range.

On web, this returns null.

Example

Cellular.isoCountryCode; // "us" or "au"

Deprecated: Use getMobileCountryCodeAsync() instead.

`Cellular.mobileCountryCode`

Android

iOS

Web

Type: string | null

The mobile country code (MCC) for the user’s current registered cellular service provider. On Android, this value is only available when SIM state is SIM_STATE_READY. Otherwise, this returns null. On iOS, the value may be null on hardware prior to iPhone 4S when in airplane mode. Furthermore, the value for this property is null if any of the following apply:

There is no SIM card in the device.
The device is outside of cellular service range.

On web, this returns null.

Example

Cellular.mobileCountryCode; // "310"

Deprecated: Use getMobileNetworkCodeAsync() instead.

`Cellular.mobileNetworkCode`

Android

iOS

Web

Type: string | null

The ISO country code for the user’s cellular service provider. On iOS, the value is null if any of the following apply:

The device is in airplane mode.
There is no SIM card in the device.
The device is outside of cellular service range.

On web, this returns null.

Example

Cellular.mobileNetworkCode; // "260"

Hooks

`usePermissions(options)`

Android

iOS

Web

Parameter	Type
options(optional)	`PermissionHookOptions<object>`

Check or request permissions to access the phone state. This uses both Cellular.requestPermissionsAsync and Cellular.getPermissionsAsync to interact with the permissions.

Returns:

[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

Example

const [status, requestPermission] = Cellular.usePermissions();

Methods

`Cellular.allowsVoipAsync()`

Android

iOS

Web

Returns:

Promise<boolean | null>

Returns if the carrier allows making VoIP calls on its network. On Android, this checks whether the system supports SIP-based VoIP API. See here to view more information.

On web, this returns null.

Example

await Cellular.allowsVoipAsync(); // true or false

`Cellular.getCarrierNameAsync()`

Android

iOS

Web

Returns:

Promise<string | null>

Returns name of the user’s home cellular service provider. If the device has dual SIM cards, only the carrier for the currently active SIM card will be returned.

On Android, this value is only available when the SIM state is SIM_STATE_READY. Otherwise, this returns null.

On web, this returns null.

Example

await Cellular.getCarrierNameAsync(); // "T-Mobile" or "Verizon"

`Cellular.getCellularGenerationAsync()`

Android

iOS

Web

Returns:

Promise<CellularGeneration>

Returns a promise which fulfils with a Cellular.CellularGeneration enum value that represents the current cellular-generation type.

You will need to check if the native permission has been accepted to obtain generation. If the permission is denied getCellularGenerationAsync will resolve to Cellular.Cellular Generation.UNKNOWN.

On web, this method uses navigator.connection.effectiveType to detect the effective type of the connection using a combination of recently observed round-trip time and downlink values. See here to view browser compatibility.

Example

await Cellular.getCellularGenerationAsync();
// CellularGeneration.CELLULAR_4G

`Cellular.getIsoCountryCodeAsync()`

Android

iOS

Web

Returns:

Promise<string | null>

Returns the ISO country code for the user’s cellular service provider.

On iOS, the value is null if any of the following apply:

The device is in airplane mode.
There is no SIM card in the device.
The device is outside of cellular service range.

On web, this returns null.

Example

await Cellular.getIsoCountryCodeAsync(); // "us" or "au"

`Cellular.getMobileCountryCodeAsync()`

Android

iOS

Web

Returns:

Promise<string | null>

Returns mobile country code (MCC) for the user’s current registered cellular service provider.

On Android, this value is only available when SIM state is SIM_STATE_READY. Otherwise, this returns null. On iOS, the value may be null on hardware prior to iPhone 4S when in airplane mode. Furthermore, the value for this property is null if any of the following apply:

There is no SIM card in the device.
The device is outside of cellular service range.

On web, this returns null.

Example

await Cellular.getMobileCountryCodeAsync(); // "310"

`Cellular.getMobileNetworkCodeAsync()`

Android

iOS

Web

Returns:

Promise<string | null>

Returns the mobile network code (MNC) for the user’s current registered cellular service provider.

There is no SIM card in the device.
The device is outside of cellular service range.

On web, this returns null.

Example

await Cellular.getMobileNetworkCodeAsync(); // "310"

`Cellular.getPermissionsAsync()`

Android

iOS

Web

Checks user's permissions for accessing phone state.

Returns:

Promise<PermissionResponse>

`Cellular.requestPermissionsAsync()`

Android

iOS

Web

Asks the user to grant permissions for accessing the phone state.

Returns:

Promise<PermissionResponse>

Enums

`CellularGeneration`

Android

iOS

Web

Describes the current generation of the cellular connection. It is an enum with these possible values:

`UNKNOWN`

CellularGeneration.UNKNOWN ＝ 0

Either we are not currently connected to a cellular network or type could not be determined.

`CELLULAR_2G`

CellularGeneration.CELLULAR_2G ＝ 1

Currently connected to a 2G cellular network. Includes CDMA, EDGE, GPRS, and IDEN type connections.

`CELLULAR_3G`

CellularGeneration.CELLULAR_3G ＝ 2

Currently connected to a 3G cellular network. Includes EHRPD, EVDO, HSPA, HSUPA, HSDPA, HSPAP, and UTMS type connections.

`CELLULAR_4G`

CellularGeneration.CELLULAR_4G ＝ 3

Currently connected to a 4G cellular network. Includes LTE type connections.

`CELLULAR_5G`

CellularGeneration.CELLULAR_5G ＝ 4

Currently connected to a 5G cellular network. Includes NR and NRNSA type connections.

错误代码

Code	Description
ERR_CELLULAR_GENERATION_UNKNOWN_NETWORK_TYPE	无法访问网络类型，或未连接到蜂窝网络

权限

Android

你必须将以下权限添加到 app.json 中 expo.android.permissions 数组里。

Android Permission Description

Android Permission	Description
`READ_PHONE_STATE`	Allows read only access to phone state, including the current cellular network information, the status of any ongoing calls, and a list of any PhoneAccounts registered on the device. Allows read only access to phone state, including the current cellular network information, the status of any ongoing calls, and a list of any `PhoneAccount`s registered on the device.

READ_PHONE_STATE

Allows read only access to phone state, including the current cellular network information, the status of any ongoing calls, and a list of any PhoneAccounts registered on the device.

Allows read only access to phone state, including the current cellular network information, the status of any ongoing calls, and a list of any PhoneAccounts registered on the device.

iOS

无需权限。