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, and this page is available as Markdown at /apps-plugin/docs/js-api/device/wifi/connectWifi.md.

connectWifi

连接指定 Wi-Fi。

扫码预览

扫码预览 connectWifi

使用限制

WARNING

iOS:豆包 iOS 的连接实现不接收 bssid,仅按 ssid 与密码连接;iOS 上传入 bssid 不会生效。

支持版本

前端库版本不低于 0.0.25。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

接入准备

前置条件

  • 需先调用 startWifi 完成初始化

使用说明

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

  • 连接过程由系统弹窗确认
  • iOS:传入的 bssid 会被忽略,仅按 ssid 与 password 连接

调用方式

异步 API

connectWifi(params: ConnectWifiParams): Promise<object>

入参

名称类型必填默认值约束说明
bssidstring否-仅 Android 使用,iOS 会忽略该字段Wi-Fi BSSID。iOS:豆包 iOS 的连接实现不接收 bssid,仅按 ssid 与密码连接。
manualboolean否false-是否跳转到系统设置页连接。
partialInfoboolean否false-是否仅返回部分 Wi-Fi 信息。
passwordstring是--Wi-Fi 密码。
ssidstring是--Wi-Fi SSID。

调用示例

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

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

成功返回

无返回字段。

返回示例

{}

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

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

错误码

errNoerrMsg平台触发条件处理建议
104invalid parameterAndroid、iOSssid 为空传入非空的 ssid 后重试
103feature not supportAndroid、iOS设备无可用的 Wi-Fi 能力,或 iOS 系统版本过低不支持连接检查设备与系统能力,不支持时不要调用
1401001wifi is not initializedAndroid、iOS调用前未先调用 startWifi 完成初始化先调用 startWifi 再连接 Wi-Fi
115operation timeoutAndroid连接 Wi-Fi 超时确认目标网络可用后提示用户重试
1401003connect wifi failedAndroid、iOS连接目标 Wi-Fi 失败(如密码错误、网络不可达、系统连接被拒)检查 ssid 与密码后提示用户重试

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS

平台差异

  • Android:连接超时返回 115;iOS 未细分超时,连接失败统一归为 1401003。