引言

移动应用的核心能力依赖网络通信，而蜂窝网络是移动设备最基础的联网方式。无论是即时通讯、视频播放还是在线支付，开发者都需要了解当前设备的无线接入技术（2G/3G/4G/5G）、信号强度等级、网络注册状态以及 SIM 卡状态。HarmonyOS NEXT 通过 @ohos.telephony.radio 和 @ohos.telephony.sim 两个模块将这些蜂窝网络信息统一暴露。

@ohos.telephony.radio 和 @ohos.telephony.sim 同属 @kit.TelephonyKit，分别负责无线接入技术和 SIM 卡管理。与 Android 的 TelephonyManager（单一大类包含所有电话功能）和 iOS 的 CTTelephonyNetworkInfo（仅限蜂窝网络信息）相比，鸿蒙将无线和 SIM 拆分为两个职责清晰的子模块——radio 专注无线技术栈（制式/信号/注册），sim 专注 SIM 卡状态。

本文将深入讲解 @ohos.telephony.radio 的无线技术查询、信号信息获取、网络状态监测和 @ohos.telephony.sim 的 SIM 卡状态读取四大核心能力，并构建一个"蜂窝网络实验室"Demo，在一个页面中完整展示蜂窝网络的全部诊断信息。

一、API 架构：radio 与 sim 的双模块设计

1.1 核心设计理念

@kit.TelephonyKit 将蜂窝网络能力拆分为四个子模块：radio（无线接入）、sim（SIM 卡）、data（数据连接）、observer（状态观察）。本文聚焦最常用的 radio 和 sim 两个子模块。

import radio from '@ohos.telephony.radio';
import sim from '@ohos.telephony.sim';

// radio：同步获取无线接入技术
const rt = radio.getRadioTechSync(0);  // slotId = 0（SIM 卡槽1）
// rt.psRadioTech — 分组交换域（数据）的无线技术
// rt.csRadioTech — 电路交换域（语音）的无线技术

// radio：同步获取信号信息
const signals = radio.getSignalInformationSync(0);
// signals[0].signalLevel — 信号强度等级（0-5）

// radio：异步获取网络注册状态
radio.getNetworkState(0).then((ns) => {
  // ns.regState — 注册状态
  // ns.cfgTech — 当前无线技术
  // ns.nsaState — 5G NSA 状态
});

// sim：同步获取 SIM 卡状态
const state = sim.getSimStateSync(0);
// SimState.SIM_STATE_READY / NOT_PRESENT / LOCKED / etc.

这种双模块设计带来三个好处：

• 职责单一：radio 只管无线信号和技术，sim 只管 SIM 卡，不会出现一个模块几十个方法的混乱情况
• 同步优先：所有即时可获取的信息（无线技术、信号等级、SIM 状态）都提供 Sync 同步方法，零延迟
• 异步补充：网络状态查询（需要与基带通信）使用 Promise 异步模式

1.2 getRadioTechSync —— 无线接入技术

getRadioTechSync(slotId: number) 同步返回 NetworkRadioTech 对象，包含两个字段：

字段	说明	典型值
psRadioTech	分组交换域（PS）的无线接入技术	LTE (4G)、NR (5G)
csRadioTech	电路交换域（CS）的无线接入技术	WCDMA (3G)、LTE (VoLTE)

PS 域（Packet Switched）承载数据业务——上网、视频、消息等。CS 域（Circuit Switched）承载语音通话。在 4G 时代，VoLTE（Voice over LTE）将语音也搬到了 PS 域；在 5G 时代，VoNR（Voice over NR）进一步演进。通过 psRadioTech 和 csRadioTech 可以精确判断当前设备的数据和语音承载方式。

RadioTechnology 枚举是蜂窝网络技术的完整谱系：

枚举值	说明	代际
RADIO_TECHNOLOGY_GSM	GSM	2G
RADIO_TECHNOLOGY_1XRTT	CDMA 1xRTT	2G
RADIO_TECHNOLOGY_WCDMA	WCDMA	3G
RADIO_TECHNOLOGY_HSPA	HSPA	3G
RADIO_TECHNOLOGY_HSPAP	HSPA+	3.5G
RADIO_TECHNOLOGY_TD_SCDMA	TD-SCDMA	3G
RADIO_TECHNOLOGY_LTE	LTE	4G
RADIO_TECHNOLOGY_LTE_CA	LTE-A（载波聚合）	4G+
RADIO_TECHNOLOGY_NR	New Radio	5G

private techLabel(tech: radio.RadioTechnology): string {
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_GSM) return 'GSM (2G)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_LTE) return 'LTE (4G)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_LTE_CA) return 'LTE-A (4G+)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_NR) return 'NR (5G)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_WCDMA) return 'WCDMA (3G)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_HSPA) return 'HSPA (3G)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_HSPAP) return 'HSPA+ (3G)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_TD_SCDMA) return 'TD-SCDMA (3G)';
  if (tech === radio.RadioTechnology.RADIO_TECHNOLOGY_1XRTT) return '1xRTT (2G)';
  return '其他';
}

1.3 getSignalInformationSync —— 信号强度

getSignalInformationSync(slotId) 同步返回 Array<SignalInformation> 数组。每个 SignalInformation 对象中最重要的字段是 signalLevel——信号强度等级，取值范围为 0-5（部分设备可能为 0-4）。数值越大表示信号越好。

const infos = radio.getSignalInformationSync(0);
if (infos.length > 0) {
  const level = infos[0].signalLevel;
  // level: 0=无信号, 1-2=较弱, 3=一般, 4=良好, 5=优秀
}

信号强度分级策略：

if (level >= 5) {
  label = '优秀';
} else if (level >= 4) {
  label = '良好';
} else if (level >= 3) {
  label = '一般';
} else if (level >= 1) {
  label = '较弱';
} else {
  label = '无信号';
}

Demo 中通过可视化信号格直观展示信号强度——5 段竖条，填充颜色根据信号等级自动变化：绿（优秀）、蓝（良好）、黄（一般）、红（较弱）、灰（无信号）。

1.4 getNetworkState —— 网络注册状态

getNetworkState(slotId?) 是 radio 模块中唯一的异步 API，返回 Promise<NetworkState>。NetworkState 对象包含多个字段：

字段	类型	说明
regState	RegState	网络注册状态
cfgTech	RadioTechnology	当前配置的无线技术
nsaState	NsaState	5G NSA 组网状态
longOperatorName	string	运营商全称（如 “中国移动”）
shortOperatorName	string	运营商简称（如 “CMCC”）
plmnNumeric	string	PLMN 数字代码
isRoaming	boolean	是否漫游
isCaActive	boolean	CA 载波聚合是否激活
isEmergency	boolean	是否仅限紧急呼叫

RegState 注册状态枚举：

值	枚举	说明
0	REG_STATE_NO_SERVICE	无服务（信号盲区或飞行模式）
1	REG_STATE_IN_SERVICE	已注册（正常使用）
2	REG_STATE_EMERGENCY_CALL_ONLY	仅紧急呼叫（无 SIM 卡或欠费）
3	REG_STATE_POWER_OFF	无线已关闭（飞行模式）

NsaState 5G NSA 状态枚举：

值	枚举	说明
1	NSA_STATE_NOT_SUPPORT	LTE 小区不支持 NSA
2	NSA_STATE_NO_DETECT	支持 NSA 但未检测到 NR 覆盖
3	NSA_STATE_CONNECTED_DETECT	LTE 连接下检测到 NR 覆盖
4	NSA_STATE_IDLE_DETECT	LTE 空闲下检测到 NR 覆盖
5	NSA_STATE_DUAL_CONNECTED	EN-DC 双连接已激活（真正的 5G）

NSA（Non-Standalone）是 5G 早期部署的主要模式——手机同时连接 4G LTE（锚点）和 5G NR（数据增强）。nsaState 的五个状态精确描述了设备从"不支持"到"完全 5G 双连接"的全过程。

二、@ohos.telephony.sim —— SIM 卡管理

2.1 getSimStateSync —— SIM 卡状态

getSimStateSync(slotId) 同步返回 SimState 枚举值，表示 SIM 卡的当前状态：

枚举值	说明
SIM_STATE_READY	SIM 卡就绪，可以正常使用
SIM_STATE_NOT_PRESENT	卡槽为空，未检测到 SIM 卡
SIM_STATE_LOCKED	SIM 卡已锁定（需要 PIN/PUK 解锁）
SIM_STATE_NOT_READY	SIM 卡存在但未初始化完成
SIM_STATE_LOADED	SIM 卡数据已加载（联系人等）

const st = sim.getSimStateSync(0);
if (st === sim.SimState.SIM_STATE_READY) {
  // SIM 卡正常，可以获取更多信息
} else if (st === sim.SimState.SIM_STATE_NOT_PRESENT) {
  // 设备未插卡
}

2.2 getISOCountryCodeForSimSync —— 运营商国家代码

getISOCountryCodeForSimSync(slotId) 同步返回 ISO 国家代码字符串（如 “cn”、“us”、“jp”），用于判断 SIM 卡的归属国家。

const code = sim.getISOCountryCodeForSimSync(0);
// 返回 "cn" 表示中国运营商

这个信息在国际化应用（i18n）和合规检查中非常有用——例如根据 SIM 卡国家自动切换默认语言或判断内容分发区域。

三、实战 Demo：蜂窝网络实验室

3.1 页面设计

"蜂窝网络实验室"页面分为六个功能区域：

1. 信号强度面板：大字显示信号等级标签（优秀/良好/一般/较弱/无信号），颜色随等级自动变化。右侧可视化信号格——5 段竖条从矮到高，填充色与信号等级联动。下方三栏"信号级别"（Lv.0-5）、“网络注册”（已注册/无服务/仅紧急呼叫/无线关闭）和"5G NSA"（不支持/未检测/已检测/双连接）。

2. 无线接入技术双栏：左侧橙色卡片显示 PS 域（数据）的无线技术（LTE/NR/WCDMA 等），右侧橙色卡片显示 CS 域（语音）的无线技术。下方灰色说明文字解释 PS/CS 域的区别。

3. SIM 卡与网络三栏：展示 SIM 状态（就绪/无卡/锁定/未就绪）、国家代码（ISO 码）、网络类型（cfgTech 无线技术标签）。

4. 无线技术代际参考：2G（灰色）、3G（蓝色）、4G（绿色）、5G（橙色）四色卡片展示各代际对应的无线技术名称，帮助开发者快速建立认知映射。

5. 快捷操作：两个按钮——"刷新全部"重新读取 radio + sim 全部信息，"仅刷新信号"仅重新获取 SignalInformation。

6. 操作日志：记录每次 API 调用结果，时间戳 + 消息，按类别着色。

3.2 核心实现

数据模型：

@State slotId: number = 0;
@State radioTech: string = '--';
@State psRadioTech: string = '--';
@State csRadioTech: string = '--';
@State networkType: string = '--';
@State regState: string = '--';
@State nsaState: string = '--';
@State simState: string = '--';
@State isoCode: string = '--';
@State signalLevel: string = '--';
@State signalLevelNum: number = 0;
@State loading: boolean = false;

slotId 固定为 0（主卡槽），适用于大多数单卡设备。双卡设备需要传入 0 或 1 区分卡槽。

信号格可视化：

private signalBarColor(index: number): string {
  if (index <= this.signalLevelNum) {
    if (this.signalLevelNum >= 4) return '#10B981';      // 绿色
    if (this.signalLevelNum >= 3) return '#3B82F6';      // 蓝色
    if (this.signalLevelNum >= 2) return '#F59E0B';      // 黄色
    return '#EF4444';                                     // 红色
  }
  return '#E2E8F0';  // 未激活段：灰色
}

5 段竖条高度从 12px 递增到 36px，通过 signalBarColor(index) 控制每一段的填充颜色。信号等级为 5 时全部 5 段亮绿色，等级为 0 时全部灰色。

状态枚举标签转换：

private simLabel(state: sim.SimState): string {
  if (state === sim.SimState.SIM_STATE_READY) return 'SIM 就绪';
  if (state === sim.SimState.SIM_STATE_NOT_PRESENT) return '无 SIM 卡';
  if (state === sim.SimState.SIM_STATE_LOCKED) return 'SIM 已锁定';
  if (state === sim.SimState.SIM_STATE_NOT_READY) return 'SIM 未就绪';
  if (state === sim.SimState.SIM_STATE_LOADED) return 'SIM 已加载';
  return '未知';
}

private regLabel(rs: radio.RegState): string {
  if (rs === radio.RegState.REG_STATE_NO_SERVICE) return '无服务';
  if (rs === radio.RegState.REG_STATE_IN_SERVICE) return '已注册';
  if (rs === radio.RegState.REG_STATE_EMERGENCY_CALL_ONLY) return '仅紧急呼叫';
  if (rs === radio.RegState.REG_STATE_POWER_OFF) return '无线关闭';
  return '未知';
}

3.3 交互方式

Demo 提供两个核心交互点：

1. 刷新全部：一口气执行 refreshRadio() → refreshSim() → refreshSignal() → refreshNetworkType() 四个方法，更新页面上所有蜂窝网络信息。loading 状态在刷新期间禁用按钮防止重复点击。

2. 仅刷新信号：只重新调用 getSignalInformationSync() 更新信号强度和信号格可视化。信号强度是唯一频繁变化的指标（移动中、进出电梯时会波动），独立刷新按钮允许用户单独追踪信号变化。

3. 自动刷新：页面进入（aboutToAppear）时自动执行一次全量刷新，确保首次展示即显示最新数据。

四、实际应用场景

4.1 弱网场景下的自适应策略

function getNetworkQuality(): 'excellent' | 'good' | 'poor' {
  const signals = radio.getSignalInformationSync(0);
  if (signals.length === 0) return 'poor';
  const level = signals[0].signalLevel;
  if (level >= 4) return 'excellent';
  if (level >= 2) return 'good';
  return 'poor';
}

// 根据网络质量调整视频清晰度
const quality = getNetworkQuality();
if (quality === 'poor') {
  videoPlayer.setResolution('360p');
} else if (quality === 'good') {
  videoPlayer.setResolution('720p');
} else {
  videoPlayer.setResolution('1080p');
}

4.2 5G 能力检测

function supports5G(): boolean {
  const rt = radio.getRadioTechSync(0);
  return rt.psRadioTech === radio.RadioTechnology.RADIO_TECHNOLOGY_NR;
}

async function is5GConnected(): Promise<boolean> {
  const ns = await radio.getNetworkState(0);
  return ns.nsaState === radio.NsaState.NSA_STATE_DUAL_CONNECTED;
}

4.3 SIM 卡异常检测

function checkSimReady(): string {
  const st = sim.getSimStateSync(0);
  switch (st) {
    case sim.SimState.SIM_STATE_READY:
      return 'OK';
    case sim.SimState.SIM_STATE_NOT_PRESENT:
      return '请插入 SIM 卡';
    case sim.SimState.SIM_STATE_LOCKED:
      return 'SIM 卡已锁定，请解锁';
    case sim.SimState.SIM_STATE_NOT_READY:
      return 'SIM 卡初始化中...';
    default:
      return 'SIM 卡异常';
  }
}

五、与网络诊断三层体系的协作

@ohos.telephony.radio/sim 与之前介绍的 @ohos.net.connection 和 @ohos.wifiManager 共同构成了 HarmonyOS 网络诊断的三层体系：

层次	模块	关注点	核心 API
连接层	@ohos.net.connection	有没有网？走哪条通道？	hasDefaultNetSync, getNetCapabilitiesSync
通道层	@ohos.wifiManager / telephony.radio	WiFi 还是蜂窝？信号多强？	isWifiActive, getRadioTechSync, getSignalInformationSync
身份层	telephony.sim / deviceInfo	谁的网？哪个运营商？	getSimStateSync, getISOCountryCodeForSimSync

三层结合可实现精确的网络诊断：

• 连接层判断：设备是否接入网络？（hasDefaultNetSync）
• 通道层判断：WiFi 还是蜂窝？信号如何？（radio 信号等级 + WiFi 信号强度）
• 身份层判断：SIM 卡是否就绪？哪个国家/运营商？

六、总结

@ohos.telephony.radio 和 @ohos.telephony.sim 是 HarmonyOS NEXT 中获取蜂窝网络信息的核心模块。通过本文的学习，你应该已经掌握：

1. 双模块职责分离：radio 负责无线接入技术查询和信号信息获取（getRadioTechSync、getSignalInformationSync、getNetworkState），sim 负责 SIM 卡状态和运营商识别（getSimStateSync、getISOCountryCodeForSimSync）
2. RadioTechnology 全谱系：从 GSM（2G）到 NR（5G），9 个枚举值覆盖全部蜂窝代际，PS 域和 CS 域分别指示数据和语音承载方式
3. 信号强度可视化：signalLevel（0-5）驱动 5 段信号格 + 颜色分级（绿/蓝/黄/红/灰），直观展示信号质量
4. 5G NSA 状态精确感知：5 种 NsaState 枚举值详细描述从"不支持"到"EN-DC 双连接激活"的全过程
5. RegState 识别：4 种注册状态（无服务/已注册/仅紧急呼叫/无线关闭）覆盖全部网络可用性场景

@ohos.telephony.radio/sim 的最佳使用模式可以总结为：

应用启动时用 getRadioTechSync + getSimStateSync 建立网络画像，网络请求前用 getSignalInformationSync 判断信号质量决定资源策略，异常场景用 RegState 和 SimState 枚举精确定位问题根源。所有基础查询均为同步 API——零延迟、无权限。

蜂窝网络信息是移动应用的基础能力。@kit.TelephonyKit 通过 radio 和 sim 两个子模块的职责分离，将复杂的蜂窝网络协议栈简化为几个清晰的枚举和同步方法。与 @ohos.net.connection（网络连通检测）和 @ohos.wifiManager（WiFi 管理）配合，开发者可以构建完整的"连接 + 通道 + 信号"三层网络诊断工具，覆盖从网络可用性到信号质量的全部维度。