> 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.

# getWifiList

获取 Wi-Fi 列表。

## 扫码预览

![扫码预览 getWifiList](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fdevice%252Fwifi-list%252Findex)

## 使用限制

> \[!WARNING]
> **iOS**：豆包 iOS 无系统扫描能力，仅返回当前已连接的一条 Wi-Fi；iOS 上无法列出周边 Wi-Fi，列表最多一条。

## 支持版本

前端库版本不低于 `0.0.25`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>不支持</td></tr>
</tbody>
</table>

## 接入准备

### 权限要求

<table>
<thead>
<tr><th>类型</th><th>标识</th><th>是否必须</th><th>平台</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td>应用权限</td><td><code>scope.userLocation</code></td><td>按条件</td><td>iOS</td><td>豆包 iOS 读取 Wi-Fi 信息前需授权位置权限</td></tr>
<tr><td>系统权限</td><td>位置权限</td><td>按条件</td><td>Android、iOS</td><td>系统需开启定位并授予位置权限才能获取 Wi-Fi 列表</td></tr>
</tbody>
</table>

### 授权行为

- **iOS**：首次获取 Wi-Fi 列表前会触发应用位置授权（scope.userLocation）与系统定位权限申请；用户拒绝后调用失败，需引导用户在系统设置及应用设置中开启位置权限
- **Android**：获取 Wi-Fi 列表依赖已授予的系统定位权限；未授予或被撤销时调用失败，需引导用户在系统设置中开启定位权限

### 前置条件

- 需先调用 startWifi 完成初始化

## 使用说明

通常先调用 startWifi。

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

## 调用方式

### 异步 API

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

## 入参

无。

## 调用示例

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

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

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

## 成功返回

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>wifiList</code></td><td><code>WifiInfo[]</code></td><td>是</td><td>当前获取到的 Wi-Fi 列表。</td></tr>
<tr><td><code>wifiList[].bssid</code></td><td><code>string</code></td><td>否</td><td>Wi-Fi BSSID。</td></tr>
<tr><td><code>wifiList[].frequency</code></td><td><code>number</code></td><td>否</td><td>频段，单位 MHz。</td></tr>
<tr><td><code>wifiList[].secure</code></td><td><code>boolean</code></td><td>否</td><td>Wi-Fi 是否安全。</td></tr>
<tr><td><code>wifiList[].signalStrength</code></td><td><code>number</code></td><td>否</td><td>信号强度。</td></tr>
<tr><td><code>wifiList[].ssid</code></td><td><code>string</code></td><td>是</td><td>Wi-Fi SSID。</td></tr>
</tbody>
</table>

### 返回示例

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

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

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

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>1401001</code></td><td><code>wifi is not initialized</code></td><td>Android、iOS</td><td>调用前未先调用 startWifi 完成初始化</td><td>先调用 startWifi 再获取 Wi-Fi 列表</td></tr>
<tr><td><code>1401002</code></td><td><code>wifi is not connected</code></td><td>iOS</td><td>iOS 仅返回当前已连接 Wi-Fi，当前未连接时读取失败</td><td>确认设备已连接 Wi-Fi 后重试</td></tr>
<tr><td><code>106</code></td><td><code>system permission denied</code></td><td>iOS</td><td>系统定位服务未开启，无法读取 Wi-Fi 信息</td><td>引导用户在系统设置中开启定位服务</td></tr>
<tr><td><code>107</code></td><td><code>user permission denied</code></td><td>iOS</td><td>用户未授予定位权限或未开启精确定位</td><td>引导用户授予定位权限并开启精确定位</td></tr>
<tr><td><code>114</code></td><td><code>operation cancelled</code></td><td>iOS</td><td>用户取消了位置权限授权弹窗</td><td>用户需要时可再次触发授权后重试</td></tr>
<tr><td><code>301</code></td><td><code>network request cancelled</code></td><td>iOS</td><td>位置授权过程中的网络请求被取消</td><td>确认应用和网络状态后重试</td></tr>
<tr><td><code>302</code></td><td><code>connection timed out</code></td><td>iOS</td><td>位置授权过程中的网络连接超时</td><td>检查网络连接后重试</td></tr>
<tr><td><code>303</code></td><td><code>no network connection</code></td><td>iOS</td><td>当前无可用网络连接</td><td>恢复网络连接后重试</td></tr>
<tr><td><code>305</code></td><td><code>network failure</code></td><td>iOS</td><td>位置授权过程中发生其他网络错误</td><td>检查网络连接，稍后重试</td></tr>
<tr><td><code>112</code></td><td><code>invalid result</code></td><td>iOS</td><td>位置授权服务返回的数据无法解析</td><td>稍后重试；持续失败时反馈服务端响应异常</td></tr>
</tbody>
</table>

#### 通用错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
</thead>
<tbody>
<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
</tbody>
</table>

## 平台差异

- **Android**：未初始化返回 1401001；扫描列表为空不视为失败；因定位权限不足导致读取失败时返回 102。
- **iOS**：仅返回当前已连接 Wi-Fi，未连接返回 1401002；读取前会发起位置权限授权，可返回 106/107 及授权网络类失败（301/302/303/305/112）。
