小程序网络请求。
my.request
目前支持 GET/POST/PUT/DELETE
。my.request
目前只支持 HTTPS 协议的请求。my.canIUse('request')
做兼容性处理。详见 小程序基础库说明。my.httpRequest
将被废弃,请使用 my.request
来代替。my.request
的请求头默认值为 {'content-type': 'application/json'}
,而不是 {'content-type': 'application/x-www-form-urlencoded'}
。此外,请求头对象里面的 key 和 value 必须是 String 类型。更多问题请参见 my.request 常见问题。
使用说明:
my.request
)、上传文件(my.uploadFile
)。名称 | 类型 | 必填 | 描述 |
---|---|---|---|
url | String | 是 | 目标服务器 url |
headers | Object | 否 | 设置请求的 HTTP 头,默认为 {'content-type': 'application/json'} ,该对象中的 key 和 value 必须是 String 类型。 |
method | String | 否 | 默认为 GET,目前支持 GET/POST/PUT/DELETE。 |
data | Object / ArrayBuffer | 否 | data 参数说明。 |
timeout | Number | 否 | 超时时间,单位为 ms,默认为 30000 |
dataType | String | 否 | 期望返回的数据格式,默认为 json,支持 json、text、base64 和 arraybuffer。 |
success | Function | 否 | 调用成功的回调函数 |
fail | Function | 否 | 调用失败的回调函数 |
complete | Function | 否 | 调用结束的回调函数(调用成功、失败都会执行) |
传给服务器的数据最终会是 String 类型,如果数据不是 String 类型,会被转换成 String 。转换规则如下:
GET
,会将数据转换成 query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...
。POST
且 headers['content-type']
为 application/json
,会对数据进行 JSON 序列化。POST
且 headers['content-type']
为 application/x-www-form-urlencoded
,会将数据转换成 query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...
。referer
Header 不可设置。https://urlhost/{appid}/{version}/page-frame.html
,其中 {appid}
为小程序的 APPID,{version}
为小程序的版本号。名称 | 类型 | 描述 |
---|---|---|
data | String | 响应数据,格式取决于请求时的 dataType 参数 |
status | Number | 响应码 |
headers | Object | 响应头 |
错误码 | 描述 | 解决方案 |
---|---|---|
1 | 请求没有结束,就跳转到了另一个页面 | 建议请求完成后再进行页面跳转 |
2 | 参数错误。 |
|
11 | 无权跨域 | 检查请求域名是否添加了域名白名单,开发版测试可以点击 IDE 右上角 > 详情,勾选 忽略 httpRequest 域名合法性检查。 注意:新版本上架,一定要添加 服务器域名白名单,否则会出现异常。 |
12 | 网络出错 | 建议检查网络环境是否正常,服务器是否稳定。 |
13 | 超时 | 建议检查网络环境是否正常,服务器是否正常响应,若请求需要时间长,可适当设置超时时间 timeout。 |
14 | 解码失败 | 建议检查前后端请求和响应数据格式是否一致。如返回数据格式 text 与入参 dataType 值 JSON 不一致而导致接口报错,请修改后台返回数据格式为 JSON。 |
15 | 传参失败。 | 小程序页面传参如果做 urlencode 需要把整体参数进行编码。 |
19 | HTTP 错误 |
|
20 | 请求已被停止/服务端限流 | 请确认请求服务器是否能正常请求和响应。 |
23 | 代理请求失败。 | 建议检查代理配置是否正确。 |
dataType
值为 json
时,小程序框架会先对返回结果做 JSON.prase
操作,如果解析失败,则会返回 error
为 14 的错误。当入参 dataType
值为 text
时,如果返回的内容格式不符,也会返回 error
为 14 的错误。遇到此错误时,请先检查 dataType
的设置是否正确。
若 my.request
调用返回 无权调用该接口,则需要在 开放平台小程序管理 > 服务器域名白名单 中配置域名白名单。
案例仅供参考,建议使用您自己的地址进行测试。
my.request({
url: 'https://httpbin.org/post',
method: 'POST',
data: {
from: '支付宝',
production: 'AlipayJSAPI',
},
dataType: 'json',
success: function(res) {
my.alert({content: 'success'});
},
fail: function(res) {
my.alert({content: 'fail'});
},
complete: function(res) {
my.hideLoading();
my.alert({content: 'complete'});
}
});
// 返回RequestTask,可以调用abort方法取消请求
const task = my.request({url: 'https://httpbin.org/post'})
task.abort()
网络请求任务对象。
RequestTask.abort()
上传本地资源到开发者服务器。
使用说明:
my.request
)、上传文件(my.uploadFile
)。 名称 | 类型 | 必填 | 描述 |
---|---|---|---|
url | String | 是 | 开发者服务器地址 |
filePath | String | 是 | 要上传文件资源的本地定位符 |
fileName | String | 是 | 文件名,即对应的 key, 开发者在服务器端通过这个 key 可以获取到文件二进制内容 |
fileType | String | 是 | 文件类型,image/video/audio |
hideLoading | Bool | 否 | 是否隐藏 loading 图(默认值为 false) |
header | Object | 否 | HTTP 请求 Header |
formData | Object | 否 | HTTP 请求中其他额外的 form 数据 |
success | Function | 否 | 调用成功的回调函数 |
fail | Function | 否 | 调用失败的回调函数 |
complete | Function | 否 | 调用结束的回调函数(调用成功、失败都会执行) |
名称 | 类型 | 描述 |
---|---|---|
data | String | 服务器返回的数据 |
statusCode | String | HTTP 状态码 |
header | Object | 服务器返回的 Header |
error | 描述 | 解决方案 |
---|---|---|
11 | 文件不存在 | 检查本地文件是否存在 |
12 | 上传文件失败 | 检查网络和服务器 |
13 | 没有权限 | 检查权限设置 |
案例仅供参考,建议使用您自己的地址进行测试。
my.uploadFile({
url: '请使用自己服务器地址',
fileType: 'image',
fileName: 'file',
filePath: '...',
success: (res) => {
my.alert({
content: '上传成功'
});
},
});
监听上传进度变化,取消上传任务的对象。
方法 | 描述 |
---|---|
UploadTask.abort() | 中断上传任务 |
UploadTask.onProgressUpdate(function callback) | 监听上传进度变化事件 |
const task = my.uploadFile({
url: '请使用自己服务器地址',
fileType: 'image',
fileName: 'file',
filePath: '...',
});
task.onProgressUpdate(({progress, totalBytesWritten, totalBytesExpectedToWrite}) => {
})
task.abort()
my.uploadFile
如何获取服务器返回的错误信息?my.uploadFile
默认超时时间是多长?是否可以设置默认延长时间?my.uploadFile
默认超时时间是 30s,目前无法设置默认延长时间。my.uploadFile
上传文件,为何报错 error:12
?error:12
,造成上传失败的可能原因有:my.uploadFile
上传图片至后台,接收的是二进制图片,再从后台发送小程序前台对应的二进制图片,小程序前台是如何解析的?my.uploadfile
,为何报错 error: 4
,无权限调用此接口?my.uploadFile
上传文件类型支持图片、视频、音频( image / video / audio),暂不支持其他类型的文件。my.uploadFile
是否支持多张图片同时上传?my.uploadFile
暂不支持多张图片同时上传,一次只能上传一张图片。
下载文件资源到本地。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
url | String | 是 | 下载文件地址 |
header | Object | 否 | HTTP 请求 Header |
success | Function | 否 | 调用成功的回调函数 |
fail | Function | 否 | 调用失败的回调函数 |
complete | Function | 否 | 调用结束的回调函数(调用成功、失败都会执行) |
名称 | 类型 | 描述 |
---|---|---|
apFilePath | String | 文件临时存放的位置 |
error | 描述 | 解决方案 |
---|---|---|
12 | 下载失败 | 建议检查网络和服务器 |
13 | 没有权限 | 建议检查权限 |
20 | 请求的 URL 不支持 HTTP | 建议将请求的 URL 改成 HTTPS |
案例仅供参考,建议使用您自己的地址进行测试。
// API-DEMO page/API/download-file/download-file.json
{
"defaultTitle": "下载文件"
}
<!-- API-DEMO page/API/download-file/download-file.axml-->
<view class="container">
<button onTap="download">下载图片并显示</button>
</view>
// API-DEMO page/API/download-file/download-file.js
Page({
download() {
my.downloadFile({
url: 'https://img.alicdn.com/tfs/TB1x669SXXXXXbdaFXXXXXXXXXX-520-280.jpg',
success({ apFilePath }) {
my.previewImage({
urls: [apFilePath],
});
},
fail(res) {
my.alert({
content: res.errorMessage || res.error,
});
},
});
},
})
创建一个 WebSocket 的连接。
一个小程序同时只能保留一个 WebSocket 连接,如果当前已存在 WebSocket 连接,会自动关闭该连接,并重新创建一个新的 WebSocket 连接。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
url | String | 是 | 目标服务器 URL。 注意:部分新发布的小程序只支持 wss 协议。 |
data | Object | 否 | 请求的参数 |
header | Object | 否 | 设置请求的头部 |
success | Function | 否 | 调用成功的回调函数 |
fail | Function | 否 | 调用失败的回调函数 |
complete | Function | 否 | 调用结束的回调函数(调用成功、失败都会执行) |
error | 描述 | 解决方案 |
---|---|---|
1 | 未知错误 | - |
2 | 网络连接已经存在 | 一个小程序在一段时间内只能保留一个 WebSocket 连接。如果当前已存在 WebSocket 连接,那么会自动关闭该连接,并重新创建一个新的 WebSocket 连接。 |
3 | URL 参数为空 | 替换 URL 链接。 |
4 | 无法识别的 URL 格式 | 替换 URL 链接。 |
5 | URL 必须以 ws 或者 wss 开头 |
替换 URL 链接。 |
6 | 连接服务器超时 | 稍后重试。 |
7 | 服务器返回的 https 证书无效 | 小程序必须使用 HTTPS/WSS 发起网络请求。请求时系统会对服务器域名使用的 HTTPS 证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书,确保其符合要求。 |
8 | 服务端返回协议头无效 | 从 2019 年 5 月开始新创建的小程序,默认强制使用 HTTPS 和 WSS 协议,不再支持 HTTP 和 WS 协议。 |
9 | WebSocket 请求没有指定 Sec-WebSocket-Protocol 请求头 |
请指定 Sec-WebSocket-Protocol 请求头。 |
10 | 网络连接没有打开,无法发送消息 | 请正常连接服务器后再调用 my.sendSocketMessage 发送数据消息,可通过 my.onSocketOpen 监听事件来判断与服务器建立正确连接。 注意:通过 WebSocket 连接发送数据,需要先使用 my.connectSocket 发起连接,在 my.onSocketOpen 回调之后再调用 my.sendSocketMessage 发送数据。 |
11 | 消息发送失败 | 稍后重试。 |
12 | 无法申请更多内存来读取网络数据 | 请检查内存。 |
案例仅供参考,建议使用您自己的地址进行测试。
my.connectSocket({
url: 'test.php',
data: {},
header:{
'content-type': 'application/json'
},
});
监听 WebSocket 连接打开事件。
Object 类型,属性如下:
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
callback | Function | 是 | WebSocket 连接打开事件的回调函数。 |
案例仅供参考,建议使用您自己的地址进行测试。
my.connectSocket({
url: 'test.php',
});
my.onSocketOpen(function(res) {
console.log('WebSocket 连接已打开!');
});
取消监听 WebSocket 连接打开事件。
案例仅供参考,建议使用您自己的地址进行测试。
Page({
onLoad() {
this.callback = this.callback.bind(this);
my.onSocketOpen(this.callback);
},
onUnload() {
my.offSocketOpen(this.callback);
},
callback(res) {
},
})
不传递 callback 值,则会移除监听所有的事件回调。代码示例如下:
my.offSocketOpen();
传递 callback 值,只移除对应的 callback 事件。代码示例如下:
my.offSocketOpen(this.callback);
监听 WebSocket 错误。
Obejct 类型,属性如下:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
callback | Function | 是 | WebSocket 错误事件的回调函数。 |
案例仅供参考,建议使用您自己的地址进行测试。
my.connectSocket({
url: '开发者的服务器地址'
});
my.onSocketOpen(function(res){
console.log('WebSocket 连接已打开!');
});
my.onSocketError(function(res){
console.log('WebSocket 连接打开失败,请检查!');
});
取消监听 WebSocket 错误。
案例仅供参考,建议使用您自己的地址进行测试。
Page({
onLoad() {
this.callback = this.callback.bind(this);
my.onSocketError(this.callback);
},
onUnload() {
my.offSocketError(this.callback);
},
callback(res) {
},
})
不传递 callback 值,则会移除监听所有的事件回调。代码示例如下:
my.offSocketError();
传递 callback 值,只移除对应的 callback 事件。代码示例如下:
my.offSocketError(this.callback);
通过 WebSocket 连接发送数据,需要先使用 my.connectSocket 发起建连,并在 my.onSocketOpen 回调之后再发送数据。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
data | String | 是 | 需要发送的内容:普通的文本内容 String 或者经 base64 编码后的 String。 |
isBuffer | Boolean | 否 | 如果需要发送二进制数据,需要将入参数据经 base64 编码成 String 后,赋值 data ,同时将此字段设置为 true,否则,若为普通的文本内容 String,则不需要设置此字段。 |
success | Function | 否 | 回调函数。 |
fail | Function | 否 | 调用失败的回调函数。 |
complete | Function | 否 | 调用结束的回调函数(调用成功、失败都会执行)。 |
案例仅供参考,建议使用您自己的地址进行测试。
my.sendSocketMessage({
data: this.data.toSendMessage, // 需要发送的内容
success: (res) => {
my.alert({content: '数据发送!' + this.data.toSendMessage});
},
});
监听 WebSocket 接受到服务器的消息事件。
名称 | 类型 | 描述 |
---|---|---|
data | String/ArrayBuffer | 服务器返回的消息:普通的文本 String 或者经 base64 编码后的 String。 |
isBuffer | Boolean | 如果此字段值为 true ,data 字段表示接收到的经过了 base64 编码后的 String,否则,data 字段表示接收到的普通 String 文本。 |
案例仅供参考,建议使用您自己的地址进行测试。
my.connectSocket({
url: '服务器地址'
})
my.onSocketMessage(function(res) {
console.log('收到服务器内容:' + res.data)
})
取消监听 WebSocket 接受到服务器的消息事件。
案例仅供参考,建议使用您自己的地址进行测试。
my.connectSocket({
url: '服务器地址'
})
my.onSocketMessage(function(res) {
console.log('收到服务器内容:' + res.data)
})
my.offSocketMessage();
不传递 callback 值,则会移除监听所有的事件回调。代码示例如下:
my.offSocketMessage();
传递 callback 值,只移除对应的 callback 事件。代码示例如下:
my.offSocketMessage(this.callback);
关闭 WebSocket 连接。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
success | Function | 否 | 回调函数 |
fail | Function | 否 | 调用失败的回调函数 |
complete | Function | 否 | 调用结束的回调函数(调用成功、失败都会执行) |
案例仅供参考,建议使用您自己的地址进行测试。
my.onSocketOpen(function() {
my.closeSocket()
})
my.onSocketClose(function(res) {
console.log('WebSocket 已关闭!')
})
监听 WebSocket 关闭。
Obejct 类型,属性如下:
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
callback | Function | 是 | WebSocket 连接关闭事件的回调函数。 |
案例仅供参考,建议使用您自己的地址进行测试。
onLoad() {
// 注意: 回调方法的注册在整个小程序启动阶段只要做一次,调多次会有多次回调
my.onSocketClose((res) => {
my.alert({content: '连接已关闭!'});
this.setData({
sendMessageAbility: false,
closeLinkAbility: false,
});
});
// 注意: 回调方法的注册在整个小程序启动阶段只要做一次,调多次会有多次回调
my.onSocketOpen((res) => {
my.alert({content: '连接已打开!'});
this.setData({
sendMessageAbility: true,
closeLinkAbility: true,
});
});
my.onSocketError(function(res){
my.alert('WebSocket 连接打开失败,请检查!' + res);
});
// 注意: 回调方法的注册在整个小程序启动阶段只要做一次,调多次会有多次回调
my.onSocketMessage((res) => {
my.alert({content: '收到数据!' + JSON.stringify(res)});
});
}
connect_start() {
my.connectSocket({
url: '服务器地址', // 开发者服务器接口地址,必须是 wss 协议,且域名必须是后台配置的合法域名
success: (res) => {
my.showToast({
content: 'success', // 文字内容
});
},
fail:()=>{
my.showToast({
content: 'fail', // 文字内容
});
}
});
},
取消监听 WebSocket 关闭。
案例仅供参考,建议使用您自己的地址进行测试。
Page({
onLoad() {
my.onSocketClose(this.callback);
},
onUnload() {
my.offSocketClose(this.callback);
// my.offSocketClose();
},
callback(res) {
my.alert({content: '连接已关闭!'});
this.setData({
sendMessageAbility: false,
closeLinkAbility: false,
});
},
})
不传递 callback 值,则会移除监听所有的事件回调。示例代码如下:
my.offSocketClose();
传递 callback 值,只移除对应的 callback 事件。示例代码如下:
my.offSocketClose(this.callback);
在文档使用中是否遇到以下问题
更多建议
匿名提交