# 豆包智能服务端能力 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 的事件。 |

## API 详情

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

初始化 Wi-Fi 模块。

## 代码示例

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

await startWifi();
```

## 注意事项

Wi-Fi 流程入口。

## 入参

无入参。

## 返回值

返回 `Promise<object>`。

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

关闭 Wi-Fi 模块。

## 代码示例

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

await stopWifi();
```

## 入参

无入参。

## 返回值

返回 `Promise<object>`。

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

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

## 代码示例

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

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

## 注意事项

该接口为 iOS 特有，用于预设 Wi-Fi 列表。

## 入参

<table>
<thead><td width="160">参数名</td><td width="260">类型</td><td width="80">必填</td><td width="360">说明</td></thead>
<tr><td>wifiList</td><td><code>WifiListItem[]</code></td><td>是</td><td>预设的 Wi-Fi 列表。</td></tr>
<tr><td>wifiList[].bssid</td><td><code>string</code></td><td>否</td><td>Wi-Fi BSSID。</td></tr>
<tr><td>wifiList[].password</td><td><code>string</code></td><td>否</td><td>Wi-Fi 密码。</td></tr>
<tr><td>wifiList[].ssid</td><td><code>string</code></td><td>否</td><td>Wi-Fi SSID。</td></tr>
</table>

## 返回值

返回 `Promise<object>`。

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

连接指定 Wi-Fi。

## 代码示例

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

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

## 注意事项

通常先调用 startWifi。

## 入参

<table>
<thead><td width="160">参数名</td><td width="260">类型</td><td width="80">必填</td><td width="360">说明</td></thead>
<tr><td>bssid</td><td><code>string</code></td><td>否</td><td>Wi-Fi BSSID。</td></tr>
<tr><td>manual</td><td><code>boolean</code></td><td>否</td><td>是否跳转到系统设置页连接。</td></tr>
<tr><td>partialInfo</td><td><code>boolean</code></td><td>否</td><td>是否仅返回部分 Wi-Fi 信息。</td></tr>
<tr><td>password</td><td><code>string</code></td><td>是</td><td>Wi-Fi 密码。</td></tr>
<tr><td>ssid</td><td><code>string</code></td><td>是</td><td>Wi-Fi SSID。</td></tr>
</table>

## 返回值

返回 `Promise<object>`。

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

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

## 代码示例

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

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

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

## 入参

<table>
<thead><td width="160">参数名</td><td width="260">类型</td><td width="80">必填</td><td width="360">说明</td></thead>
<tr><td>partialInfo</td><td><code>boolean</code></td><td>否</td><td>是否只返回部分 Wi-Fi 信息。</td></tr>
</table>

## 返回值

返回 `Promise<GetConnectedWifiResult>`。

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

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

获取 Wi-Fi 列表。

## 代码示例

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

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

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

## 注意事项

通常先调用 startWifi。

## 入参

无入参。

## 返回值

返回 `Promise<GetWifiListResult>`。

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

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

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

## 代码示例

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

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

off();
```

## 入参

<table>
<thead><td width="160">参数名</td><td width="260">类型</td><td width="80">必填</td><td width="360">说明</td></thead>
<tr><td>handler</td><td><code>Function</code></td><td>是</td><td>-</td></tr>
<tr><td>handler.event</td><td><code>WifiConnectedEvent</code></td><td>是</td><td>-</td></tr>
<tr><td>handler.event.wifi</td><td><code>WifiInfo</code></td><td>是</td><td>已连接的 Wi-Fi 信息。</td></tr>
<tr><td>handler.event.wifi.bssid</td><td><code>string</code></td><td>否</td><td>Wi-Fi BSSID。</td></tr>
<tr><td>handler.event.wifi.frequency</td><td><code>number</code></td><td>否</td><td>频段，单位 MHz。</td></tr>
<tr><td>handler.event.wifi.secure</td><td><code>boolean</code></td><td>否</td><td>Wi-Fi 是否安全。</td></tr>
<tr><td>handler.event.wifi.signalStrength</td><td><code>number</code></td><td>否</td><td>信号强度。</td></tr>
<tr><td>handler.event.wifi.ssid</td><td><code>string</code></td><td>是</td><td>Wi-Fi SSID。</td></tr>
</table>

## 返回值

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

## 相关类型

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

预设 Wi-Fi 条目。

#### Properties

• **ssid?**: `string` - Wi-Fi SSID
• **bssid?**: `string` - Wi-Fi BSSID
• **password?**: `string` - 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="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 信息