【Uni-App】API笔记 P1

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

clearTimeout(stId)

设定一个定时器。按照指定的周期（以毫秒计）来执行注册的回调函数

参数说明

参数	类型	必填	说明
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

clearInterval(itId);

注意事项

• 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

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	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、文件上传 & 下载

一、文件上传

uni.uploadFile(OBJECT)

将本地资源上传到开发者服务器，客户端发起一个 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();
            }
        });
    }
});

二、文件下载

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	否	接口调用结束的回调函数（调用成功、失败都会执行）

注：文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 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