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

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

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/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。
