网络
说明:
在小程序中使用网络相关的 API 时,需要注意下列问题,请开发者提前了解。
服务器域名配置
配置流程
服务器域名请在小程序后台 > 设置 > 开发设置 > 服务器域名中进行配置,配置时需要注意:
域名只支持 https (wx.request)、(wx.uploadFile)协议。
域名不能使用 IP 地址或 localhost。
可以配置端口,如 https://miniApp.com:8080,但是配置后只能向 https://miniApp.com:8080 发起请求。如果向 https://miniApp.com、https://miniApp.com:9091 等 URL 请求则会失败。
如果不配置端口。如 https://miniApp.com,那么请求的 URL 中也不能包含端口,甚至是默认的 443 端口也不可以。如果向 https://miniApp.com:443 请求则会失败。
网络请求
超时时间
默认超时时间和最大超时时间都是60s。
超时时间可以在 app.json 中配置。
使用限制
网络请求的 referer header 不可设置。其格式固定为 https://appservice.wx.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为0表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。
wx.request、wx.uploadFile 的最大并发限制是 10 个。
小程序进入后台运行后,如果5s内网络请求没有结束,会回调错误信息 fail interrupted;在回到前台之前,网络请求接口调用都会无法调用。
返回值编码
建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码,小程序会尝试进行转换,但是会有转换失败的可能。
小程序会自动对 BOM 头进行过滤(只过滤一个 BOM 头)。
回调函数
只要成功接收到服务器返回,无论
statusCode
是多少,都会进入success
回调。请开发者根据业务逻辑对返回值进行判断。常见问题
HTTPS 证书
小程序必须使用 HTTPS/WSS 发起网络请求。请求时系统会对服务器域名使用的 HTTPS 证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书是否符合要求。
对证书要求如下:
HTTPS 证书必须有效;
证书必须被系统信任,即根证书被已系统内置。
部署 SSL 证书的网站域名必须与证书颁发的域名一致。
证书必须在有效期内。
证书的信任链必需完整(需要服务器配置)。
iOS
不支持自签名证书。iOS
下证书必须满足苹果 App Transport Security (ATS) 的要求。TLS 必须支持 1.2 及以上版本。部分旧
Android
机型还未支持 TLS 1.2,请确保 HTTPS 服务器的 TLS 版本支持 1.2 及以下版本。部分 CA 可能不被操作系统信任,请开发者在选择证书时注意小程序和各系统的相关通告。
说明:
证书有效性可以使用
openssl s_client -connect example.com:443
命令验证,也可以使用其他 在线工具。除了网络请求 API 外,小程序中其他 HTTPS 请求如果出现异常,也请按上述流程进行检查。如 https 的图片无法加载、音视频无法播放等。
跳过域名校验
在开发者工具中,可以临时开启
开发环境不校验请求域名
、TLS版本及 HTTPS 证书
选项,跳过服务器域名的校验。此时,在开发者工具中及手机开启调试模式时,不会进行服务器域名的校验。在服务器域名配置成功后,建议开发者关闭此选项进行开发,并在各平台下进行测试,以确认服务器域名配置正确。
说明:
如果手机上出现 “打开调试模式可以发出请求,关闭调试模式无法发出请求” 的现象,请确认是否跳过了域名校验,并确认服务器域名和证书配置是否正确。
如遇到“服务器内部错误”,请尝试以下办法自查 ①更换浏览器 ②刷新网页 ③排查文件是否放在正确的服务器根目录下。 排查办法:按照以下规则拼接网址,并且自行尝试访问是否成功:https://m.da9c.cn/文件名。
存储
每个小程序都可以有自己的本地缓存,可以通过 wx.setStorage/qq.setStorageSync、wx.getStorage/wx.getStorageSync、qq.clearStorage/wx.clearStorageSync,wx.removeStorage/wx.removeStorageSync 对本地缓存进行读写和清理。
同一个用户,同一个小程序 storage 上限为 10MB。storage 以用户维度隔离,同一台设备上,A 用户无法读取到 B 用户的数据。
说明:
如果用户储存空间不足,应用会清空最近最久未使用的小程序的本地缓存,因此并不建议将关键信息全部存在 storage,以防储存空间不足或用户换设备的情况。
Canvas画布
所有在 <canvas> 中的画图必须用 JavaScript 完成:
WXML:在接下来的示例中如无特殊声明都会用这个 WXML 为模板,不再重复。
<canvas canvas-id="myCanvas" style="border: 1px solid;" />
JS:我们在接下来的例子中会将 JS 放在 onLoad 中
const ctx = wx.createCanvasContext('myCanvas')ctx.setFillStyle('red')ctx.fillRect(10, 10, 150, 75)ctx.draw()
第一步:创建一个 Canvas 绘图上下文
首先,我们需要创建一个 Canvas 绘图上下文 CanvasContext。CanvasContext 是小程序内建的一个对象,有一些绘图的方法:
const ctx = wx.createCanvasContext('myCanvas')
第二步:使用 Canvas 绘图上下文进行绘图描述
接着,我们来描述要在 Canvas 中绘制什么内容。设置绘图上下文的填充色为红色:
ctx.setFillStyle('red')
用
fillRect(x, y, width, height)
方法画一个矩形,填充为刚刚设置的红色:ctx.fillRect(10, 10, 150, 75)
第三步:画图
告诉 <canvas> 组件,您要将刚刚的描述绘制上去:
ctx.draw()
![](https://qcloudimg.tencent-cloud.cn/image/document/b34bcd09ea4a679d342bf0ae855b70e8.png)
坐标系
可以在 <canvas> 中加上一些事件,来观测它的坐标系:
<canvascanvas-id="myCanvas"style="margin: 5px; border:1px solid #d3d3d3;"bindtouchstart="start"bindtouchmove="move"bindtouchend="end"/><view hidden="{{hidden}}">Coordinates: ({{x}}, {{y}})</view>
Page({data: {x: 0,y: 0,hidden: true},start(e) {this.setData({hidden: false,x: e.touches[0].x,y: e.touches[0].y})},move(e) {this.setData({x: e.touches[0].x,y: e.touches[0].y})},end(e) {this.setData({hidden: true})}})
当您把手指放到 canvas 中,就会在下边显示出触碰点的坐标:
![](https://qcloudimg.tencent-cloud.cn/image/document/fbb7d9314061184c7d550b24c294079e.gif)
渐变
渐变能用于填充一个矩形,圆,线,文字等。填充色可以不固定为固定的一种颜色。
我们提供了两种颜色渐变的方式:
createLinearGradient(x, y, x1, y1)
创建一个线性的渐变。createCircularGradient(x, y, r)
创建一个从圆心开始的渐变。创建了一个渐变对象,就必须添加两个颜色渐变点。
addColorStop(position, color)
方法用于指定颜色渐变点的位置和颜色,位置必须位于0到1之间。可以用 setFillStyle 和 setStrokeStyle 方法设置渐变,然后进行画图描述。
使用
createLinearGradient()
const ctx = wx.createCanvasContext('myCanvas')// Create linear gradientconst grd = ctx.createLinearGradient(0, 0, 200, 0)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()
![](https://qcloudimg.tencent-cloud.cn/image/document/3ed60fdd3296e9084f1698b188731c92.png)
使用
createCircularGradient()
const ctx = wx.createCanvasContext('myCanvas')// Create circular gradientconst grd = ctx.createCircularGradient(75, 50, 50)grd.addColorStop(0, 'red')grd.addColorStop(1, 'white')// Fill with gradientctx.setFillStyle(grd)ctx.fillRect(10, 10, 150, 80)ctx.draw()
![](https://qcloudimg.tencent-cloud.cn/image/document/5bebb2d7aa806d1644c3f51c121cea47.png)
自定义 tabBar
自定义 tabBar 可以让开发者更加灵活地设置 tabBar 样式,以满足更多个性化的场景。
在自定义 tabBar 模式下
为了保证低版本兼容以及区分哪些页面是 tab 页,tabBar 的相关配置项需完整声明,但这些字段不会作用于自定义 tabBar 的渲染。
此时需要开发者提供一个自定义组件来渲染 tabBar,所有 tabBar 的样式都由该自定义组件渲染。推荐用 fixed 在底部的 <cover-view> + <cover-image> 组件渲染样式,以保证 tabBar 层级相对较高。
与 tabBar 样式相关的接口,如 wx.setTabBarItem 等将失效。
每个 tab 页下的自定义 tabBar 组件实例是不同的,可通过自定义组件下的 getTabBar 接口,获取当前页面的自定义 tabBar 组件实例。
说明:
配置信息
在
app.json
中的 tabBar
项指定 custom
字段,同时其余 tabBar
相关配置也补充完整。所有 tab 页的 json 里需声明
usingComponents
项,也可以在 app.json
全局开启。示例代码:
{"tabBar": {"custom": true,"color": "#000000","selectedColor": "#000000","backgroundColor": "#000000","list": [{"pagePath": "page/develop/miniprogram/develop/miniprogram/component/index","text": "组件"},{"pagePath": "page/develop/miniprogram/API/index","text": "接口"}]},"usingComponents": {}}
添加 tabBar 代码
在代码根目录下添加入口文件:
custom-tab-bar/index.jscustom-tab-bar/index.jsoncustom-tab-bar/index.wxmlcustom-tab-bar/index.wxss
编写 tabBar 代码
用自定义组件的方式编写即可,该自定义组件完全接管 tabBar 的渲染。另外,自定义组件新增
getTabBar
接口,可获取当前页面下的自定义 tabBar 组件实例。示例代码:
// page/index/index.jsPage({onShow:function(){// 取当前页面的TabBar实例,设置选中态if (typeof this.getTabBar === 'function' && this.getTabBar()) {this.getTabBar().setData({selected: 0})}}})