鸿蒙新特性：@ohos.telephony.radio/sim 蜂窝网络实验室实战 —— 无线技术、信号强度与 SIM 卡

引言

移动应用的核心能力依赖网络通信，而蜂窝网络是移动设备最基础的联网方式。无论是即时通讯、视频播放还是在线支付，开发者都需要了解当前设备的无线接入技术（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两个子模块。

importradiofrom'@ohos.telephony.radio';importsimfrom'@ohos.telephony.sim';// radio：同步获取无线接入技术constrt=radio.getRadioTechSync(0);// slotId = 0（SIM 卡槽1）// rt.psRadioTech — 分组交换域（数据）的无线技术// rt.csRadioTech — 电路交换域（语音）的无线技术// radio：同步获取信号信息constsignals=radio.getSignalInformationSync(0);// signals[0].signalLevel — 信号强度等级（0-5）// radio：异步获取网络注册状态radio.getNetworkState(0).then((ns)=>{// ns.regState — 注册状态// ns.cfgTech — 当前无线技术// ns.nsaState — 5G NSA 状态});// sim：同步获取 SIM 卡状态conststate=sim.getSimStateSync(0);// SimState.SIM_STATE_READY / NOT_PRESENT / LOCKED / etc.

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

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

1.2 getRadioTechSync —— 无线接入技术

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

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

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

privatetechLabel(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）。数值越大表示信号越好。

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

信号强度分级策略：

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

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

1.4 getNetworkState —— 网络注册状态

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

RegState 注册状态枚举：

NsaState 5G NSA 状态枚举：

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

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

2.1 getSimStateSync —— SIM 卡状态

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

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

2.2 getISOCountryCodeForSimSync —— 运营商国家代码

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

constcode=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 核心实现

数据模型：

@StateslotId:number=0;@StateradioTech:string='--';@StatepsRadioTech:string='--';@StatecsRadioTech:string='--';@StatenetworkType:string='--';@StateregState:string='--';@StatensaState:string='--';@StatesimState:string='--';@StateisoCode:string='--';@StatesignalLevel:string='--';@StatesignalLevelNum:number=0;@Stateloading:boolean=false;

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

信号格可视化：

privatesignalBarColor(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 时全部灰色。

状态枚举标签转换：

privatesimLabel(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'未知';}privateregLabel(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 弱网场景下的自适应策略

functiongetNetworkQuality():'excellent'|'good'|'poor'{constsignals=radio.getSignalInformationSync(0);if(signals.length===0)return'poor';constlevel=signals[0].signalLevel;if(level>=4)return'excellent';if(level>=2)return'good';return'poor';}// 根据网络质量调整视频清晰度constquality=getNetworkQuality();if(quality==='poor'){videoPlayer.setResolution('360p');}elseif(quality==='good'){videoPlayer.setResolution('720p');}else{videoPlayer.setResolution('1080p');}

4.2 5G 能力检测

functionsupports5G():boolean{constrt=radio.getRadioTechSync(0);returnrt.psRadioTech===radio.RadioTechnology.RADIO_TECHNOLOGY_NR;}asyncfunctionis5GConnected():Promise<boolean>{constns=awaitradio.getNetworkState(0);returnns.nsaState===radio.NsaState.NSA_STATE_DUAL_CONNECTED;}

4.3 SIM 卡异常检测

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

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

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

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

• 连接层判断：设备是否接入网络？（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 管理）配合，开发者可以构建完整的"连接 + 通道 + 信号"三层网络诊断工具，覆盖从网络可用性到信号质量的全部维度。