发起请求
uni.request(OBJECT)
发起网络请求。
在各个小程序平台运行时,网络相关的 API 在使用前需要配置域名白名单。
OBJECT 参数说明
参数名 | 类型 | 必填 | 默认值 | 说明 | 平台差异说明 |
---|---|---|---|---|---|
url | String | 是 | 开发者服务器接口地址 | ||
data | Object/String/ArrayBuffer | 否 | 请求的参数 | App不支持ArrayBuffer类型 | |
header | Object | 否 | 设置请求的 header,header 中不能设置 Referer。 | App、H5端会自动带上cookie,且H5端不可手动修改 | |
method | String | 否 | GET | 有效值详见下方说明 | |
timeout | Number | 否 | 60000 | 超时时间,单位 ms | H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序(2.10.0)、支付宝小程序 |
dataType | String | 否 | json | 如果设为 json,会尝试对返回的数据做一次 JSON.parse | |
responseType | String | 否 | text | 设置响应的数据类型。合法值:text、arraybuffer | 支付宝小程序不支持 |
sslVerify | Boolean | 否 | true | 验证 ssl 证书 | 仅App安卓端支持(HBuilderX 2.3.3+) |
withCredentials | Boolean | 否 | false | 跨域请求时是否携带凭证(cookies) | 仅H5支持(HBuilderX 2.6.15+) |
firstIpv4 | Boolean | 否 | false | DNS解析时优先使用ipv4 | 仅 App-Android 支持 (HBuilderX 2.8.0+) |
success | Function | 否 | 收到开发者服务器成功返回的回调函数 | ||
fail | Function | 否 | 接口调用失败的回调函数 | ||
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
method 有效值
注意:method有效值必须大写,每个平台支持的method有效值不同,详细见下表。
method | App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 |
---|---|---|---|---|---|---|
GET | √ | √ | √ | √ | √ | √ |
POST | √ | √ | √ | √ | √ | √ |
PUT | √ | √ | √ | x | √ | √ |
DELETE | √ | √ | √ | x | √ | x |
CONNECT | x | √ | √ | x | x | x |
HEAD | x | √ | √ | x | √ | x |
OPTIONS | √ | √ | √ | x | √ | x |
TRACE | x | √ | √ | x | x | x |
success 返回参数说明
参数 | 类型 | 说明 |
---|---|---|
data | Object/String/ArrayBuffer | 开发者服务器返回的数据 |
statusCode | Number | 开发者服务器返回的 HTTP 状态码 |
header | Object | 开发者服务器返回的 HTTP Response Header |
cookies | Array.<string> | 开发者服务器返回的 cookies,格式为字符串数组 |
data 数据说明
最终发送给服务器的数据是 String 类型,如果传入的 data 不是 String 类型,会被转换成 String。转换规则如下:
- 对于
GET
方法,会将数据转换为 query string。例如{ name: 'name', age: 18 }
转换后的结果是name=name&age=18
。 - 对于
POST
方法且header['content-type']
为application/json
的数据,会进行 JSON 序列化。 - 对于
POST
方法且header['content-type']
为application/x-www-form-urlencoded
的数据,会将数据转换为 query string。
示例
uni.request({
url: 'https://www.example.com/request', //仅为示例,并非真实接口地址。
data: {
text: 'uni.request'
},
header: {
'custom-header': 'hello' //自定义请求头信息
},
success: (res) => {
console.log(res.data);
this.text = 'request success';
}
});
返回值
如果希望返回一个 requestTask
对象,需要至少传入 success / fail / complete 参数中的一个。例如:
var requestTask = uni.request({
url: 'https://www.example.com/request', //仅为示例,并非真实接口地址。
complete: ()=> {}
});
requestTask.abort();
如果没有传入 success / fail / complete 参数,则会返回封装后的 Promise 对象:Promise 封装
通过 requestTask
,可中断请求任务。
requestTask 对象的方法列表
方法 | 参数 | 说明 |
---|---|---|
abort | 中断请求任务 | |
offHeadersReceived | 取消监听 HTTP Response Header 事件,仅微信小程序平台 支持,文档详情 | |
onHeadersReceived | 监听 HTTP Response Header 事件。会比请求完成事件更早,仅微信小程序平台 支持,文档详情 |
示例
const requestTask = uni.request({
url: 'https://www.example.com/request', //仅为示例,并非真实接口地址。
data: {
name: 'name',
age: 18
},
success: function(res) {
console.log(res.data);
}
});
// 中断请求任务
requestTask.abort();
Tips
- 请求的
header
中content-type
默认为application/json
。 - 避免在
header
中使用中文,或者使用 encodeURIComponent 进行编码,否则在百度小程序报错。(来自:快狗打车前端团队) - 网络请求的
超时时间
可以统一在manifest.json
中配置 networkTimeout。 - H5 端本地调试需注意跨域问题,参考:调试跨域问题解决方案
- 注意由于百度小程序iOS客户端,请求失败时会进入fail回调,需要针对百度增加相应的处理以解决该问题。
- 注意小程序端不支持自动保持 cookie,服务器应避免验证 cookie。如果服务器无法修改,也可以使用一些模拟手段,比如这样的工具https://github.com/charleslo1/weapp-cookie 可以请求时带上 cookie 并将响应的 cookie 保存在本地。
- H5端 cookie 受跨域限制(和平时开发网站时一样),旧版的 uni.request 未支持 withCredentials 配置,可以直接使用 xhr 对象或者其他类库。
- 根据 W3C 规范,H5 端无法获取 response header 中 Set-Cookie、Set-Cookie2 这2个字段,对于跨域请求,允许获取的 response header 字段只限于“simple response header”和“Access-Control-Expose-Headers”(详情)
- uni-app 插件市场有flyio、axios等三方封装的拦截器可用
- 低版本手机自身不支持 ipv6,如果服务器仅允许 ipv6,会导致老手机无法正常运行或访问速度非常慢
- localhost、127.0.0.1等服务器地址,只能在电脑端运行,手机端连接时不能访问。请使用标准IP并保证手机能连接电脑网络
- debug 模式,安卓端暂时无法获取响应头,url中含有非法字符(如未编码为%20的空格)时会请求失败
- iOS App第一次安装启动后,会弹出是否允许联网的询问框,在用户点击同意前,调用联网API会失败。请注意判断这种情况。比如官方提供的新闻模板示例(HBuilderX新建项目可选择),会判断如果无法联网,则提供一个错误页,提示用户设置网络及下拉刷新重试。
- 良好体验的App,还会判断当前是否处于飞行模式(参考)、是wifi还是3G(参考)
- 部分安卓设备,真机运行或debug模式下的网速,低于release模式很多。
- 使用一些比较小众的证书机构(如:CFCA OV OCA)签发的 ssl 证书在安卓设备请求会失败,因为这些机构的根证书不在系统内置根证书库,可以更换其他常见机构签发的证书(如:Let’s Encrypt),或者配置 sslVerify 为 false 关闭 ssl 证书验证(不推荐)。
- 单次网络请求数据量建议控制在50K以下(仅指json数据,不含图片),过多数据应分页获取,以提升应用体验。
uni.configMTLS(OBJECT)
https 请求配置自签名证书
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 |
---|---|---|---|---|---|---|---|
√(3.2.7+) | x | x | x | x | x | x | x |
OBJECT 参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
certificates | Array<certificate > | 是 | certificates 为数组,支持为多个域名配置自签名证书 |
success | Function(callbackObject ) | 否 | 接口调用成功的回调函数 |
fail | Function(callbackObject ) | 否 | 接口调用失败的回调函数 |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
certificate 参数说明
证书配置项
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
host | String | 是 | 对应请求的域名(注意:不要协议部分) |
client | String | 否 | 客户端证书(服务器端需要验证客户端证书时需要配置此项,格式要求请参考下面的证书格式说明,注意 iOS 平台客户端证书只支持 .p12 类型的证书) |
clientPassword | String | 否 | 客户端证书对应的密码(客户端证书存在时必须配置此项) |
server | Array<String> | 否 | 服务器端证书(客户端需要对服务器端证书做校验时需要配置此项,格式要求请参考下面的证书格式说明,注意 iOS 平台服务器端证书只支持 .cer 类型的证书) |
证书格式说明
- 文件路径形式:可将证书文件放到工程的 ‘static’ 目录中,然后填写文件路径,示例:
'/static/client.p12'
Base64String
:将证书文件的二进制转换为Base64String
字符串,然后在字符串前面添加'data:cert/pem;base64,'
前缀,示例:'data:cert/pem;base64,xxx'
xxx 代表真实的证书 base64String
callbackObject 参数说明
属性 | 类型 | 说明 |
---|---|---|
code | Number | 成功返回 0,失败返回相应 code 码 |
示例
uni.configMTLS({
certificates: [{
'host': 'www.test.com',
'client': '/static/client.p12',
'clientPassword': '123456789',
'server': ['/static/server.cer'],
}],
success ({code}) {}
});
上传、下载
uni.uploadFile(OBJECT)
将本地资源上传到开发者服务器,客户端发起一个 POST
请求,其中 content-type
为 multipart/form-data
。
如页面通过 uni.chooseImage 等接口获取到一个本地资源的临时文件路径后,可通过此接口将本地资源上传到指定服务器。另外选择和上传非图像、视频文件参考:https://ask.dcloud.net.cn/article/35547。
在各个小程序平台运行时,网络相关的 API 在使用前需要配置域名白名单。
推荐开发者上传到uniCloud,uniCloud提供了免费CDN和更好的易用性,包括安全的cdn直传。
- uniCloud的上传API:https://uniapp.dcloud.io/uniCloud/storage?id=uploadfile
- 封装的更完善的uni-file-picker组件,文件选择、上传到uniCloud,一站式集成。
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
url | String | 是 | 开发者服务器 url | |
files | Array | 是(files和filePath选其一) | 需要上传的文件列表。使用 files 时,filePath 和 name 不生效。 | App、H5( 2.6.15+) |
fileType | String | 见平台差异说明 | 文件类型,image/video/audio | 仅支付宝小程序,且必填。 |
file | File | 否 | 要上传的文件对象。 | 仅H5(2.6.15+)支持 |
filePath | String | 是(files和filePath选其一) | 要上传文件资源的路径。 | |
name | String | 是 | 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容 | |
header | Object | 否 | HTTP 请求 Header, header 中不能设置 Referer。 | |
timeout | Number | 否 | 超时时间,单位 ms | H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+) |
formData | Object | 否 | HTTP 请求中其他额外的 form data | |
success | Function | 否 | 接口调用成功的回调函数 | |
fail | Function | 否 | 接口调用失败的回调函数 | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
注意:
- App支持多文件上传,微信小程序只支持单文件上传,传多个文件需要反复调用本API。所以跨端的写法就是循环调用本API。
- hello uni-app中的客服反馈,支持多图上传。uni-app插件市场中也有多个封装的组件。
- App平台选择和上传非图像、视频文件,参考https://ask.dcloud.net.cn/article/35547
- 网络请求的
超时时间
可以统一在manifest.json
中配置 networkTimeout。 - 支付宝小程序开发工具上传文件返回的http状态码为字符串形式,支付宝小程序真机返回的状态码为数字形式
files参数说明
files 参数是一个 file 对象的数组,file 对象的结构如下:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
name | String | 否 | multipart 提交时,表单的项目名,默认为 file |
file | File | 否 | 要上传的文件对象,仅H5(2.6.15+)支持 |
uri | String | 是 | 文件的本地地址 |
Tip:
- 如果
name
不填或填的值相同,可能导致服务端读取文件时只能读取到一个文件。
success 返回参数说明
参数 | 类型 | 说明 |
---|---|---|
data | String | 开发者服务器返回的数据 |
statusCode | Number | 开发者服务器返回的 HTTP 状态码 |
示例
uni.chooseImage({
success: (chooseImageRes) => {
const tempFilePaths = chooseImageRes.tempFilePaths;
uni.uploadFile({
url: 'https://www.example.com/upload', //仅为示例,非真实的接口地址
filePath: tempFilePaths[0],
name: 'file',
formData: {
'user': 'test'
},
success: (uploadFileRes) => {
console.log(uploadFileRes.data);
}
});
}
});
返回值
如果希望返回一个 uploadTask
对象,需要至少传入 success / fail / complete 参数中的一个。例如:
var uploadTask = uni.uploadFile({
url: 'https://www.example.com/upload', //仅为示例,并非真实接口地址。
complete: ()=> {}
});
uploadTask.abort();
如果没有传入 success / fail / complete 参数,则会返回封装后的 Promise 对象:Promise 封装
通过 uploadTask
,可监听上传进度变化事件,以及取消上传任务。
uploadTask 对象的方法列表
方法 | 参数 | 说明 |
---|---|---|
abort | 中断上传任务 | |
onProgressUpdate | callback | 监听上传进度变化 |
onHeadersReceived | callback | 监听 HTTP Response Header 事件。会比请求完成事件更早,仅微信小程序平台 支持,规范详情 |
offProgressUpdate | callback | 取消监听上传进度变化事件,仅微信小程序平台 支持,规范详情 |
offHeadersReceived | callback | 取消监听 HTTP Response Header 事件,仅微信小程序平台 支持,规范详情 |
onProgressUpdate 返回参数说明
参数 | 类型 | 说明 |
---|---|---|
progress | Number | 上传进度百分比 |
totalBytesSent | Number | 已经上传的数据长度,单位 Bytes |
totalBytesExpectedToSend | Number | 预期需要上传的数据总长度,单位 Bytes |
示例
uni.chooseImage({
success: (chooseImageRes) => {
const tempFilePaths = chooseImageRes.tempFilePaths;
const uploadTask = uni.uploadFile({
url: 'https://www.example.com/upload', //仅为示例,非真实的接口地址
filePath: tempFilePaths[0],
name: 'file',
formData: {
'user': 'test'
},
success: (uploadFileRes) => {
console.log(uploadFileRes.data);
}
});
uploadTask.onProgressUpdate((res) => {
console.log('上传进度' + res.progress);
console.log('已经上传的数据长度' + res.totalBytesSent);
console.log('预期需要上传的数据总长度' + res.totalBytesExpectedToSend);
// 测试条件,取消上传任务。
if (res.progress > 50) {
uploadTask.abort();
}
});
}
});
uni.downloadFile(OBJECT)
下载文件资源到本地,客户端直接发起一个 HTTP GET 请求,返回文件的本地临时路径。
在各个小程序平台运行时,网络相关的 API 在使用前需要配置域名白名单。在h5上是跨域的,用户需要处理好跨域问题。
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
url | String | 是 | 下载资源的 url | |
header | Object | 否 | HTTP 请求 Header, header 中不能设置 Referer。 | |
timeout | Number | 否 | 超时时间,单位 ms | H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+) |
success | Function | 否 | 下载成功后以 tempFilePath 的形式传给页面,res = {tempFilePath: ‘文件的临时路径’} | |
fail | Function | 否 | 接口调用失败的回调函数 | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) | |
filePath | string | 否 | 指定文件下载后存储的路径 (本地路径) | 微信小程序(IOS小程序保存到相册需要添加此字段才可以正常保存) |
注:文件的临时路径,在应用本次启动期间可以正常使用,如需持久保存,需在主动调用 uni.saveFile,才能在应用下次启动时访问得到。
success 返回参数说明
参数 | 类型 | 说明 |
---|---|---|
tempFilePath | String | 临时文件路径,下载后的文件会存储到一个临时文件 |
statusCode | Number | 开发者服务器返回的 HTTP 状态码 |
注意
- 网络请求的
超时时间
可以统一在manifest.json
中配置 networkTimeout。
示例
uni.downloadFile({
url: 'https://www.example.com/file/test', //仅为示例,并非真实的资源
success: (res) => {
if (res.statusCode === 200) {
console.log('下载成功');
}
}
});
返回值
如果希望返回一个 downloadTask
对象,需要至少传入 success / fail / complete 参数中的一个。例如:
var downloadTask = uni.downloadFile({
url: 'https://www.example.com/file/test', //仅为示例,并非真实接口地址。
complete: ()=> {}
});
downloadTask.abort();
如果没有传入 success / fail / complete 参数,则会返回封装后的 Promise 对象:Promise 封装
通过 downloadTask
,可监听下载进度变化事件,以及取消下载任务。
downloadTask 对象的方法列表
方法 | 参数 | 说明 | 最低版本 |
---|---|---|---|
abort | 中断下载任务 | * | |
onProgressUpdate | callback | 监听下载进度变化 | * |
onHeadersReceived | callback | 监听 HTTP Response Header 事件,会比请求完成事件更早,仅微信小程序平台 支持,规范详情 | |
offProgressUpdate | callback | 取消监听下载进度变化事件,仅微信小程序平台 支持,规范详情 | |
offHeadersReceived | callback | 取消监听 HTTP Response Header 事件,仅微信小程序平台 支持,规范详情 |
onProgressUpdate 返回参数说明
参数 | 类型 | 说明 |
---|---|---|
progress | Number | 下载进度百分比 |
totalBytesWritten | Number | 已经下载的数据长度,单位 Bytes |
totalBytesExpectedToWrite | Number | 预期需要下载的数据总长度,单位 Bytes |
示例
const downloadTask = uni.downloadFile({
url: 'http://www.example.com/file/test', //仅为示例,并非真实的资源
success: (res) => {
if (res.statusCode === 200) {
console.log('下载成功');
}
}
});
downloadTask.onProgressUpdate((res) => {
console.log('下载进度' + res.progress);
console.log('已经下载的数据长度' + res.totalBytesWritten);
console.log('预期需要下载的数据总长度' + res.totalBytesExpectedToWrite);
// 满足测试条件,取消下载任务。
if (res.progress > 50) {
downloadTask.abort();
}
});
WebSocket
uni.connectSocket(OBJECT)
创建一个 WebSocket 连接。
在各个小程序平台运行时,网络相关的 API 在使用前需要配置域名白名单。
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
url | String | 是 | 服务器接口地址 | 小程序中必须是 wss:// 协议 |
header | Object | 否 | HTTP Header , header 中不能设置 Referer | 小程序、App 2.9.6+ |
method | String | 否 | 默认是GET,有效值:OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT | 仅微信小程序支持 |
protocols | Array<String> | 否 | 子协议数组 | App、H5、微信小程序、百度小程序、字节跳动小程序、飞书小程序 |
success | Function | 否 | 接口调用成功的回调函数 | |
fail | Function | 否 | 接口调用失败的回调函数 | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例代码
uni.connectSocket({
url: 'wss://www.example.com/socket',
data() {
return {
x: '',
y: ''
};
},
header: {
'content-type': 'application/json'
},
protocols: ['protocol1'],
method: 'GET'
});
返回值
如果希望返回一个 socketTask 对象,需要至少传入 success / fail / complete 参数中的一个。例如:
var socketTask = uni.connectSocket({
url: 'wss://www.example.com/socket', //仅为示例,并非真实接口地址。
complete: ()=> {}
});
如果没有传入 success / fail / complete 参数,则会返回封装后的 Promise 对象:Promise 封装
注意事项
- 网络请求的
超时时间
可以统一在manifest.json
中配置 networkTimeout。 - App平台,2.2.6以下的版本,不支持
ArrayBuffer
类型的数据收发。老版本不愿升级也可以使用 plus-websocket插件 插件替代。 - App平台2.2.6以下的版本以及支付宝小程序下,所有
vue
页面只能使用一个websocket
连接。App下可以使用 plus-websocket 插件替代实现多链接。。 - 微信小程序平台1.7.0 及以上版本,最多可以同时存在5个WebSocket 连接。老版本只支持一个socket连接
- 百度小程序平台自基础库版本 1.9.4 及以后支持多个socket连接。老版本只支持一个socket连接
- QQ小程序平台最多支持同时存在5个socket链接
uni.onSocketOpen(CALLBACK)
监听WebSocket连接打开事件。
平台兼容性
字节小程序不支持
CALLBACK 返回参数
属性 | 类型 | 说明 |
---|---|---|
header | Object | 连接成功的 HTTP 响应 Header |
示例代码:
uni.connectSocket({
url: 'wss://www.example.com/socket'
});
uni.onSocketOpen(function (res) {
console.log('WebSocket连接已打开!');
});
uni.onSocketError(CALLBACK)
监听WebSocket错误。
平台兼容性
字节小程序不支持
示例代码
uni.connectSocket({
url: 'wss://www.example.com/socket'
});
uni.onSocketOpen(function (res) {
console.log('WebSocket连接已打开!');
});
uni.onSocketError(function (res) {
console.log('WebSocket连接打开失败,请检查!');
});
uni.sendSocketMessage(OBJECT)
通过 WebSocket 连接发送数据,需要先 uni.connectSocket,并在 uni.onSocketOpen 回调之后才能发送。
平台兼容性
字节小程序不支持
OBJECT 参数说明:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
data | String/ArrayBuffer | 是 | 需要发送的内容 |
success | Function | 否 | 接口调用成功的回调函数 |
fail | Function | 否 | 接口调用失败的回调函数 |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例代码
var socketOpen = false;
var socketMsgQueue = [];
uni.connectSocket({
url: 'wss://www.example.com/socket'
});
uni.onSocketOpen(function (res) {
socketOpen = true;
for (var i = 0; i < socketMsgQueue.length; i++) {
sendSocketMessage(socketMsgQueue[i]);
}
socketMsgQueue = [];
});
function sendSocketMessage(msg) {
if (socketOpen) {
uni.sendSocketMessage({
data: msg
});
} else {
socketMsgQueue.push(msg);
}
}
uni.onSocketMessage(CALLBACK)
监听WebSocket接受到服务器的消息事件。
平台兼容性
字节小程序不支持
CALLBACK 返回参数
参数 | 类型 | 说明 |
---|---|---|
data | String/ArrayBuffer | 服务器返回的消息 |
示例代码:
uni.connectSocket({
url: 'wss://www.example.com/socket'
});
uni.onSocketMessage(function (res) {
console.log('收到服务器内容:' + res.data);
});
uni.closeSocket(OBJECT)
关闭 WebSocket 连接。
平台兼容性
字节小程序不支持
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
code | Number | 否 | 一个数字值表示关闭连接的状态号,表示连接被关闭的原因。如果这个参数没有被指定,默认的取值是1000 (表示正常连接关闭) |
reason | String | 否 | 一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本(不是字符) |
success | Function | 否 | 接口调用成功的回调函数 |
fail | Function | 否 | 接口调用失败的回调函数 |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
uni.onSocketClose(CALLBACK)
监听WebSocket关闭。
平台兼容性
字节小程序不支持
uni.connectSocket({
url: 'wss://www.example.com/socket'
});
// 注意这里有时序问题,
// 如果 uni.connectSocket 还没回调 uni.onSocketOpen,而先调用 uni.closeSocket,那么就做不到关闭 WebSocket 的目的。
// 必须在 WebSocket 打开期间调用 uni.closeSocket 才能关闭。
uni.onSocketOpen(function () {
uni.closeSocket();
});
uni.onSocketClose(function (res) {
console.log('WebSocket 已关闭!');
});
SocketTask
SocketTask 由 uni.connectSocket() 接口创建。
平台差异说明
支付宝小程序、字节跳动小程序,没有明确的文档来具体说明这个对象,而是指向了 Web Websocket 对象。
SocketTask.onMessage(CALLBACK)
监听 WebSocket 接受到服务器的消息事件
回调函数
Function
WebSocket 接受到服务器的消息事件的回调函数
回调函数中的参数
Object
属性 | 类型 | 说明 |
---|---|---|
data | String/ArrayBuffer | 服务器返回的消息 |
SocketTask.send(OBJECT)
通过 WebSocket 连接发送数据
参数
属性 | 类型 | 是否必填 | 说明 |
---|---|---|---|
data | String/ArrayBuffer | 是 | 需要发送的内容 |
success | Function | 否 | 接口调用成功的回调函数 |
fail | Function | 否 | 接口调用失败的回调函数 |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
SocketTask.close(OBJECT)
关闭 WebSocket 连接
参数
属性 | 类型 | 默认值 | 是否必填 | 说明 |
---|---|---|---|---|
code | Number | 1000(表示正常关闭连接) | 否 | 一个数字值表示关闭连接的状态号,表示连接被关闭的原因。 |
reason | String | 否 | 一个可读的字符串,表示连接被关闭的原因。 | |
success | Function | 否 | 接口调用成功的回调函数 | |
fail | Function | 否 | 接口调用失败的回调函数 | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
SocketTask.onOpen(CALLBACK)
监听 WebSocket 连接打开事件
回调函数
Function
WebSocket 连接打开事件的回调函数
回调函数中的参数
Object
属性 | 类型 | 说明 |
---|---|---|
data | String/ArrayBuffer | 服务器返回的消息 |
SocketTask.onClose(CALLBACK)
监听 WebSocket 连接关闭事件
回调函数
Function
WebSocket 连接关闭事件的回调函数
SocketTask.onError(CALLBACK)
监听 WebSocket 错误事件
回调函数
Function
WebSocket 错误事件的回调函数
回调函数中的参数
Object
属性 | 类型 | 说明 |
---|---|---|
errMsg | String | 错误信息 |
mDNS 服务
UDP 通信
仅微信小程序平台支持,规范详情