For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/device/wifi/getConnectedWifi.md.

getConnectedWifi

获取当前已连接 Wi-Fi 信息。

扫码预览

扫码预览 getConnectedWifi

使用限制

WARNING

Android、iOS:豆包 Android 返回 0 到 100 的信号等级,iOS 返回 0 到 1 的归一化值;跨端使用同一阈值判断信号强弱会出错。

支持版本

前端库版本不低于 0.0.25。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

接入准备

权限要求

类型标识是否必须平台说明
应用权限scope.userLocation按条件iOS豆包 iOS 读取 Wi-Fi 信息前需授权位置权限
系统权限位置权限按条件Android、iOS系统需开启定位并授予位置权限才能读取 Wi-Fi 信息

授权行为

  • iOS:首次读取 Wi-Fi 信息前会触发应用位置授权(scope.userLocation)与系统定位权限申请;用户拒绝后调用失败,需引导用户在系统设置及应用设置中开启位置权限
  • Android:读取 Wi-Fi 信息依赖已授予的系统定位权限;未授予或被撤销时调用失败,需引导用户在系统设置中开启定位权限

前置条件

  • 需先调用 startWifi 完成初始化

使用说明

  • signalStrength 量纲双端不一致,Android 为 0 到 100,iOS 为 0 到 1

调用方式

异步 API

getConnectedWifi(params?: GetConnectedWifiParams): Promise<GetConnectedWifiResult>

入参

名称类型必填默认值约束说明
partialInfoboolean否false-是否只返回部分 Wi-Fi 信息。

调用示例

import { getConnectedWifi } from '@doubao-dev/framework/api';

const { wifi } = await getConnectedWifi({ partialInfo: true });

console.log(wifi.ssid);

成功返回

名称类型必返说明
wifiWifiInfo是当前连接的 Wi-Fi 信息。
wifi.bssidstring否Wi-Fi BSSID。
wifi.frequencynumber否频段,单位 MHz。
wifi.secureboolean否Wi-Fi 是否安全。
wifi.signalStrengthnumber否信号强度。
wifi.ssidstring是Wi-Fi SSID。

返回示例

{
  "wifi": {
    "ssid": "Office-WiFi",
    "bssid": "a0:b1:c2:d3:e4:f5",
    "secure": true,
    "signalStrength": 80,
    "frequency": 5180
  }
}

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errNo": 1401002,
  "errMsg": "wifi is not connected"
}

错误码

errNoerrMsg平台触发条件处理建议
1401001wifi is not initializedAndroid、iOS调用前未先调用 startWifi 完成初始化先调用 startWifi 再获取已连接 Wi-Fi
1401002wifi is not connectedAndroid、iOS当前未连接 Wi-Fi 或无法读取已连接 Wi-Fi 信息确认设备已连接 Wi-Fi 后重试
106system permission deniediOS系统定位服务未开启,无法读取 Wi-Fi 信息引导用户在系统设置中开启定位服务
107user permission deniediOS用户未授予定位权限或未开启精确定位引导用户授予定位权限并开启精确定位
114operation cancellediOS用户取消了位置权限授权弹窗用户需要时可再次触发授权后重试
301network request cancellediOS位置授权过程中的网络请求被取消确认应用和网络状态后重试
302connection timed outiOS位置授权过程中的网络连接超时检查网络连接后重试
303no network connectioniOS当前无可用网络连接恢复网络连接后重试
305network failureiOS位置授权过程中发生其他网络错误检查网络连接,稍后重试
112invalid resultiOS位置授权服务返回的数据无法解析稍后重试;持续失败时反馈服务端响应异常

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS

平台差异

  • Android:未连接或因缺少定位权限无法读取时统一返回 1401002;未初始化返回 1401001。
  • iOS:读取前会发起位置权限授权,可返回 106/107 及授权网络类失败(301/302/303/305/112);读取阶段未连接返回 1401002。