1、调试打印:
console.log() 向控制台打印 log 日志
console.debug() 向控制台打印 debug 日志 注:App 端自定义组件模式下,debug 方法等同于 log 方法
console.info() 向控制台打印 info 日志
console.warn() 向控制台打印 warn 日志
console.error() 向控制台打印 error 日志
- 不同平台对于 console 方法的支持存在差异,建议在开发过程中只使用文档中提到的方法。
- HBuilderX中有2个重要的代码块,敲
clog:可直接输出console.log();敲clogv:可输出console.log(": " + );,并且出现双光标,方便把变量名称和值同时打印出来。
- HBuilderX 1.9.7 以上的自定义组件模式,在App端支持打印对象信息到控制台。老版本可使用
clogj代码块将json对象转为字符串打印出来。
2、定时器
设定一个定时器。在定时到期以后执行注册的回调函数
参数说明
| 参数 | 类型 | 必填 | 说明 |
| callback |
Function |
是 |
回调函数 |
| delay |
Number |
否 |
延迟的时间,函数的调用会在该延迟之后发生,单位 ms |
| rest |
Any |
否 |
param1, param2, ..., paramN 等附加参数,它们会作为参数传递给回调函数 |
返回值
| 返回值 | 类型 | 说明 |
| timeoutID |
Number |
定时器的编号,这个值可以传递给 clearTimeout 来取消该定时 |
let stId = setTimeout(function(p1, p2, p3) {
// todo ...
}, 300, 'a', true, 100)
取消由 setTimeout 设置的定时器。
参数说明
| 参数 | 类型 | 必填 | 说明 |
| timeoutID |
Number |
是 |
要取消的定时器的 ID |
设定一个定时器。按照指定的周期(以毫秒计)来执行注册的回调函数
参数说明
| 参数 | 类型 | 必填 | 说明 |
| callback |
Function |
是 |
回调函数 |
| delay |
Number |
否 |
延迟的时间,函数的调用会在该延迟之后发生,单位 ms |
| rest |
Any |
否 |
param1, param2, ..., paramN 等附加参数,它们会作为参数传递给回调函数 |
返回值
| 返回值 | 类型 | 说明 |
| intervalID |
Number |
定时器的编号,这个值可以传递给 clearInterval 来取消该定时 |
let itId = setInterval(function(p1, p2){
// todo ...
}, 1000, 'aaa', true);
取消由 setInterval 设置的定时器。
参数说明
| 参数 | 类型 | 必填 | 说明 |
| intervalID |
Number |
是 |
要取消的定时器的 ID |
注意事项
- App 端返回的定时器编号可能为 String 类型,使用时无需主动转换为 Number 类型
3、ArrayBuffer & Base64
MDN补充扩展
https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
将 Base64 字符串转成 ArrayBuffer 对象
平台差异说明
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序 | 快手小程序 |
| √ |
x |
√ |
x |
x |
x |
√ |
参数说明
| 参数 | 类型 | 必填 | 说明 |
| base64 |
String |
是 |
要转化成 ArrayBuffer 对象的 Base64 字符串 |
示例
const base64 = 'test'
const arrayBuffer = uni.base64ToArrayBuffer(base64)
将 ArrayBuffer 对象转成 Base64 字符串
平台差异说明
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序 | 快手小程序 |
| √ |
x |
√ |
x |
x |
x |
√ |
参数说明
| 参数 | 类型 | 必填 | 说明 |
| arrayBuffer |
ArrayBuffer |
是 |
要转换成 Base64 字符串的 ArrayBuffer 对象 |
示例
const arrayBuffer = new Uint8Array([55, 55, 55])
const base64 = uni.arrayBufferToBase64(arrayBuffer)
4、请求 Request
发起网络请求。
在各个小程序平台运行时,网络相关的 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 | 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 对象的方法列表
| 方法 | 参数 | 说明 |
| 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();
六、注意事项
- 请求的
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数据,不含图片),过多数据应分页获取,以提升应用体验。
5、拦截器
1、添加拦截器
uni.addInterceptor(STRING, OBJECT)
STRING 参数说明
需要拦截的api名称,如:uni.addInterceptor('request', OBJECT) ,将拦截 uni.request()
OBJECT 参数说明
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 平台差异说明 |
| invoke |
Function |
否 |
|
拦截前触发 |
|
| success |
Function |
否 |
|
成功回调拦截 |
|
| fail |
Function |
否 |
|
失败回调拦截 |
|
| complete |
Function |
否 |
|
完成回调拦截 |
uni.request({
url: 'request/login', //仅为示例,并非真实接口地址。
success: (res) => {
console.log(res.data);
// 打印: {code:1,...}
}
});
uni.addInterceptor('request', {
invoke(args) {
// request 触发前拼接 url
args.url = 'https://www.example.com/'+args.url
},
success(args) {
// 请求成功后,修改code值为1
args.data.code = 1
},
fail(err) {
console.log('interceptor-fail',err)
},
complete(res) {
console.log('interceptor-complete',res)
}
})
2、移除拦截器
uni.removeInterceptor(STRING)
STRING 参数说明
需要删除拦截器的api名称
3、拦截器的适用场景
拦截器的适用场景非常多,比如路由拦截,权限引导等。
你可以参考插件市场,拦截器应用示例:图片选择api时无权限,引导用户快捷打开系统设置:https://ext.dcloud.net.cn/plugin?id=5095
6、文件上传 & 下载
一、文件上传
将本地资源上传到开发者服务器,客户端发起一个 POST 请求,其中 content-type 为 multipart/form-data。
如页面通过 uni.chooseImage 等接口获取到一个本地资源的临时文件路径后,可通过此接口将本地资源上传到指定服务器。另外选择和上传非图像、视频文件参考:https://ask.dcloud.net.cn/article/35547。
- uniCloud的上传API:https://uniapp.dcloud.io/uniCloud/storage?id=uploadfile
- 封装的更完善的uni-file-picker组件,文件选择、上传到uniCloud,一站式集成。
OBJECT 参数说明
| 参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
| url |
String |
是 |
开发者服务器 url |
|
| files |
Array |
否 |
需要上传的文件列表。使用 files 时,filePath 和 name 不生效。 |
App、H5( 2.6.15+) |
| fileType |
String |
见平台差异说明 |
文件类型,image/video/audio |
仅支付宝小程序,且必填。 |
| file |
File |
否 |
要上传的文件对象。 |
仅H5(2.6.15+)支持 |
| filePath |
String |
是 |
要上传文件资源的路径。 |
|
| 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();
}
});
}
});
二、文件下载
下载文件资源到本地,客户端直接发起一个 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 |
否 |
接口调用结束的回调函数(调用成功、失败都会执行) |
注:文件的临时路径,在应用本次启动期间可以正常使用,如需持久保存,需在主动调用 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();
}
});
7、WebSocket & SocketTask
一般来说不涉及,见官方文档
https://uniapp.dcloud.io/api/request/websocket https://uniapp.dcloud.io/api/request/socket-task
来源:https://www.cnblogs.com/mindzone/p/15146349.html |