引言

移动应用的核心能力依赖网络通信，而蜂窝网络是移动设备最基础的联网方式。无论是即时通讯、视频播放还是在线支付，开发者都需要了解当前设备的无线接入技术（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 管理）配合，开发者可以构建完整的"连接 + 通道 + 信号"三层网络诊断工具，覆盖从网络可用性到信号质量的全部维度。

# harmonyos # 网络 # 华为 # .net # nginx
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

大模型与行业应用关键技术突破 | 国产算力平台赋能

avatar 人工智能6S服务平台
cover

京深联动打通AI硬件出海全链路！深圳模力营生态对接会・北京站成功举办

avatar 人工智能6S服务平台

HarmonyOS开发实战：小分享-TemplateDetailPage模板详情——预览信息标签

页面预览模板详情页预览信息标签图前言欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net模板详情页 展示模板的完整预览、使用量、标签和描述信息

avatar 人工智能6S服务平台