# 豆包智能服务的端能力 API: Wi-Fi

Wi-Fi 模块能力；通常先 startWifi，再获取列表或连接。

[返回目录](./groups.md) | [返回速查](./quick-reference.md)

## 速查

| API | 说明 |
| --- | --- |
| [startWifi](#startwifi) | 初始化 Wi-Fi 模块。 |
| [stopWifi](#stopwifi) | 关闭 Wi-Fi 模块。 |
| [setWifiList](#setwifilist) | 设置 Wi-Fi 预设列表（iOS 特有）。 |
| [connectWifi](#connectwifi) | 连接指定 Wi-Fi。 |
| [getConnectedWifi](#getconnectedwifi) | 获取当前已连接 Wi-Fi 信息。 |
| [getWifiList](#getwifilist) | 获取 Wi-Fi 列表。 |
| [onWifiConnected](#onwificonnected) | 监听连接上 Wi-Fi 的事件。<br><br>返回取消监听函数。 |

## API 详情

<a id="startwifi"></a>
### startWifi()

# startWifi

初始化 Wi-Fi 模块。

## 扫码预览
![扫码预览 startWifi](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-lifecycle%252Findex)

## 支持版本

前端库版本不低于 `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>

## 使用说明

Wi-Fi 流程入口。调用其他 Wi-Fi 接口前需先调用本接口完成初始化。

## 调用方式

### 异步 API

```typescript
startWifi(params?: object): Promise<object>
```

## 入参

无。

## 调用示例

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

await startWifi();
```

## 成功返回

无返回字段。

### 返回示例

```json
{}
```

## 错误处理

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

### 失败示例

```json
{
  "errNo": 103,
  "errMsg": "feature not support"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android</td><td>设备无可用的 Wi-Fi 能力（缺少系统 Wi-Fi 服务）</td><td>检查设备是否支持 Wi-Fi，不支持时不要调用</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</td></tr>
</tbody>
</table>

## 平台差异

- **iOS**：初始化恒返回成功，不返回失败错误码。

<a id="stopwifi"></a>
### stopWifi()

# stopWifi

关闭 Wi-Fi 模块。

## 扫码预览
![扫码预览 stopWifi](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-lifecycle%252Findex)

## 支持版本

前端库版本不低于 `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>

## 调用方式

### 异步 API

```typescript
stopWifi(params?: object): Promise<object>
```

## 入参

无。

## 调用示例

```typescript
import { stopWifi } from '@doubao-dev/framework/api';

await stopWifi();
```

## 成功返回

无返回字段。

### 返回示例

```json
{}
```

<a id="setwifilist"></a>
### setWifiList()

# setWifiList

设置 Wi-Fi 预设列表（iOS 特有）。

## 扫码预览
![扫码预览 setWifiList](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]
> **Android**：豆包 Android 的 setWifiList 固定返回失败（setWifiList is iOS only）；Android 上调用无法设置预设列表。

## 支持版本

前端库版本不低于 `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>

## 接入准备

### 前置条件

- **iOS**：需先调用 startWifi 完成初始化

## 使用说明

该接口为 iOS 特有，用于预设 Wi-Fi 列表。Android 不支持该能力，调用会失败。

- **Android**：该 API 在 Android 上不可用，调用会返回失败

## 调用方式

### 异步 API

```typescript
setWifiList(params: SetWifiListParams): Promise<object>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>wifiList</code></td><td><code>WifiListItem[]</code></td><td>是</td><td>-</td><td>-</td><td>预设的 Wi-Fi 列表。</td></tr>
<tr><td><code>wifiList[].bssid</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>Wi-Fi BSSID。</td></tr>
<tr><td><code>wifiList[].password</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>Wi-Fi 密码。</td></tr>
<tr><td><code>wifiList[].ssid</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>Wi-Fi SSID。</td></tr>
</tbody>
</table>

## 调用示例

```typescript
import { setWifiList } from '@doubao-dev/framework/api';

await setWifiList({
  wifiList: [{ ssid: 'Office-WiFi', password: 'password' }]
});
```

## 成功返回

无返回字段。

### 返回示例

```json
{}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](./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>103</code></td><td><code>feature not support</code></td><td>Android</td><td>该 API 为 iOS 特有，Android 调用固定失败</td><td>不要在 Android 调用该 API</td></tr>
<tr><td><code>1401001</code></td><td><code>wifi is not initialized</code></td><td>iOS</td><td>调用前未先调用 startWifi 完成初始化</td><td>先调用 startWifi 再设置预设列表</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>iOS</td></tr>
</tbody>
</table>

## 平台差异

- **Android**：固定返回 103（该能力仅 iOS）；iOS 未初始化返回 1401001，其他失败统一返回 102。

<a id="connectwifi"></a>
### connectWifi()

# connectWifi

连接指定 Wi-Fi。

## 扫码预览
![扫码预览 connectWifi](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%252Fconnect-wifi%252Findex)

## 使用限制

> [!WARNING]
> **iOS**：豆包 iOS 的连接实现不接收 bssid，仅按 ssid 与密码连接；iOS 上传入 bssid 不会生效。

## 支持版本

前端库版本不低于 `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>

## 接入准备

### 前置条件

- 需先调用 startWifi 完成初始化

## 使用说明

通常先调用 startWifi。设置 manual 为 true 时会跳转到系统 Wi-Fi 设置页由用户手动连接。

- 连接过程由系统弹窗确认
- **iOS**：传入的 bssid 会被忽略，仅按 ssid 与 password 连接

## 调用方式

### 异步 API

```typescript
connectWifi(params: ConnectWifiParams): Promise<object>
```

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>bssid</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>仅 Android 使用，iOS 会忽略该字段</td><td>Wi-Fi BSSID。iOS：豆包 iOS 的连接实现不接收 bssid，仅按 ssid 与密码连接。</td></tr>
<tr><td><code>manual</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>-</td><td>是否跳转到系统设置页连接。</td></tr>
<tr><td><code>partialInfo</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>-</td><td>是否仅返回部分 Wi-Fi 信息。</td></tr>
<tr><td><code>password</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>Wi-Fi 密码。</td></tr>
<tr><td><code>ssid</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>Wi-Fi SSID。</td></tr>
</tbody>
</table>

## 调用示例

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

await startWifi();
await connectWifi({ ssid: 'Office-WiFi', password: 'password' });
```

## 成功返回

无返回字段。

### 返回示例

```json
{}
```

## 错误处理

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

### 失败示例

```json
{
  "errNo": 1401003,
  "errMsg": "connect wifi failed"
}
```

### 错误码

<table>
<thead>
<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>ssid 为空</td><td>传入非空的 ssid 后重试</td></tr>
<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>设备无可用的 Wi-Fi 能力，或 iOS 系统版本过低不支持连接</td><td>检查设备与系统能力，不支持时不要调用</td></tr>
<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>115</code></td><td><code>operation timeout</code></td><td>Android</td><td>连接 Wi-Fi 超时</td><td>确认目标网络可用后提示用户重试</td></tr>
<tr><td><code>1401003</code></td><td><code>connect wifi failed</code></td><td>Android、iOS</td><td>连接目标 Wi-Fi 失败（如密码错误、网络不可达、系统连接被拒）</td><td>检查 ssid 与密码后提示用户重试</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**：连接超时返回 115；iOS 未细分超时，连接失败统一归为 1401003。

<a id="getconnectedwifi"></a>
### getConnectedWifi()

# getConnectedWifi

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

## 扫码预览
![扫码预览 getConnectedWifi](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%252Fconnect-wifi%252Findex)

## 使用限制

> [!WARNING]
> **Android、iOS**：豆包 Android 返回 0 到 100 的信号等级，iOS 返回 0 到 1 的归一化值；跨端使用同一阈值判断信号强弱会出错。

## 支持版本

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

## 使用说明

- signalStrength 量纲双端不一致，Android 为 0 到 100，iOS 为 0 到 1

## 调用方式

### 异步 API

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

## 入参

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>partialInfo</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>-</td><td>是否只返回部分 Wi-Fi 信息。</td></tr>
</tbody>
</table>

## 调用示例

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

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

console.log(wifi.ssid);
```

## 成功返回

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

### 返回示例

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

## 错误处理

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

### 失败示例

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

### 错误码

<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>Android、iOS</td><td>当前未连接 Wi-Fi 或无法读取已连接 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**：未连接或因缺少定位权限无法读取时统一返回 1401002；未初始化返回 1401001。
- **iOS**：读取前会发起位置权限授权，可返回 106/107 及授权网络类失败（301/302/303/305/112）；读取阶段未连接返回 1401002。

<a id="getwifilist"></a>
### getWifiList()

# 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><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
    }
  ]
}
```

## 错误处理

错误对象和通用错误码见 [通用错误处理](./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）。

<a id="onwificonnected"></a>
### onWifiConnected()

# onWifiConnected

监听连接上 Wi-Fi 的事件。

## 扫码预览
![扫码预览 onWifiConnected](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-lifecycle%252Findex)

## 支持版本

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

## 支持平台

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

## 接入准备

### 前置条件

- 需先调用 startWifi 完成初始化

## 调用方式

### 事件监听 API

```typescript
onWifiConnected(callback: (event: WifiConnectedEvent) => void): () => void
```

## 入参

无。

## 调用示例

```ts
import { onWifiConnected } from '@doubao-dev/framework/api';

const off = onWifiConnected(({ wifi }) => {
  console.log(wifi.ssid);
});

off();
```

## 回调参数

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>event.wifi</code></td><td><code>WifiInfo</code></td><td>是</td><td>已连接的 Wi-Fi 信息。</td></tr>
<tr><td><code>event.wifi.bssid</code></td><td><code>string</code></td><td>否</td><td>Wi-Fi BSSID。</td></tr>
<tr><td><code>event.wifi.frequency</code></td><td><code>number</code></td><td>否</td><td>频段，单位 MHz。</td></tr>
<tr><td><code>event.wifi.secure</code></td><td><code>boolean</code></td><td>否</td><td>Wi-Fi 是否安全。</td></tr>
<tr><td><code>event.wifi.signalStrength</code></td><td><code>number</code></td><td>否</td><td>信号强度。</td></tr>
<tr><td><code>event.wifi.ssid</code></td><td><code>string</code></td><td>是</td><td>Wi-Fi SSID。</td></tr>
</tbody>
</table>

## 返回值

返回取消当前监听函数的函数。

### 回调示例

```json
{
  "wifi": {
    "ssid": "Office-WiFi",
    "bssid": "a0:b1:c2:d3:e4:f5",
    "secure": true
  }
}
```

## 相关类型

<a id="wifilistitem"></a>
### WifiListItem

预设 Wi-Fi 条目。

#### Properties

• **ssid?**: `string` - Wi-Fi SSID
• **bssid?**: `string` - Wi-Fi BSSID
• **password?**: `string` - Wi-Fi 密码

<a id="setwifilistparams"></a>
### SetWifiListParams

设置 Wi-Fi 预设列表的请求参数（iOS 特有）。

#### Properties

• **wifiList**: `WifiListItem[]` - 预设的 Wi-Fi 列表

<a id="connectwifiparams"></a>
### ConnectWifiParams

连接 Wi-Fi 的请求参数。

#### Properties

• **ssid**: `string` - Wi-Fi SSID
• **password**: `string` - Wi-Fi 密码
• **bssid?**: `string` - Wi-Fi BSSID
• **manual?**: `boolean` - 是否跳转到系统设置页连接
• **partialInfo?**: `boolean` - 是否仅返回部分 Wi-Fi 信息

<a id="wifiinfo"></a>
### WifiInfo

Wi-Fi 信息。

#### Properties

• **ssid**: `string` - Wi-Fi SSID
• **bssid?**: `string` - Wi-Fi BSSID
• **secure?**: `boolean` - Wi-Fi 是否安全
• **signalStrength?**: `number` - 信号强度
• **frequency?**: `number` - 频段，单位 MHz

<a id="getconnectedwifiparams"></a>
### GetConnectedWifiParams

获取当前已连接 Wi-Fi 的请求参数。

#### Properties

• **partialInfo?**: `boolean` - 是否只返回部分 Wi-Fi 信息

<a id="getconnectedwifiresult"></a>
### GetConnectedWifiResult

获取当前已连接 Wi-Fi 的返回结果。

#### Properties

• **wifi**: `WifiInfo` - 当前连接的 Wi-Fi 信息

<a id="getwifilistresult"></a>
### GetWifiListResult

获取 Wi-Fi 列表的返回结果。

#### Properties

• **wifiList**: `WifiInfo[]` - 当前获取到的 Wi-Fi 列表

<a id="wificonnectedevent"></a>
### WifiConnectedEvent

Wi-Fi 连接事件。

#### Properties

• **wifi**: `WifiInfo` - 已连接的 Wi-Fi 信息