tencent cloud

文档反馈

基础能力

最后更新时间:2024-03-04 23:07:33

    网络

    说明:
    在小程序中使用网络相关的 API 时,需要注意下列问题,请开发者提前了解。

    服务器域名配置

    每个小程序需要事先设置一个通讯域名,小程序只可以跟指定的域名与进行网络通信。包括普通 HTTPS 请求(wx.request)、上传文件(wx.uploadFile)。

    配置流程

    服务器域名请在小程序后台 > 设置 > 开发设置 > 服务器域名中进行配置,配置时需要注意:
    域名只支持 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()
    
    
    

    坐标系

    可以在 <canvas> 中加上一些事件,来观测它的坐标系:
    <canvas
    canvas-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 中,就会在下边显示出触碰点的坐标:
    
    
    

    渐变

    渐变能用于填充一个矩形,圆,线,文字等。填充色可以不固定位固定的一种颜色。
    我们提供了两种颜色渐变的方式:
    createLinearGradient(x, y, x1, y1)创建一个线性的渐变。
    createCircularGradient(x, y, r)创建一个从圆心开始的渐变。
    创建了一个渐变对象,就必须添加两个颜色渐变点。
    addColorStop(position, color)方法用于指定颜色渐变点的位置和颜色,位置必须位于0到1之间。
    可以用 setFillStyle 和 setStrokeStyle 方法设置渐变,然后进行画图描述。
    使用 createLinearGradient()
    const ctx = wx.createCanvasContext('myCanvas')
    
    // Create linear gradient
    const grd = ctx.createLinearGradient(0, 0, 200, 0)
    grd.addColorStop(0, 'red')
    grd.addColorStop(1, 'white')
    
    // Fill with gradient
    ctx.setFillStyle(grd)
    ctx.fillRect(10, 10, 150, 80)
    ctx.draw()
    
    
    
    使用 createCircularGradient()
    const ctx = wx.createCanvasContext('myCanvas')
    
    // Create circular gradient
    const grd = ctx.createCircularGradient(75, 50, 50)
    grd.addColorStop(0, 'red')
    grd.addColorStop(1, 'white')
    
    // Fill with gradient
    ctx.setFillStyle(grd)
    ctx.fillRect(10, 10, 150, 80)
    ctx.draw()
    
    
    

    自定义 tabBar

    自定义 tabBar 可以让开发者更加灵活地设置 tabBar 样式,以满足更多个性化的场景。
    在自定义 tabBar 模式下
    为了保证低版本兼容以及区分哪些页面是 tab 页,tabBar 的相关配置项需完整声明,但这些字段不会作用于自定义 tabBar 的渲染。
    此时需要开发者提供一个自定义组件来渲染 tabBar,所有 tabBar 的样式都由该自定义组件渲染。推荐用 fixed 在底部的 <cover-view> + <cover-image> 组件渲染样式,以保证 tabBar 层级相对较高。
    与 tabBar 样式相关的接口,如 wx.setTabBarItem 等将失效。
    每个 tab 页下的自定义 tabBar 组件实例是不同的,可通过自定义组件下的 getTabBar 接口,获取当前页面的自定义 tabBar 组件实例。
    说明:
    如需实现 tab 选中态,要在当前页面下,通过 getTabBar 接口获取组件实例,并调用 setData 更新选中态。可参考下文 配置信息 中的示例代码。

    配置信息

    在 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.js
    custom-tab-bar/index.json
    custom-tab-bar/index.wxml
    custom-tab-bar/index.wxss

    编写 tabBar 代码

    用自定义组件的方式编写即可,该自定义组件完全接管 tabBar 的渲染。另外,自定义组件新增getTabBar接口,可获取当前页面下的自定义 tabBar 组件实例。
    示例代码:
    // page/index/index.js
    
    Page({
    onShow:function(){
    
    // 取当前页面的TabBar实例,设置选中态
    if (typeof this.getTabBar === 'function' && this.getTabBar()) {
    this.getTabBar().setData({
    selected: 0
    })
    }
    }
    })
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持