微信小程序基础

 

=

导航

 

• 顶部
• 介绍
• 视图容器
• 基础内容
• 表单组件
• 操作反馈
• 导航
• 媒体组件
• 地图
• 画布
• 小程序API
• 网络
• 数据
• 位置
• 设备
• 界面
• 开发接口

 

• 顶部
• 介绍
• 视图容器
• 基础内容
• 表单组件
• 操作反馈
• 导航
• 媒体组件
• 地图
• 画布
• 小程序API
• 网络
• 数据
• 位置
• 设备
• 界面
• 开发接口

全面教程

介绍

微信小程序是一种不需要下载安装即可使用的应用，它实现了应用“触手可及”的梦想，用户扫一扫或者搜一下即可打开应用。也体现了“用完即走”的理念，用户不用关心是否安装太多应用的问题。微信“小程序”可以为开发者提供基于微信的表单、导航、地图、媒体和位置等开发组件，让他们在微信的网页里构建一个HTML 5应用。同时微信还开放了登录和微信支付等接口，让这个“小程序”可以和用户的微信账号打通。微信将“小程序”定义为“一种新的应用形态”。微信方面强调，小程序、订阅号、服务号、企业号目前是并行的体系。

虽然微信小程序本质上来说就是一个HTML 5（移动网页）应用，但与那些经常在朋友圈刷屏的 H5 小游戏或者应用不同的是，微信小程序获得更多的系统权限。首先是数据缓存能力，这可以让用户在打开一个小程序的时候将程序的主要框架缓存到微信上，下一次就可以快速打开了

主要内容包括一些API接口

• 视图容器：视图(View)、滚动视图、Swiper
• 基础内容：图标、文本、进度条
• 表单组件：按钮、表单等
• 操作反馈
• 导航
• 媒体组件：音频、图片、视频
• 地图
• 画布
• 微信小程序API
• 网络：上传下载能力、websocket
• 数据：数据缓存能力
• 位置：获取位置查看位置
• 设备：网络状态、系统信息、重力感应、罗盘
• 界面：设置导航条、导航、动画、绘画
• 开发接口：登录包括签名加密、用户信息、微信支付、模板消息

视图容器

视图(View)

        <view class="section">
          <view class="flex-wrp" style="display:flex;flex-direction:row;">
            <view class="flex-item bc_green">1</view>
            <view class="flex-item bc_red">2</view>
            <view class="flex-item bc_blue">3</view>
          </view>
        </view>
             

        <view class="section">
           <view class="flex-wrp" style="display:flex;flex-direction:column;">
             <view class="flex-item bc_green">1</view>
             <view class="flex-item bc_red">2</view>
             <view class="flex-item bc_blue">3</view>
           </view>
        </view>
             

滚动视图(scroll-view)

使用竖向滚动时，需要给<scroll-view/>一个固定高度，

• scroll-x允许横向滚动
• scroll-y允许纵向滚动
• scroll-top设置竖向滚动条位置
• scroll-left设置横向滚动条位置
• scroll-into-view值应为某子元素id，则滚动到该元素，元素顶部对齐滚动区域顶部
• bindscrolltoupper滚动到顶部/左边，会触发 scrolltoupper 事件
• bindscrolltolower滚动到底部/右边，会触发 scrolltolower 事件
• scroll-top滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}

        <scroll-view scroll-y="true" style="height: 200px;" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}"> 
           <view id="green" class="scroll-view-item bc_green"></view> 
           <view id="red"  class="scroll-view-item bc_red"></view>
           <view id="yellow" class="scroll-view-item bc_yellow">></view>
           <view id="blue" class="scroll-view-item bc_blue"></view>
        </scroll-view>
             

滑块视图容器(swiper)

swiper-item仅可放置在swiper组件中，宽高自动设置为100%

• indicator-dots是否显示面板指示点(默认false)
• autoplay是否自动切换(默认false)
• current当前所在页面的index(0)
• interval自动切换时间间隔(默认5000)
• duration滑动动画时长(默认1000)
• bindchangecurrent改变时会触发change事件，event.detail={current:current}

        <swpier indicator-dots="{{indicatorDots}}" autoplay="{{autoplay}}" interval="{{interval}}" duration="{{duration}}">
          <block wx:for-items="{{imgUrls}}">
            <swpier-item>
              <image src="{{item}}" class="slide-image" width="355" height="150"/>
              <text class="textindex">{{index}}</text>
            </swpier-item>
          </block>
        </swpier>

            <slider bindchange="durationChange" show-value min="1000" max="10000"/>duration

        durationChange: function(e) {
          this.setData({
            duration: e.detail.value
          })
        }
             

基础内容

图标

• typeicon的类型，有效值：
  • success
  • success_no_circle
  • safe_success
  • safe_warn
  • info
  • info_circle
  • warn
  • waiting
  • waiting_circle
  • circle
  • cancel
  • download
  • search
  • clear
• sizeicon的大小，单位px
• coloricon的颜色，同css的color

        <view class="group">
          <block wx:for="{{iconSize}}">
           <icon type="success" size="{{item}}"/>
          </block>
        </view>
             

文本

文本节点，支持转义符""。除了文本节点以外的其他节点都无法长按选中

             <text>{{text1}}+'
'+{{test2}}></text>
             

进度条(process)

• percent百分比0~100
• showInfo在进度条右侧显示百分比，默认false
• strokeWidth进度条线的宽度，单位px,默认为6
• color进度条颜色
• active进度条从左往右的动画,默认false

            <progress percent="20" show-info stroke-width="12" color="pink" active />
             

逻辑层

小程序开发框架的逻辑层是由JavaScript编写。逻辑层将数据进行处理后发送给视图层，同时接受视图层的事件反馈

增加 App 和 Page 方法，进行程序和页面的注册。

App()

App()函数用来注册一个小程序。接受一个object参数，其指定小程序的生命周期函数等。

• onLaunch生命周期函数--监听小程序初始化,当小程序初始化完成时，会触发onLaunch（全局只触发一次）
• onShow生命周期函数--监听小程序显示,当小程序启动，或从后台进入前台显示，会触发onShow
• onHide生命周期函数--监听小程序隐藏,当小程序从前台进入后台，会触发onHide
• 其他开发者可以添加任意的函数或数据到Object参数中，用this可以访问

当用户点击左上角关闭，或者按了设备Home键离开微信，小程序并没有正在的销毁，而是进入了后台；当再次启动微信或再次打开小程序，又会从后台进入前台.只有当小程序进入后台一定时间，或者系统资源占用过高，才会被真正的销毁。

        App({
          onLaunch: function() { 
            // Do something initial when launch.
          },
          onShow: function() {
              // Do something when show.
          },
          onHide: function() {
              // Do something when hide.
          },
          globalData: 'I am global data'
        })
             

App.prototype.getCurrentPage()

getCurrentPage()函数用户获取当前页面的实例。

getApp()

我们提供了全局的getApp()函数，可以获取到小程序实例。

        // other.js
        var appInstance = getApp()
        console.log(appInstance.globalData) // I am global data
             

App()必须在app.js中注册，且不能注册多个。不要在定义于App()内的函数中调用getApp()，使用this就可以拿到app实例。不要在onLaunch的时候调用getCurrentPage()，此时page还没有生成。通过getApp获取实例之后，不要私自调用生命周期函数。

Page()

Page()函数用来注册一个页面。接受一个object参数，其指定页面的初始数据、生命周期函数、事件处理函数等。

• data页面的初始数据
• onLoad生命周期函数--监听页面加载
• onReady生命周期函数--监听页面初次渲染完成
• onShow生命周期函数--监听页面显示
• onHide生命周期函数--监听页面隐藏
• onUnload生命周期函数--监听页面卸载
• onPullDownRefresh页面相关事件处理函数--监听用户下拉动作
• onReachBottom页面上拉触底事件的处理函数
• 其他开发者可以添加任意的函数或数据到 object 参数中，在页面的函数中用 this 可以访问

        //index.js
        Page({
          data: {
            text: "This is page data."
          },
          onLoad: function(options) {
            // Do some initialize when page load.
          },
          onReady: function() {
            // Do something when page ready.
          },
          onShow: function() {
            // Do something when page show.
          },
          onHide: function() {
            // Do something when page hide.
          },
          onUnload: function() {
            // Do something when page close.
          },
          onPullDownRefresh: function() {
            // Do something when pull down.
          },
          onReachBottom: function() {
            // Do something when page reach bottom.
          },
          // Event handler.
          viewTap: function() {
            this.setData({
              text: 'Set some data for updating view.'
            })
          },
          customData: {
            hi: 'MINA'
          }
        })
             

初始化数据

初始化数据将作为页面的第一次渲染。data将会以JSON的形式由逻辑层传至渲染层，所以其数据必须是可以转成JSON的格式：字符串，数字，布尔值，对象，数组。

            <view>{{text}}</view>
<view>{{array[0].msg}}</view>


        Page({
          data: {
            text: 'init data',
            array: [{msg: '1'}, {msg: '2'}]
          }
        })
             

• onLoad页面加载,一个页面只会调用一次。一个页面只会调用一次。接收页面参数可以获取wx.navigateTo和wx.redirectTo及<navigator/>中的
• onShow页面显示,每次打开页面都会调用一次。
• onReady页面初次渲染完成,一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。对界面的设置如wx.setNavigationBarTitle请在onReady之后设置。
• onHide页面隐藏,当navigateTo或底部tab切换时调用。
• onUnload页面卸载,当redirectTo或navigateBack的时候调用。
• onPullDownRefresh下拉刷新,监听用户下拉刷新事件,需要在config的window选项中开启enablePullDownRefresh。当处理完数据刷新后，wx.stopPullDownRefresh可以停止当前页面的下拉刷新。

事件处理函数

除了初始化数据和生命周期函数，Page中还可以定义一些特殊的函数：事件处理函数。在渲染层可以在组件中加入事件绑定，当达到触发事件时，就会执行Page中定义的事件处理函数。

        <view bindtap="viewTap"> click me </view>

        Page({
          viewTap: function() {
            console.log('view tap')
          }
        })
             

Page.prototype.setData()

setData函数用于将数据从逻辑层发送到视图层，同时改变对应的this.data的值。直接修改this.data无效，无法改变页面的状态，还会造成数据不一致。单次设置的数据不能超过1024kB，请尽量避免一次设置过多的数据。

表单组件

按钮(button)

• size有效值default, mini,默认default
• type按钮的样式类型，有效值primary, default, warn,默认default
• plain按钮是否镂空，背景色透明,false
• disabled是否禁用,默认false
• loading名称前是否带 loading 图标,默认false
• formType有效值：submit, reset，用于form组件，点击分别会触发submit/reset事件
• hover-class指定按钮按下去的样式类。当hover-class="none"时，没有点击态效果,默认button-hover{background-color:rgba(0,0,0,0.1);opacity:0.7;}

        <button type="primary" size="default" >牛</button>
        <button type="default" size="mini" disabled>牛</button>
        <button type="warn"    size="mini" plain>牛</button>
        <button type="warn"    size="default" >牛</button>
             

checkbox-group

多选项目组，内部由多个checkbox组成。checkbox-group内只能包含checkbox

• bindchangecheckbox-group中选中项发生改变是触发change事件，detail = {value:[选中的checkbox的value的数组]}
• valueheckbox标识，选中时触发checkbox-group的change事件，并携带checkbox的value
• disabled是否禁用
• checked当前是否选中，可用来设置默认选中

        <checkbox-group bindchange="checkboxChange">
             <label class="checkbox" wx:for-items="{{items}}">
               <checkbox value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}
             </label>
        </checkbox-group>

        Page({
          data: {
            items: [
              {name: 'USA', value: '美国'},
              {name: 'CHN', value: '中国', checked: 'true'},
              {name: 'BRA', value: '巴西'},
              {name: 'JPN', value: '日本'},
              {name: 'ENG', value: '英国'},
              {name: 'TUR', value: '法国'},
            ]
          },
          checkboxChange: function(e) {
            console.log('checkbox发生change事件，携带value值为：', e.detail.value)
          }          
        })
            

form

将表单内的用户输入的switch input checkbox slider radio picker 提交.当点击 <form/> 表单中 formType 为 submit 的 <button/> 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。

• report-submit是否返回formId用于发送模板消息
• bindsubmit携带form中的数据触发submit事件，event.detail = { value : {"name":"value"} , formId:"" }
• bindreset表单重置时会触发reset事件

        <form bindsubmit="formSubmit" bindReset="formReset">
           <view class="section section_gap">           
             <switch name="switch" />
             <input name="input" placeholder="hahha" />
             <radio value="1">中国</radio>
             <checkbox value="1"/>美食
             <button size="mini"  type="submit">啦啦</button>
             <button size="mini" type="reset">重置</button>
             <slider max="60" min="0" name="slider" show-value>设置</slider>
           </view>
        </form>
             

input

• value输入框的内容
• typeinput的类型，有效值：emoji(带有表情的输入框),text,number,idcard(带小数点的数字键盘),digit(带小数点的数字键盘),time,date
• password是否是密码类型
• placeholder输入框为空时占位符
• 输入框为空时占位符指定placeholder的样式
• placeholder-class指定placeholder的样式类
• disabled是否禁用
• maxlength最大输入长度，设置为0的时候不限制最大长度,默认是140
• auto-focus自动聚焦，拉起键盘。页面中只能有一个input设置auto-focus属性.默认是false
• focus使得input获取焦点,默认是false
• bindchange输入框失去焦点时，触发bindchange事件，event.detail={value:value}
• bindinput除了date/time类型外的输入框，当键盘输入时，触发input事件，event.detail={value:value}，处理函数可以直接return一个字符串，将替换输入框的内容。
• bindfocus输入框聚焦时触发，event.detail = {value:value}
• bindblur输入框失去焦点时触发，event.detail = {value:value}

            <input maxlength="10"  placeholder-style="color:red" bindinput="bindKeyInput" placeholder="这是一个可以自动聚焦的input" auto-focus/>
            
            Page({
            data:{
              focus:false,
              inputValue:""
            },

            bindReplaceInput:function(e){
              var value = e.detail.value;
              var pos = e.detail.cursor;
              if(pos != -1){
                //光标在中间
                var left = e.detail.value.slice(0,pos);
                //计算光标的位置
                pos = left.replace(/11/g,'2').length;
                }
            },             
            bindHideKeyboard:function(e){
              if(e.detail.value === "123"){
                //收起键盘
                wx.hideKeyboard();
              }
            }
            });
             

label

用来改进表单组件的可用性，使用for属性找到对应的id，或者将控件放在该标签下，当点击时，就会触发对应的控件。

目前可以绑定的控件有：button, checkbox, radio, switch。

            <label class="label-2__text" for="{{item.name}}"><text>{{item.name}}</text></label>
             

picker

滚动选择器，现支持三种选择器，通过mode来区分，分别是普通选择器，时间选择器，日期选择器，默认是普通选择器

• 普通选择器：mode=selector
  • rangemode为selector时，range有效
  • valuemode为selector时，是数字，表示选择了range中的第几个，从0开始。
  • bindchangevalue改变时触发change事件，event.detail= { value:value}
• 时间选择器：mode=time
  • valuemode为selector时，range有效
  • valuemode为selector时，是数字，表示选择了range中的第几个，从0开始。
  • bindchangevalue改变时触发change事件，event.detail= { value:value}
• 日期选择器：mode=date
  • value表示选中的日期，格式为"yyyy-MM-dd"
  • start表示有效日期范围的开始，字符串格式为"yyyy-MM-dd"
  • end表示有效日期范围的结束，字符串格式为"yyyy-MM-dd"
  • fields有效值year,month,day，表示选择器的粒度
  • bindchangevalue改变时触发change事件，event.detail= { value:value}

        <picker mode="time" value="{{time}}" start="09:01" end="21:01" bindchange="bindTimeChange">
             <view class="picker">
                 当前选择: {{time}}
             </view>
        </picker>

            Page({
            data: {
               date:"2016-09-01",
               time:"12:01"
            },
             bindTimeChange:function(e){
                this.setData({
                  time:e.detail.time
                })
            }
            })
        

radio

• bindchangeradio-group中的选中项发生变化时触发change事件，event.detai = {value : 选中项radio的value
• valueradio标识。当该radio选中时，radio-group的change事件会携带radio的value
• checked当前是否选中,默认为false
• disabled是否禁用,默认为false

        <radio-group class="radio-group" bindchange="radioChange">
           <label class="radio" wx:for-items="{{items}}">
             <radio value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}
           </label>
        </radio-group>

        Page({
          data: {
            items: [
              {name: 'USA', value: '美国'},
              {name: 'CHN', value: '中国', checked: 'true'},
              {name: 'BRA', value: '巴西'},
              {name: 'JPN', value: '日本'},
              {name: 'ENG', value: '英国'},
              {name: 'TUR', value: '法国'},
            ]
          },
          radioChange: function(e) {
            console.log('radio发生change事件，携带value值为：', e.detail.value)
          }
        })
             

slider

• min最小值，默认值0
• max最大值,默认值100
• step步长，取值必须大于 0，并且可被 (max - min) 整除，默认值1
• disabled是否禁用,默认值false
• value当前取值
• show-value默认值false,是否显示当前value
• bindchange完成一次拖动后触发的事件，event.detail = {value:value}

        <slider bindchange="slider4change" step="5" min="50" max="200" show-value/>

        var pageData = {}
        for(var i = 1; i < 5; ++i) {
          (function (index) {
            pageData['slider${index}change'] = function(e) {
              console.log('slider${index}发生change事件，携带值为', e.detail.value)
            }
          })(i);
        }
        Page(pageData)
             

switch

• checked是否选中,默认为false
• disabled是否禁用,默认为false
• type样式，有效值：switch, checkbox.默认是switch
• bindchangechecked改变时触发change事件，event.detail={ value:checked}

           <switch checked="{{switch1Checked}}" bindchange="switch1Change"/>
        

textarea

• value输入框的内容
• placeholder输入框为空时占位符
• placeholder-style指定 placeholder 的样式
• placeholder-class指定 placeholder 的样式类
• disabled是否禁用,默认false
• maxlength最大输入长度，设置为0的时候不限制最大长度.默认140
• auto-focus自动聚焦，拉起键盘。页面中只能有一个 <textarea/> 或<input/> 设置 auto-focus 属性
• focus获取焦点（开发工具暂不支持）.默认false
• auto-height是否自动增高，设置auto-height时，style.height不生效.默认false
• bindfocus输入框聚焦时触发，event.detail = {value: value}
• bindblur输入框失去焦点时触发，event.detail = {value: value}
• bindlinechange输入框行数变化时调用，event.detail = {height: 0, heightRpx: 0, lineCount: 0}

            <textarea bindblur="bindTextAreaBlur" placeholder-style="color:red;" auto-focus auto-height placeholder="自动变高" />
             

操作反馈

action-sheet

上拉菜单，从屏幕底部出现的菜单表。

• hidden是否隐藏,默认true
• bindchange点击背景或action-sheet-cancel按钮时触发change事件，不携带数据

action-sheet-item

底部菜单表的子选项。

action-sheet-cancel

底部菜单表的取消按钮，和action-sheet-item的区别是，点击它会触发action-sheet的change事件，并且外观上会同它上面的内容间隔开来

        <button type="default" bindtap="actionSheetTap">弹出action sheet</button>
        <action-sheet hidden="{{actionSheetHidden}}" bindchange="actionSheetChange">
             <block wx:for-items="{{actionSheetItems}}">
             <action-sheet-item class="item" bindtap="bind{{item}}">{{item}}</action-sheet-item>
             </block>
        <action-sheet-cancel class="cancel">取消</action-sheet-cancel>
        </action-sheet>
        

modal

modal即将废弃，请使用 API wx.showModal

• title标题
• hidden是否隐藏整个弹窗,默认false
• no-cancel是否隐藏cancel按钮，默认false
• confirm-textconfirm按钮文字.默认确定
• bindconfirm点击确认触发的回调
• bindcancel点击取消以及蒙层触发的回调

        <modal title="标题" confirm-text="confirm" cancel-text="cancel" hidden="{{modalHidden}}" bindconfirm="modalChange" bindcancel="modalChange">
             这是对话框的内容。
        </modal>
             

toast

toast即将废弃，请使用 API wx.showToast

• durationhidden设置false后，触发bindchange的延时，单位毫秒,默认值1500
• hidden是否隐藏,默认值false
• bindchangeduration延时后触发

            <toast hidden="{{toast1Hidden}}" duration="3000" bindchange="toast1Change">
             

loading

• hidden是否隐藏.默认值false

        <loading hidden="{{hidden}}">加载中...</loading>
             

导航

微信小程序导航 navigator

• url应用内的跳转链接
• redirect是否关闭当前页面.默认为false
• hover-class指定点击时的样式类，当hover-class="none"时，没有点击态效果.默认navigator-hover

navigator-hover默认为{background-color:rgba(0,0,0,0.1);opacity:0.7;},<navigator/>的子节点背景色应为透明色

        <navigator url="navigate?title=navigate" hover-class="navigator-hover">跳转到新页面</navigator>
        <navigator url="redirect?title=redirect" hover-class="other-navigator-hover" redirect >在当前页打开</navigator>
             

媒体组件

媒体组件audio

• action控制音频的播放、暂停，播放速率、播放进度的对象，有method和data两个参数
• src要播放音频的资源地址
• loop是否循环播放,默认为false
• controls是否显示默认控件,默认true
• poster默认控件上的音频封面的图片资源地址，如果controls属性值为false则设置poster无效
• name默认控件上的音频名字，如果controls属性值为false则设置name无效
• author默认控件上的作者名字，如果controls属性值为false则设置author无效
• binderror当发生错误时触发error事件，detail = {errMsg: MediaError.code}
• bindplay当开始/继续播放时触发play事件
• bindpause当暂停播放时触发pause事件
• bindratechange当播放速率改变时触发ratechange事件
• bindtimeupdate当播放进度改变时触发timeupdate事件，detail = {currentTime, duration}
• bindended当播放到末尾时触发ended事件

        <audio poster="{{poster}}" name="{{name}}" author="{{author}}" src="http://qqma.tingge123.com:823/   mp3/    2015-06-13/1434188181.mp3" action="{{action}}" controls loop></audio> 
        <button type="primary" bindtap="audioPlay">播放</button>
        <button type="primary" bindtap="audioPause">暂停</button>
        <button type="primary" bindtap="audioPlaybackRateSpeedUp">调为2倍速</button>
        <button type="primary" bindtap="audioPlaybackRateNormal">调为1倍速</button>
        <button type="primary" bindtap="audioPlaybackRateSlowDown">调为0.5倍速</button>
        <button type="primary" bindtap="audio14">设置当前播放时间为14秒</button>
        <button type="primary" bindtap="audioStart">回到开头</button>

        Page({
          data: {
            poster: 'http://pic.pimg.tw/pam86591/1408719752-3322564110_n.jpg',
            name: 'Sugar',
            author: 'Maroon 5'
          },
          audioPlay: function () {
            this.setData({
              action: {
                method: 'play'
              }
            });
          },
          audioPause: function () {
            this.setData({
              action: {
                method: 'pause'
              }
            });
          },
          audioPlaybackRateSpeedUp: function () {
            this.setData({
              action: {
                method: 'setPlaybackRate',
                data: 2
              }
            });
          },
          audioPlaybackRateNormal: function () {
            this.setData({
              action: {
                method: 'setPlaybackRate',
                data: 1
              }
            });
          },
          audioPlaybackRateSlowDown: function () {
            this.setData({
              action: {
                method: 'setPlaybackRate',
                data: 0.5
              }
            });
          },
          audio14: function () {
            this.setData({
              action: {
                method: 'setCurrentTime',
                data: 14
              }
            });
          },
          audioStart: function () {
            this.setData({
              action: {
                method: 'setCurrentTime',
                data: 0
              }
            });
          }
        })
             

image

• src图片资源地址
• mode图片裁剪、缩放的模式,image标签默认为300px,高度225px,默认scaleToFill
  

  mode有12种模式，其中3中是缩放模式，9种是裁剪模式。

  • scaleToFill不保持纵横比缩放图片，使图片的宽高完全拉伸至填满image元素
  • aspectFit保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。
  • aspectFill保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。
  • top不缩放图片，只显示图片的顶部区域
  • bottom不缩放图片，只显示图片的底部区域
  • center不缩放图片，只显示图片的中间区域
  • left不缩放图片，只显示图片的左边区域
  • right不缩放图片，只显示图片的右边区域
  • top left不缩放图片，只显示图片的左上边区域
  • top right不缩放图片，只显示图片的右上边区域
  • bottom left不缩放图片，只显示图片的左下边区域
  • bottom right不缩放图片，只显示图片的右下边区域
• binderror 当错误发生时，发布到AppService的事件名，事件对象event.detail = { errMsg: 'something wrong' }
• bindload当图片载入完毕时，发布到AppService的事件名，事件对象event.detail = {}

        <image style=" 200px; height: 200px; background-color: #eeeeee;" mode="{{item.mode}}" src="{{src}}"></image>  
        

video

video标签认宽度300px、高度225px，设置宽高需要通过wxss设置width和height。

tip: 请勿在 scroll-view 中使用 video 组件

• hidden设置视频的显示/隐藏，hidden值为true表示隐藏，值为false表示显示
• src要播放视频的资源地址
• binderror当发生错误时触发error事件，event.detail = { errMsg: 'something wrong' }

            <video src="http://www.w3school.com.cn//i/movie.mp4" binderror="videoErrorCallback"></video>
             

地图map

map

tip: 请勿在 scroll-view 中使用 map 组件

• longitude中心经度
• latitude中心纬度
• scale缩放级别,默认1
• markers标记点
• covers覆盖物

标记点用于在地图上显示标记的位置，不能自定义图标和样式

• latitude纬度，浮点数，范围 -90 ~ 90
• longitude经度，浮点数，范围 -180 ~ 180
• name标注点名
• desc标注点详细描述

覆盖物用于在地图上显示自定义图标，可自定义图标和样式

地图组件的经纬度必填, 如果不填经纬度则默认值是北京的经纬度。标记点markers只能在初始化的时候设置，不支持动态更新。

• latitude纬度:浮点数，范围 -90 ~ 90
• longitude经度:浮点数，范围 -180 ~ 180
• iconPath显示的图标:项目目录下的图片路径，支持相对路径写法
• rotate旋转角度,顺时针旋转的角度，范围 0 ~ 360，默认为 0

        <map longitude="23.099994" latitude="113.324520" markers="{{markers}}" covers="{{covers}}" style=" 375px; height: 200px;"></map> 

        Page({
          data: {
            markers: [{
              latitude: 23.099994,
              longitude: 113.324520,
              name: 'T.I.T 创意园',
              desc: '我现在的位置'
            }],
            covers: [{
              latitude: 23.099794,
              longitude: 113.324520,
              icaonPath: '../images/car.png',
              rotate: 10
            }, {
              latitude: 23.099298,
              longitude: 113.324129,
              iconPath: '../images/car.png',
              rotate: 90
            }]
          }
        })
        

canvas

画布canvas

canvas标签默认宽度300px、高度225px. 同一页面中的canvas-id不可重复，如果使用一个已经出现过的canvas-id，该canvas标签对应的画布将被隐藏并不再正常工作

tip: 请勿在 scroll-view 中使用 canvas 组件

• hidden设置画布的显示/隐藏，hidden值为true表示隐藏，值为false表示显示,默认为false
• canvas-idcanvas组件的唯一标识符
• binderror 当发生错误时触发error事件，detail = { errMsg: 'something wrong' }

        <canvas style=" 300px; height: 200px;" canvas-id="firstCanvas" binderror="canvasIdErrorCallback" ></canvas>

        Page({
          canvasIdErrorCallback: function (e) {
            console.error(e.detail.errMsg);
          },
          onReady: function (e) {
        
            //使用wx.createContext获取绘图上下文context
            var context = wx.createContext();
        
            context.setStrokeStyle("#00ff00");
            context.setLineWidth(5);
            context.rect(0,0,200,200);
            context.stroke()
            context.setStrokeStyle ("#ff0000") ;
            context.setLineWidth (2)
            context.moveTo(160,100)
            context.arc(100,100,60,0,2*Math.PI,true);
            context.moveTo(140,100);
            context.arc(100,100,40,0,Math.PI,false);
            context.moveTo(85,80);
            context.arc(80,80,5,0,2*Math.PI,true);
            context.moveTo(125,80);
            context.arc(120,80,5,0,2*Math.PI,true);
            context.stroke();
        
            //调用wx.drawCanvas，通过canvasId指定在哪张画布上绘制，通过actions指定绘制行为
            wx.drawCanvas({
              canvasId: 'firstCanvas',
              actions: context.getActions() //获取绘图动作数组
            });
          }
        });
             

微信API请求

wx.request(OBJECT)

wx.request发起的是https请求。一个微信小程序，同时只能有5个网络请求连接。

• url开发者服务器接口地址,必填
• data请求的参数，否
• header设置请求的header , header中不能设置Referer，否
• method默认为GET，有效值：OPTIONS,GET,HEAD,POST,PUT,DELETE,TRACE,CONNECT，否
• success收到开发者服务成功返回的回调函数，res = {data:"开发者服务器返回的内容"}，否
• fail接口调用失败的回调函数，否
• complete接口调用结束的回调函数（调用成功、失败都会执行）,否

        wx.request({
          url: 'test.php',
          data: {
             x: '' ,
             y: ''
          },
          header:{
              "Content-Type":"application/json"
          },
          success: function(res) {
             var data = res.data;
          }
        });
            

API 上传、下载

将本地资源上传到开发者服务器。如页面通过 wx.chooseImage 等接口获取到一个本地资源的临时文件路径后，可通过此接口将本地资源上传到指定服务器。客户端发起一个HTTPS POST请求，其中 Content-Type 为 multipart/form-data 。

wx.uploadFile(OBJECT)

• url开发者服务器url，必填
• filePath要上传文件资源的路径，必填
• name文件对应的key , 开发者在服务器端通过这个key可以获取到文件二进制内容，必填
• headerHTTP 请求 Header，否
• formDataHTTP 请求中其他额外的form data，否
• success接口调用成功的回调函数，否
• fail接口调用失败的回调函数，否
• complete接口调用结束的回调函数（调用成功、失败都会执行），否

        wx.chooseImage({
          success:function(res){
            var tempFilePaths = res.tempFilePaths; 
            wx.uploadFile({
              url: 'http://example.com/upload',
              filePath: tempFilePaths[0],
              name:"file",
              formData:{
                "user":"test"
              }
            })
          }
        })
             

wx.downloadFile(OBJECT)

下载文件资源到本地。客户端直接发起一个HTTP GET请求，把下载到的资源根据 type 进行处理，并返回文件的本地临时路径。

• url下载资源的 url
• type下载资源的类型，用于客户端识别处理，有效值：image/audio/video
• headerHTTP 请求 Header
• success下载成功后以 tempFilePath 的形式传给页面，res={tempFilePath:"文件的临时路径"}
• fail接口调用失败的回调函数
• complete接口调用结束的回调函数（调用成功、失败都会执行）

        wx.downloadFile({
          url: 'http://example.com/audio/123',
          type: 'audio',
          success:function(res){
            wx.playVoice({
                filePath: res.tempFilePath
            })
          }
        })
             

创建Websocket

wx.connectSocket(OBJECT)

wx.onSocketOpen(CALLBACK)

wx.onSocketError(CALLBACK)

wx.sendSocketMessage(OBJECT)

wx.onSocketMessage(CALLBACK)

wx.closeSocket()

wx.onSocketClose(CALLBACK)

wx.connectSocket(OBJECT)

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

• url开发者服务器接口地址，必须是HTTPS协议，且域名必须是后台配置的合法域名
• data请求的数据
• headerHTTP Header
• method默认是GET，有效值为： OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT
• success接口调用成功的回调函数
• fail接口调用失败的回调函数
• complete接口调用结束的回调函数（调用成功、失败都会执行）

        wx.connectSocket({
          url:"test.php",
          data:{
            x:"",
            y:""
          },
          header:{ 
            'content-type': 'application/json'
          },
          method:"GET"
        })
        

wx.onSocketOpen(CALLBACK)

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

wx.onSocketError(CALLBACK)

        wx.connectSocket({
          url:"test.php"
        });
        wx.onSocketOpen(function(res){
          console.log("WebSocket连接已打开！")
        })
        wx.onSocketError(function(res){
          console.log("WebSocket连接打开失败，请检查！")
        })
        

wx.sendSocketMessage(OBJECT)

通过WebSocket连接发送数据，需要先wx.connectSocket，并在wx.onSocketOpen回调之后才能发送。

• data需要发送的内容

        var socketOpen = false;
        var socketMsgQueue = []
        wx.connectSocket({
          url:"test.php"
        });
        
        wx.onSocketOpen(function(res){
          socketOpen = true;
          for(var i = 0 ; i < socketMsgQueue.length; i++){
             sendSocketMessage(socketMsgQueue[i])
          }
          socketMsgQueue = [];
        })
        
        function sendSocketMessage(msg){
          if(socketOpen){
            wx.sendSocketMessage({
               data:msg
            });
          }else{
             socketMsgQueue.push(msg)
          }
        }
             

wx.onSocketMessage(CALLBACK)

• data服务器返回的消息

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

wx.onSocketError(CALLBACK)

        wx.connectSocket({
          url:"test.php"
        });
        wx.onSocketOpen(function(res){
          console.log("WebSocket连接已打开！")
        })
        wx.onSocketError(function(res){
          console.log("WebSocket连接打开失败，请检查！")
        })
             

wx.closeSocket()

关闭WebSocket连接

wx.onSocketClose(CALLBACK)

监听WebSocket关闭

        wx.connectSocket({
          url:"test.php"
        });
        
        //注意这里有时序问题，
        //如果wx.connectSocket还没回调wx.onSocketOpen,而先调用wx.closeSocket,那么就做不到关闭WebSocket的目的
        //必须在WebSocket打开期间调用wx.closeSocket才能关闭
        wx.onSocketOpen(function(){
          wx.closeSocket()
        })
        
        wx.onSocketClose(function(res){
          console.log("WebSocket 已关闭！")
        })
             

API图片

wx.chooseImage(OBJECT)

从本地相册选择图片或使用相机拍照

• count最多可以选择的图片张数，默认9，非必填
• sizeType"original"原图，"compressed"压缩图，默认二者都有,非必填
• sourceType"album"从相册选图，"camera"使用相机，默认二者都由,非必填
• success成功则返回图片的本地文件路径列表tempFilePaths，必填
• fail接口调用失败的回调函数
• complete接口调用结束的回调函数（调用成功、失败都会执行）

        wx.chooseImage({
            count: 1, // 默认9
            sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，默认二者都有
            sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
            success: function (res) {
                  // 返回选定照片的本地文件路径列表，tempFilePath可以作为img标签的src属性显示图片
                var tempFilePaths = res.tempFilePaths; 
            }
        });
             

wx.previewImage(OBJECT)

• current当前显示图片的链接，不填则默认为urls的第一张,非必填
• urls需要预览的图片链接列表
• success接口调用成功的回调函数
• fail接口调用失败的回调函数
• complete接口调用结束的回调函数（调用成功、失败都会执行）

        wx.previewImage({
            current: '', // 当前显示图片的http链接
            urls: [] // 需要预览的图片http链接列表
        });
             

数据

数据缓存

有自己的本地缓存，可以通过wx.setStorage（wx.setStorageSync）、wx.getStorage（wx.getStorageSync）、wx.clearStorage（wx.clearStorageSync）可以对本地缓存进行设置、获取和清理。localStorage是永久存储的，但是我们不建议将关键信息全部存在localStorage，以防用户换设备的情况。

wx.setStorage(OBJECT)

将数据存储在本地缓存中指定的key中，会覆盖掉原来该key对应的内容，这是一个异步接口。

• key：本地缓存中的指定的key
• data：需要存储的内容

        wx.setStorage({
        key:'key',
        data:'value'
        });
             

wx.setStorageSync(key,data)

将DATA存储在本地缓存中指定的KEY中，会覆盖掉原来该KEY对应的内容，这是一个同步接口。

• KEY:本地缓存中的指定的key
• DATA: 需要存储的内容

        wx.setStorageSync("key","value");
        

wx.getStorage(OBJECT)

从本地缓存中异步获取指定key对应的内容。

• key:本地缓存中的指定的key,必填字段
• success接口调用的回调函数,res={data:"key对应的内容"}，必填字段

        wx.getStorage({
          key:'key',
          success:function(res){
              console.log(res.data);
          } 
        });
             

wx.getStorageSync(KEY)

从本地缓存中同步获取指定key对应的内容。

• KEY:本地缓存中的指定的key，必填字段

        var value = wx.getStorageSync("key");
             

wx.clearStorage()

清理本地数据缓存

wx.clearStorageSync()

​同步清理本地数据缓存

        wx.clearStorage();
        wx.clearStorageSync();
             

当前位置、速度

wx.getLocation(OBJECT)

• type默认为"wgs84"返回gps坐标，"gcj02"返回可用于wx.openLocation的坐标，非必填
• success成功获取地理位置的回调，必填
• fail接口调用失败的回调函数，非必填
• complete接口调用结束的回调函数（调用成功、失败都会执行）,非必填