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/getWifiList.md.

getWifiList

获取 Wi-Fi 列表。

扫码预览

扫码预览 getWifiList

使用限制

WARNING

iOS:豆包 iOS 无系统扫描能力,仅返回当前已连接的一条 Wi-Fi;iOS 上无法列出周边 Wi-Fi,列表最多一条。

支持版本

前端库版本不低于 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 完成初始化

使用说明

通常先调用 startWifi。

  • iOS:列表最多返回一条当前已连接的 Wi-Fi,不代表周边可用网络

调用方式

异步 API

getWifiList(params?: object): Promise<GetWifiListResult>

入参

无。

调用示例

import { getWifiList, startWifi } from '@doubao-dev/framework/api';

await startWifi();
const { wifiList } = await getWifiList();

console.log(wifiList.map((wifi) => wifi.ssid));

成功返回

名称类型必返说明
wifiListWifiInfo[]是当前获取到的 Wi-Fi 列表。
wifiList[].bssidstring否Wi-Fi BSSID。
wifiList[].frequencynumber否频段,单位 MHz。
wifiList[].secureboolean否Wi-Fi 是否安全。
wifiList[].signalStrengthnumber否信号强度。
wifiList[].ssidstring是Wi-Fi SSID。

返回示例

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

错误处理

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

失败示例

{
  "errNo": 1401001,
  "errMsg": "wifi is not initialized"
}

错误码

errNoerrMsg平台触发条件处理建议
1401001wifi is not initializedAndroid、iOS调用前未先调用 startWifi 完成初始化先调用 startWifi 再获取 Wi-Fi 列表
1401002wifi is not connectediOSiOS 仅返回当前已连接 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:未初始化返回 1401001;扫描列表为空不视为失败;因定位权限不足导致读取失败时返回 102。
  • iOS:仅返回当前已连接 Wi-Fi,未连接返回 1401002;读取前会发起位置权限授权,可返回 106/107 及授权网络类失败(301/302/303/305/112)。