@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/17-wi-fi.md

@@ -0,0 +1,1028 @@
+# 豆包应用插件的端能力 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>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</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>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</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>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</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>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</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></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 完成初始化
+
+## 使用说明
+
+- 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></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
+    }
+  ]
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./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>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</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 信息