网络

my.request

小程序网络请求。

• my.request 目前支持 GET/POST/PUT/DELETE。
• my.request 目前只支持 HTTPS 协议的请求。

更多问题请参见 my.request 常见问题。

使用说明：

• 需预先在 小程序发布 > 开放平台小程序管理 中打开下图中的 小程序权限控制开关，并在 服务器域名白名单 中配置域名白名单。小程序在以下 API 调用时只能与白名单中的域名进行通讯：HTTP 请求（my.request）、上传文件（my.uploadFile）。
  
• 添加服务器域名白名单后，需要重新打包上传生成体验版，服务器域名才会生效。
• 在 IDE 上进行调试时，请使用真机预览调试。

入参

data 参数说明

传给服务器的数据最终会是 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 说明

• 网络请求的 referer Header 不可设置。
• 其格式固定为 https://urlhost/{appid}/{version}/page-frame.html，其中 {appid} 为小程序的 APPID，{version} 为小程序的版本号。

success 返回值

错误码

若 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

网络请求任务对象。

方法

RequestTask.abort()

my.uploadFile

上传本地资源到开发者服务器。

使用说明：

• 需预先在 开放平台小程序管理 > 服务器域名白名单 中配置域名白名单。小程序在以下 API 调用时只能与白名单中的域名进行通讯：HTTP 请求（my.request）、上传文件（my.uploadFile）。

入参

success 返回值

错误码

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.uploadFile({
  url: '请使用自己服务器地址',
  fileType: 'image',
  fileName: 'file',
  filePath: '...',
  success: (res) => {
    my.alert({
      content: '上传成功'
    });
  },
});

UploadTask

监听上传进度变化，取消上传任务的对象。

方法

代码示例

const task = my.uploadFile({
  url: '请使用自己服务器地址',
  fileType: 'image',
  fileName: 'file',
  filePath: '...',
});
task.onProgressUpdate(({progress, totalBytesWritten, totalBytesExpectedToWrite}) => {
})
task.abort()

常见问题

• Q：小程序上传图片可以自动转成 Base64 (基于 64 个可打印字符来表示二进制数据的方法)吗？
  A：小程序暂不支持图片转成 Base64。
• Q：my.uploadFile 如何获取服务器返回的错误信息？
  A：
  • 可以通过 success 回调中的 data 参数获取。
  • 可以在服务端增加一个日志获取接口。如果上传失败，就请求到日志获取接口获取详细的失败日志。
• Q：my.uploadFile 默认超时时间是多长？是否可以设置默认延长时间？
  A：my.uploadFile 默认超时时间是 30s，目前无法设置默认延长时间。
• Q：使用 my.uploadFile 上传文件，为何报错 error:12？
  A：上传失败导致报错 error:12，造成上传失败的可能原因有：
  • 文件过大。
  • 上传时间超过 30s。
  • 没有权限。
• Q：使用 my.uploadFile 上传图片至后台，接收的是二进制图片，再从后台发送小程序前台对应的二进制图片，小程序前台是如何解析的？
  A：上传图片是后端通过二进制流接受图片，之后后端只需提供对应的图片在服务器上的位置地址即可。
• Q：调用 my.uploadfile，为何报错 error: 4，无权限调用此接口？
  A：请求的 URL 没有配置白名单，建议添加 URL 的域名为白名单。
• Q：小程序是否支持上传 excel 文件？
  A：目前 my.uploadFile 上传文件类型支持图片、视频、音频（ image / video / audio），暂不支持其他类型的文件。
• Q：my.uploadFile 是否支持多张图片同时上传？
  A：my.uploadFile 暂不支持多张图片同时上传，一次只能上传一张图片。

my.downloadFile

下载文件资源到本地。

入参

success 返回值

错误码

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

// 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,
        });
      },
    });
  },
})

my.connectSocket

创建一个 WebSocket 的连接。

一个小程序同时只能保留一个 WebSocket 连接，如果当前已存在 WebSocket 连接，会自动关闭该连接，并重新创建一个新的 WebSocket 连接。

入参

错误码

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.connectSocket({
  url: 'test.php',
  data: {},
  header:{
    'content-type': 'application/json'
  },
});

my.onSocketOpen

监听 WebSocket 连接打开事件。

入参

Object 类型，属性如下：

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.connectSocket({
  url: 'test.php',
});
my.onSocketOpen(function(res) {
  console.log('WebSocket 连接已打开！');
});

my.offSocketOpen

取消监听 WebSocket 连接打开事件。

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onSocketOpen(this.callback);
  },
  onUnload() {
    my.offSocketOpen(this.callback);
  },
  callback(res) {
  },
})

是否需要传 callback 值

• 不传递 callback 值，则会移除监听所有的事件回调。代码示例如下：

  my.offSocketOpen();

• 传递 callback 值，只移除对应的 callback 事件。代码示例如下：

  my.offSocketOpen(this.callback);

my.onSocketError

监听 WebSocket 错误。

入参

Obejct 类型，属性如下：

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.connectSocket({
  url: '开发者的服务器地址'
});
my.onSocketOpen(function(res){
  console.log('WebSocket 连接已打开！');
});
my.onSocketError(function(res){
  console.log('WebSocket 连接打开失败，请检查！');
});

my.offSocketError

取消监听 WebSocket 错误。

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onSocketError(this.callback);
  },
  onUnload() {
    my.offSocketError(this.callback);
  },
  callback(res) {
  },
})

是否需要传 callback 值

• 不传递 callback 值，则会移除监听所有的事件回调。代码示例如下：

  my.offSocketError();

• 传递 callback 值，只移除对应的 callback 事件。代码示例如下：

  my.offSocketError(this.callback);

my.sendSocketMessage

通过 WebSocket 连接发送数据，需要先使用 my.connectSocket 发起建连，并在 my.onSocketOpen 回调之后再发送数据。

入参

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.sendSocketMessage({
    data: this.data.toSendMessage, // 需要发送的内容
    success: (res) => {
        my.alert({content: '数据发送！' + this.data.toSendMessage});
    },
});

my.onSocketMessage

监听 WebSocket 接受到服务器的消息事件。

回调返回值

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.connectSocket({
  url: '服务器地址'
})
my.onSocketMessage(function(res) {
  console.log('收到服务器内容：' + res.data)
})

my.offSocketMessage

取消监听 WebSocket 接受到服务器的消息事件。

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.connectSocket({
  url: '服务器地址'
})
my.onSocketMessage(function(res) {
  console.log('收到服务器内容：' + res.data)
})
my.offSocketMessage();

是否需要传 callback 值

• 不传递 callback 值，则会移除监听所有的事件回调。代码示例如下：

  my.offSocketMessage();

• 传递 callback 值，只移除对应的 callback 事件。代码示例如下：

  my.offSocketMessage(this.callback);

my.closeSocket

关闭 WebSocket 连接。

入参

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

my.onSocketOpen(function() {
  my.closeSocket()
})
my.onSocketClose(function(res) {
  console.log('WebSocket 已关闭！')
})

my.onSocketClose

监听 WebSocket 关闭。

入参

Obejct 类型，属性如下：

代码示例

案例仅供参考，建议使用您自己的地址进行测试。

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', // 文字内容
        });
      }
    });
  },

my.offSocketClose

取消监听 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 值

• 不传递 callback 值，则会移除监听所有的事件回调。示例代码如下：

  my.offSocketClose();

• 传递 callback 值，只移除对应的 callback 事件。示例代码如下：

  my.offSocketClose(this.callback);