引言移动应用的核心能力依赖网络通信而蜂窝网络是移动设备最基础的联网方式。无论是即时通讯、视频播放还是在线支付开发者都需要了解当前设备的无线接入技术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无线接入、simSIM 卡、data数据连接、observer状态观察。本文聚焦最常用的radio和sim两个子模块。importradiofromohos.telephony.radio;importsimfromohos.telephony.sim;// radio同步获取无线接入技术constrtradio.getRadioTechSync(0);// slotId 0SIM 卡槽1// rt.psRadioTech — 分组交换域数据的无线技术// rt.csRadioTech — 电路交换域语音的无线技术// radio同步获取信号信息constsignalsradio.getSignalInformationSync(0);// signals[0].signalLevel — 信号强度等级0-5// radio异步获取网络注册状态radio.getNetworkState(0).then((ns){// ns.regState — 注册状态// ns.cfgTech — 当前无线技术// ns.nsaState — 5G NSA 状态});// sim同步获取 SIM 卡状态conststatesim.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 时代VoLTEVoice over LTE将语音也搬到了 PS 域在 5G 时代VoNRVoice over NR进一步演进。通过psRadioTech和csRadioTech可以精确判断当前设备的数据和语音承载方式。RadioTechnology枚举是蜂窝网络技术的完整谱系枚举值说明代际RADIO_TECHNOLOGY_GSMGSM2GRADIO_TECHNOLOGY_1XRTTCDMA 1xRTT2GRADIO_TECHNOLOGY_WCDMAWCDMA3GRADIO_TECHNOLOGY_HSPAHSPA3GRADIO_TECHNOLOGY_HSPAPHSPA3.5GRADIO_TECHNOLOGY_TD_SCDMATD-SCDMA3GRADIO_TECHNOLOGY_LTELTE4GRADIO_TECHNOLOGY_LTE_CALTE-A载波聚合4GRADIO_TECHNOLOGY_NRNew Radio5GprivatetechLabel(tech:radio.RadioTechnology):string{if(techradio.RadioTechnology.RADIO_TECHNOLOGY_GSM)returnGSM (2G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_LTE)returnLTE (4G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_LTE_CA)returnLTE-A (4G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_NR)returnNR (5G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_WCDMA)returnWCDMA (3G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_HSPA)returnHSPA (3G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_HSPAP)returnHSPA (3G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_TD_SCDMA)returnTD-SCDMA (3G);if(techradio.RadioTechnology.RADIO_TECHNOLOGY_1XRTT)return1xRTT (2G);return其他;}1.3 getSignalInformationSync —— 信号强度getSignalInformationSync(slotId)同步返回ArraySignalInformation数组。每个SignalInformation对象中最重要的字段是signalLevel——信号强度等级取值范围为 0-5部分设备可能为 0-4。数值越大表示信号越好。constinfosradio.getSignalInformationSync(0);if(infos.length0){constlevelinfos[0].signalLevel;// level: 0无信号, 1-2较弱, 3一般, 4良好, 5优秀}信号强度分级策略if(level5){label优秀;}elseif(level4){label良好;}elseif(level3){label一般;}elseif(level1){label较弱;}else{label无信号;}Demo 中通过可视化信号格直观展示信号强度——5 段竖条填充颜色根据信号等级自动变化绿优秀、蓝良好、黄一般、红较弱、灰无信号。1.4 getNetworkState —— 网络注册状态getNetworkState(slotId?)是 radio 模块中唯一的异步 API返回PromiseNetworkState。NetworkState对象包含多个字段字段类型说明regStateRegState网络注册状态cfgTechRadioTechnology当前配置的无线技术nsaStateNsaState5G NSA 组网状态longOperatorNamestring运营商全称如 “中国移动”shortOperatorNamestring运营商简称如 “CMCC”plmnNumericstringPLMN 数字代码isRoamingboolean是否漫游isCaActivebooleanCA 载波聚合是否激活isEmergencyboolean是否仅限紧急呼叫RegState 注册状态枚举值枚举说明0REG_STATE_NO_SERVICE无服务信号盲区或飞行模式1REG_STATE_IN_SERVICE已注册正常使用2REG_STATE_EMERGENCY_CALL_ONLY仅紧急呼叫无 SIM 卡或欠费3REG_STATE_POWER_OFF无线已关闭飞行模式NsaState 5G NSA 状态枚举值枚举说明1NSA_STATE_NOT_SUPPORTLTE 小区不支持 NSA2NSA_STATE_NO_DETECT支持 NSA 但未检测到 NR 覆盖3NSA_STATE_CONNECTED_DETECTLTE 连接下检测到 NR 覆盖4NSA_STATE_IDLE_DETECTLTE 空闲下检测到 NR 覆盖5NSA_STATE_DUAL_CONNECTEDEN-DC 双连接已激活真正的 5GNSANon-Standalone是 5G 早期部署的主要模式——手机同时连接 4G LTE锚点和 5G NR数据增强。nsaState的五个状态精确描述了设备从不支持到完全 5G 双连接的全过程。二、ohos.telephony.sim —— SIM 卡管理2.1 getSimStateSync —— SIM 卡状态getSimStateSync(slotId)同步返回SimState枚举值表示 SIM 卡的当前状态枚举值说明SIM_STATE_READYSIM 卡就绪可以正常使用SIM_STATE_NOT_PRESENT卡槽为空未检测到 SIM 卡SIM_STATE_LOCKEDSIM 卡已锁定需要 PIN/PUK 解锁SIM_STATE_NOT_READYSIM 卡存在但未初始化完成SIM_STATE_LOADEDSIM 卡数据已加载联系人等conststsim.getSimStateSync(0);if(stsim.SimState.SIM_STATE_READY){// SIM 卡正常可以获取更多信息}elseif(stsim.SimState.SIM_STATE_NOT_PRESENT){// 设备未插卡}2.2 getISOCountryCodeForSimSync —— 运营商国家代码getISOCountryCodeForSimSync(slotId)同步返回 ISO 国家代码字符串如 “cn”、“us”、“jp”用于判断 SIM 卡的归属国家。constcodesim.getISOCountryCodeForSimSync(0);// 返回 cn 表示中国运营商这个信息在国际化应用i18n和合规检查中非常有用——例如根据 SIM 卡国家自动切换默认语言或判断内容分发区域。三、实战 Demo蜂窝网络实验室3.1 页面设计蜂窝网络实验室页面分为六个功能区域信号强度面板大字显示信号等级标签优秀/良好/一般/较弱/无信号颜色随等级自动变化。右侧可视化信号格——5 段竖条从矮到高填充色与信号等级联动。下方三栏信号级别Lv.0-5、“网络注册”已注册/无服务/仅紧急呼叫/无线关闭和5G NSA不支持/未检测/已检测/双连接。无线接入技术双栏左侧橙色卡片显示 PS 域数据的无线技术LTE/NR/WCDMA 等右侧橙色卡片显示 CS 域语音的无线技术。下方灰色说明文字解释 PS/CS 域的区别。SIM 卡与网络三栏展示 SIM 状态就绪/无卡/锁定/未就绪、国家代码ISO 码、网络类型cfgTech 无线技术标签。无线技术代际参考2G灰色、3G蓝色、4G绿色、5G橙色四色卡片展示各代际对应的无线技术名称帮助开发者快速建立认知映射。快捷操作两个按钮——刷新全部重新读取 radio sim 全部信息仅刷新信号仅重新获取 SignalInformation。操作日志记录每次 API 调用结果时间戳 消息按类别着色。3.2 核心实现数据模型StateslotId:number0;StateradioTech:string--;StatepsRadioTech:string--;StatecsRadioTech:string--;StatenetworkType:string--;StateregState:string--;StatensaState:string--;StatesimState:string--;StateisoCode:string--;StatesignalLevel:string--;StatesignalLevelNum:number0;Stateloading:booleanfalse;slotId固定为 0主卡槽适用于大多数单卡设备。双卡设备需要传入 0 或 1 区分卡槽。信号格可视化privatesignalBarColor(index:number):string{if(indexthis.signalLevelNum){if(this.signalLevelNum4)return#10B981;// 绿色if(this.signalLevelNum3)return#3B82F6;// 蓝色if(this.signalLevelNum2)return#F59E0B;// 黄色return#EF4444;// 红色}return#E2E8F0;// 未激活段灰色}5 段竖条高度从 12px 递增到 36px通过signalBarColor(index)控制每一段的填充颜色。信号等级为 5 时全部 5 段亮绿色等级为 0 时全部灰色。状态枚举标签转换privatesimLabel(state:sim.SimState):string{if(statesim.SimState.SIM_STATE_READY)returnSIM 就绪;if(statesim.SimState.SIM_STATE_NOT_PRESENT)return无 SIM 卡;if(statesim.SimState.SIM_STATE_LOCKED)returnSIM 已锁定;if(statesim.SimState.SIM_STATE_NOT_READY)returnSIM 未就绪;if(statesim.SimState.SIM_STATE_LOADED)returnSIM 已加载;return未知;}privateregLabel(rs:radio.RegState):string{if(rsradio.RegState.REG_STATE_NO_SERVICE)return无服务;if(rsradio.RegState.REG_STATE_IN_SERVICE)return已注册;if(rsradio.RegState.REG_STATE_EMERGENCY_CALL_ONLY)return仅紧急呼叫;if(rsradio.RegState.REG_STATE_POWER_OFF)return无线关闭;return未知;}3.3 交互方式Demo 提供两个核心交互点刷新全部一口气执行refreshRadio()→refreshSim()→refreshSignal()→refreshNetworkType()四个方法更新页面上所有蜂窝网络信息。loading状态在刷新期间禁用按钮防止重复点击。仅刷新信号只重新调用getSignalInformationSync()更新信号强度和信号格可视化。信号强度是唯一频繁变化的指标移动中、进出电梯时会波动独立刷新按钮允许用户单独追踪信号变化。自动刷新页面进入aboutToAppear时自动执行一次全量刷新确保首次展示即显示最新数据。四、实际应用场景4.1 弱网场景下的自适应策略functiongetNetworkQuality():excellent|good|poor{constsignalsradio.getSignalInformationSync(0);if(signals.length0)returnpoor;constlevelsignals[0].signalLevel;if(level4)returnexcellent;if(level2)returngood;returnpoor;}// 根据网络质量调整视频清晰度constqualitygetNetworkQuality();if(qualitypoor){videoPlayer.setResolution(360p);}elseif(qualitygood){videoPlayer.setResolution(720p);}else{videoPlayer.setResolution(1080p);}4.2 5G 能力检测functionsupports5G():boolean{constrtradio.getRadioTechSync(0);returnrt.psRadioTechradio.RadioTechnology.RADIO_TECHNOLOGY_NR;}asyncfunctionis5GConnected():Promiseboolean{constnsawaitradio.getNetworkState(0);returnns.nsaStateradio.NsaState.NSA_STATE_DUAL_CONNECTED;}4.3 SIM 卡异常检测functioncheckSimReady():string{conststsim.getSimStateSync(0);switch(st){casesim.SimState.SIM_STATE_READY:returnOK;casesim.SimState.SIM_STATE_NOT_PRESENT:return请插入 SIM 卡;casesim.SimState.SIM_STATE_LOCKED:returnSIM 卡已锁定请解锁;casesim.SimState.SIM_STATE_NOT_READY:returnSIM 卡初始化中...;default:returnSIM 卡异常;}}五、与网络诊断三层体系的协作ohos.telephony.radio/sim与之前介绍的ohos.net.connection和ohos.wifiManager共同构成了 HarmonyOS 网络诊断的三层体系层次模块关注点核心 API连接层ohos.net.connection有没有网走哪条通道hasDefaultNetSync, getNetCapabilitiesSync通道层ohos.wifiManager / telephony.radioWiFi 还是蜂窝信号多强isWifiActive, getRadioTechSync, getSignalInformationSync身份层telephony.sim / deviceInfo谁的网哪个运营商getSimStateSync, getISOCountryCodeForSimSync三层结合可实现精确的网络诊断连接层判断设备是否接入网络hasDefaultNetSync通道层判断WiFi 还是蜂窝信号如何radio 信号等级 WiFi 信号强度身份层判断SIM 卡是否就绪哪个国家/运营商六、总结ohos.telephony.radio和ohos.telephony.sim是 HarmonyOS NEXT 中获取蜂窝网络信息的核心模块。通过本文的学习你应该已经掌握双模块职责分离radio 负责无线接入技术查询和信号信息获取getRadioTechSync、getSignalInformationSync、getNetworkStatesim 负责 SIM 卡状态和运营商识别getSimStateSync、getISOCountryCodeForSimSyncRadioTechnology 全谱系从 GSM2G到 NR5G9 个枚举值覆盖全部蜂窝代际PS 域和 CS 域分别指示数据和语音承载方式信号强度可视化signalLevel0-5驱动 5 段信号格 颜色分级绿/蓝/黄/红/灰直观展示信号质量5G NSA 状态精确感知5 种 NsaState 枚举值详细描述从不支持到EN-DC 双连接激活的全过程RegState 识别4 种注册状态无服务/已注册/仅紧急呼叫/无线关闭覆盖全部网络可用性场景ohos.telephony.radio/sim的最佳使用模式可以总结为应用启动时用 getRadioTechSync getSimStateSync 建立网络画像网络请求前用 getSignalInformationSync 判断信号质量决定资源策略异常场景用 RegState 和 SimState 枚举精确定位问题根源。所有基础查询均为同步 API——零延迟、无权限。蜂窝网络信息是移动应用的基础能力。kit.TelephonyKit通过 radio 和 sim 两个子模块的职责分离将复杂的蜂窝网络协议栈简化为几个清晰的枚举和同步方法。与ohos.net.connection网络连通检测和ohos.wifiManagerWiFi 管理配合开发者可以构建完整的连接 通道 信号三层网络诊断工具覆盖从网络可用性到信号质量的全部维度。
