tencent cloud

腾讯云超级应用服务

Wi-Fi

下载
聚焦模式
字号
最后更新时间: 2026-03-20 17:56:26

onWifiConnected

该 API 使用方法为 wx.onWifiConnected(function listener)
说明:
支持度:
Android:支持。
iOS:支持。
功能说明:监听连接上 Wi-Fi 的事件。
参数及说明:function listener,连接上 Wi-Fi 的事件的监听函数,参数 Object res 如下:
属性
类型
说明
wifi
WifiInfo
Wi-Fi 信息

offWifiConnected

该 API 使用方法为 wx.offWifiConnected(function listener)
功能说明:移除连接上 Wi-Fi 的事件的监听函数。
参数及说明:function listener,onWifiConnected 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onWifiConnected(listener)
wx.offWifiConnected(listener) // 需传入与监听时同一个的函数对象

stopWifi

该 API 使用方法为 wx.stopWifi(Object object)
功能说明:关闭 Wi-Fi 模块。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
错误码
错误码
错误信息
说明
0
ok
正常
12000
not init
未先调用 startWifi 接口
12001
system not support
当前系统不支持相关能力
12002
password error Wi-Fi
密码错误
12003
connection timeout
连接超时, 仅 Android 支持
12004
duplicate request
重复连接 Wi-Fi
12005
wifi not turned on
Android 特有,未打开 Wi-Fi 开关
12006
gps not turned on
Android 特有,未打开 GPS 定位开关
12007
user denied
用户拒绝授权连接 Wi-Fi
12008
invalid SSID
无效 SSID
12009
system config err
系统运营商配置拒绝连接 Wi-Fi
12010
system internal error
系统其他错误,需要在 errmsg 打印具体的错误原因
12011
weapp in background
应用在后台无法配置 Wi-Fi
12013
wifi config may be expired
系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试,仅 Android 支持
12014
invalid WEP / WPA password
iOS 特有,无效的 WEP / WPA 密码
示例代码:
wx.stopWifi({
success (res) {
console.log(res.errMsg)
}
})

startWifi

该 API 使用方法为 wx.startWifi(Object object)
功能说明:初始化 Wi-Fi 模块。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
错误码
错误码
错误信息
说明
0
ok
正常
12000
not init
未先调用 startWifi 接口
12001
system not support
当前系统不支持相关能力
12002
password error Wi-Fi
密码错误
12003
connection timeout
连接超时, 仅 Android 支持
12004
duplicate request
重复连接 Wi-Fi
12005
wifi not turned on
Android 特有,未打开 Wi-Fi 开关
12006
gps not turned on
Android 特有,未打开 GPS 定位开关
12007
user denied
用户拒绝授权连接 Wi-Fi
12008
invalid SSID
无效 SSID
12009
system config err
系统运营商配置拒绝连接 Wi-Fi
12010
system internal error
系统其他错误,需要在 errmsg 打印具体的错误原因
12011
weapp in background
应用在后台无法配置 Wi-Fi
12013
wifi config may be expired
系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试,仅 Android 支持
12014
invalid WEP / WPA password
iOS 特有,无效的 WEP / WPA 密码
示例代码:
wx.startWifi({
success (res) {
console.log(res.errMsg)
}
})

getWifiList

该 API 使用方法为 wx.getWifiList(Object object)
功能说明:请求获取 Wi-Fi 列表。wifiList 数据会在 onGetWifiList 注册的回调中返回。 Android 调用前需要 用户授权 scope.userLocation
iOS 上需要用户手动进入「无线局域网」设置页,并在系统扫描到设备后,小程序才能收到 onGetWifiList 回调。

参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
错误码
错误码
错误信息
说明
0
ok
正常
12000
not init
未先调用 startWifi 接口
12001
system not support
当前系统不支持相关能力
12002
password error Wi-Fi
密码错误
12003
connection timeout
连接超时, 仅 Android 支持
12004
duplicate request
重复连接 Wi-Fi
12005
wifi not turned on
Android 特有,未打开 Wi-Fi 开关
12006
gps not turned on
Android 特有,未打开 GPS 定位开关
12007
user denied
用户拒绝授权连接 Wi-Fi
12008
invalid SSID
无效 SSID
12009
system config err
系统运营商配置拒绝连接 Wi-Fi
12010
system internal error
系统其他错误,需要在 errmsg 打印具体的错误原因
12011
weapp in background
应用在后台无法配置 Wi-Fi
12013
wifi config may be expired
系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试,仅 Android 支持
12014
invalid WEP / WPA password
iOS 特有,无效的 WEP / WPA 密码
示例代码:
wx.onGetWifiList(function(res) {
if (res.wifiList.length) {
wx.setWifiList({
wifiList: [{
SSID: res.wifiList[0].SSID,
BSSID: res.wifiList[0].BSSID,
password: '123456'
}]
})
} else {
wx.setWifiList({
wifiList: []
})
}
})
wx.getWifiList()

setWifiList

该 API 使用方法为 wx.setWifiList(Object object)
功能说明:设置 wifiList 中 AP 的相关信息。在 onGetWifiList 回调后调用,iOS特有接口
注意:
该接口只能在 onGetWifiList 回调之后才能调用。
此时客户端会挂起,等待小程序设置 Wi-Fi 信息,请务必尽快调用该接口,若无数据请传入一个空数组。
有可能随着周边 Wi-Fi 列表的刷新,单个流程内收到多次带有存在重复的 Wi-Fi 列表的回调。
参数及说明:Object object。
属性
类型
默认值
必填
说明
wifiList
Array.<Object>
-
提供预设的 Wi-Fi 信息列表
SSID(string): Wi-Fi 的 SSID
BSSID(string): Wi-Fi 的 BSSID
password(string): Wi-Fi 设备密码
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
错误码
错误码
错误信息
说明
0
ok
正常
12000
not init
未先调用 startWifi 接口
12001
system not support
当前系统不支持相关能力
12002
password error Wi-Fi
密码错误
12003
connection timeout
连接超时, 仅 Android 支持
12004
duplicate request
重复连接 Wi-Fi
12005
wifi not turned on
Android 特有,未打开 Wi-Fi 开关
12006
gps not turned on
Android 特有,未打开 GPS 定位开关
12007
user denied
用户拒绝授权连接 Wi-Fi
12008
invalid SSID
无效 SSID
12009
system config err
系统运营商配置拒绝连接 Wi-Fi
12010
system internal error
系统其他错误,需要在 errmsg 打印具体的错误原因
12011
weapp in background
应用在后台无法配置 Wi-Fi
12013
wifi config may be expired
系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试,仅 Android 支持
12014
invalid WEP / WPA password
iOS 特有,无效的 WEP / WPA 密码
示例代码:
wx.onGetWifiList(function(res) {
if (res.wifiList.length) {
wx.setWifiList({
wifiList: [{
SSID: res.wifiList[0].SSID,
BSSID: res.wifiList[0].BSSID,
password: '123456'
}]
})
} else {
wx.setWifiList({
wifiList: []
})
}
})
wx.getWifiList()

onGetWifiList

该 API 使用方法为 wx.onGetWifiList(function listener)
功能说明:监听获取到 Wi-Fi 列表数据事件。
参数及说明:function listener,获取到 Wi-Fi 列表数据事件的监听函数。参数 Object res 如下:
属性
类型
说明
wifiList
Array.<WifiInfo>
Wi-Fi 列表数据

offGetWifiList

该 API 使用方法为 wx.offGetWifiList(function listener)
功能说明:移除获取到 Wi-Fi 列表数据事件的监听函数。
参数及说明:function listener,onGetWifiList 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onGetWifiList(listener)
wx.offGetWifiList(listener) // 需传入与监听时同一个的函数对象

onWifiConnectedWithPartialInfo

该 API 使用方法为 wx.onWifiConnectedWithPartialInfo(function listener)
功能说明:监听连接上 Wi-Fi 的事件。
参数及说明:function listener,连接上 Wi-Fi 的事件的监听函数。参数 Object res 如下:
属性
类型
说明
wifi
WifiInfo
只包含 SSID 属性的 WifiInfo 对象

offWifiConnectedWithPartialInfo

该 API 使用方法为 wx.offWifiConnectedWithPartialInfo(function listener)
功能说明:移除连接上 Wi-Fi 的事件的监听函数。
参数及说明:function listener,onWifiConnectedWithPartialInfo 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onWifiConnectedWithPartialInfo(listener)
wx.offWifiConnectedWithPartialInfo(listener) // 需传入与监听时同一个的函数对象

connectWifi

该 API 使用方法为 wx.connectWifi(Object object)
功能说明:连接 Wi-Fi。若已知 Wi-Fi 信息,可以直接利用该接口连接。
注意:
iOS 系统底层没有给开发者提供因 wifi 密码错误而连接失败的事件,但用户可以收到密码错误的系统弹窗。建议开发者通过 onWifiConnected 事件来判断 wifi 是否连接成功;即设置定时器,若超时后仍没有 onWifiConnected 事件,则认定此次 wifi 连接无效。
Android / iOS 在系统已经连上目标 wifi 的情况下,小程序再次连接目标 wifi,此时无论输入的密码是否正确,系统都会默认此次连接成功,且没有 onWifiConnected 事件。
onWifiConnected 事件可能会返回空对象,此时代表 wifi 断开连接,开发者可忽略这种情况。
参数及说明:Object object。
属性
类型
默认值
必填
说明
SSID
string
-
Wi-Fi 设备 SSID,仅安卓生效
BSSID
string
-
Wi-Fi 设备 BSSID
password
string
-
Wi-Fi 设备密码
manual
boolean
false
跳转到系统设置页进行连接,仅安卓生效
partialInfo
boolean
false
是否需要返回部分 Wi-Fi 信息,仅安卓生效
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
错误码
错误码
错误信息
说明
0
ok
正常
12000
not init
未先调用 startWifi 接口
12001
system not support
当前系统不支持相关能力
12002
password error Wi-Fi
密码错误
12003
connection timeout
连接超时, 仅 Android 支持
12004
duplicate request
重复连接 Wi-Fi
12005
wifi not turned on
Android 特有,未打开 Wi-Fi 开关
12006
gps not turned on
Android 特有,未打开 GPS 定位开关
12007
user denied
用户拒绝授权连接 Wi-Fi
12008
invalid SSID
无效 SSID
12009
system config err
系统运营商配置拒绝连接 Wi-Fi
12010
system internal error
系统其他错误,需要在 errmsg 打印具体的错误原因
12011
weapp in background
应用在后台无法配置 Wi-Fi
12013
wifi config may be expired
系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试,仅 Android 支持
12014
invalid WEP / WPA password
iOS 特有,无效的 WEP / WPA 密码
示例代码:
wx.connectWifi({
SSID: '',
password: '',
success (res) {
console.log(res.errMsg)
}
})


getConnectedWifi

该 API 使用方法为 wx.getConnectedWifi(Object object)
功能说明:获取已连接中的 Wi-Fi 信息。
参数及说明:Object object
属性
类型
默认值
必填
说明
partialInfo
boolean
false
是否需要返回部分 Wi-Fi 信息
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
object.success 回调函数参数:Object res
属性
类型
说明
wifi
WifiInfo
Wi-Fi 信息
错误码
错误码
错误信息
说明
0
ok
正常
12000
not init
未先调用 startWifi 接口
12001
system not support
当前系统不支持相关能力
12002
password error Wi-Fi
密码错误
12003
connection timeout
连接超时, 仅 Android 支持
12004
duplicate request
重复连接 Wi-Fi
12005
wifi not turned on
Android 特有,未打开 Wi-Fi 开关
12006
gps not turned on
Android 特有,未打开 GPS 定位开关
12007
user denied
用户拒绝授权连接 Wi-Fi
12008
invalid SSID
无效 SSID
12009
system config err
系统运营商配置拒绝连接 Wi-Fi
12010
system internal error
系统其他错误,需要在 errmsg 打印具体的错误原因
12011
weapp in background
应用在后台无法配置 Wi-Fi
12013
wifi config may be expired
系统保存的 Wi-Fi 配置过期,建议忘记 Wi-Fi 后重试,仅 Android 支持
12014
invalid WEP / WPA password
iOS 特有,无效的 WEP / WPA 密码

WifiInfo

功能说明:Wifi 信息。
注意:
Android wx.connectWifi / wx.getConnectedWifi 若设置了 partialInfo:true,或者调用了 wx.onWifiConnectedWithPartialInfo 事件。将会返回只包含 SSID 属性的 WifiInfo 对象。
iOS wx.getConnectedWifi 若设置了 partialInfo:true,将会返回只包含 SSID、BSSID 属性的 WifiInfo 对象,且需要用户开启superapp定位权限才能正确返回结果。
在某些情况下,可能 Wi-Fi 已经连接成功,但会因为获取不到完整的 WifiInfo 对象报错。具体错误信息为 errCode:12010, errMsg: can't gain current wifino wifi is connected。如果开发者不需要完整的 WifiInfo 对象,则可以通过采取上述策略解决报错问题。

属性

string SSID:Wi-Fi 的 SSID。
string BSSID:Wi-Fi 的 BSSID。
boolean secure:Wi-Fi 是否安全。
number signalStrength:Wi-Fi 信号强度,Android 取值 0 ~ 100 ,iOS 取值 0 ~ 1,值越大强度越大。
number frequency:Wi-Fi 频段单位 MHz。


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈