20180925-小程序学习笔记(从文档入门)

20180925-小程序学习笔记(从文档入门)

created @ 2018.9.25
completed @ 2018.9.28

★小程序的框架

小程序包含一个描述整体程序的 app 和多个描述各自页面的 page。
框架的核心是一个响应的数据绑定系统。
整个小程序框架系统分为两部分：视图层（View）和逻辑层（App Service）

小程序目录结构：

//一个小程序主体部分由三个文件组成，必须放在项目的根目录
├── app.js //小程序逻辑
├── app.json //小程序公共配置
├── app.wxss //小程序公共样式表
├── pages
│ │── index //一个小程序页面由四个文件组成
│ │ ├── index.wxml // 页面结构
│ │ ├── index.js //页面逻辑
│ │ ├── index.json //页面配置(非必需)
│ │ └── index.wxss //页面样式表(非必需)
│ └── logs
│ ├── logs.wxml
│ └── logs.js
└── utils

★小程序的配置

app.json的常用配置项

P.S. json文件不支持注释，以下代码为伪代码。

{
  "pages": [
    "pages/idx/idx",
    "pages/test/test",
    "pages/simplecalc/simplecalc"
  ],
  "window": {
    //导航栏
    "navigationBarBackgroundColor": "#fff", //导航栏背景颜色
    "navigationBarTextStyle": "black", //导航栏标题颜色
    "navigationBarTitleText": "烟语财悟工具箱-测试环境", //导航栏标题文字内容
    //窗口背景
    "backgroundTextStyle": "light", //下拉 loading 的样式，仅支持 dark / light
    //其他设置
    "enablePullDownRefresh": false //是否全局开启下拉刷新
  },
  "tabBar": {
    //tabbar样式
    "color": "#0ff", //tab 上的文字默认颜色
    "selectedcolor": "#f00", //tab 上的文字选中时的颜色
    "backgroundColor": "#fff", //tab 的背景色
    "borderStyle": "black", //tabbar上边框的颜色， 仅支持 black / white
    "position": "bottom", //tabBar的位置，仅支持 bottom / top
    //tabbar内容
    "list": [ //tab 的列表，最少2个、最多5个 tab
      {
        "pagePath": "pages/test/test",
        "text": "测试"
      },
      {
        "pagePath": "pages/simplecalc/simplecalc",
        "text": "计算器"
      }
    ]
  }
}

需要注意的是，pages数组的第一项必须是tabBar的list数组的一员，否则tabbar不会显示。

page中的.json配置项

与app.json类似，page当中的.json配置项，主要对导航栏、窗口背景进行设置。
导航栏：navigationBarBackgroundColor, navigationBarTextStyle, navigationBarTitleText.
窗口：backgroundColor, backgroundTextStyle.

相比app.json，page当中的.json特有的配置项为：
disableScroll：设置为 true 则页面整体不能上下滚动；只在页面配置中有效，无法在 app.json 中设置该项。

★小程序的逻辑层

逻辑层使用JavaScript引擎为小程序提供开发者JavaScript代码的运行环境和特有功能。
开发者的所有代码最终打包成一份JavaScript文件，并在小程序启动时候运行，直到小程序销毁（小程序的销毁自有判断）。
P.S. 当用户点击左上角关闭，或者按了设备 Home 键离开微信，小程序并没有直接销毁，而是进入了后台；当再次进入微信或再次打开小程序，又会从后台进入前台。需要注意的是：只有当小程序进入后台一定时间，或者系统资源占用过高，才会被真正的销毁。

小程序的JavaScript：

1. 增加了App和Page方法，没有window和document对象。
2. 增加了getApp和getCurrentPages方法，用来获取当前App实例和当前页面栈。

App(Object)

App() 函数用来注册一个小程序。接受一个 Object 参数，其指定小程序的生命周期回调等。
App() 必须在 app.js 中调用，必须调用且只能调用一次。

App({
  onLaunch: function(options) {
    // 小程序初始化完成时（全局只触发一次）
  },
  onShow: function(options) {
    // 小程序启动，或从后台进入前台显示时
  },
  onHide: function() {
    // 小程序从前台进入后台时
  },
  onError: function(msg) {
    // 小程序发生脚本错误，或者 api 调用失败时触发，会带上错误信息
    console.log(msg)
  },
 onPageNotFound: function(msg) {
    // 小程序要打开的页面不存在时触发，会带上页面信息回调该函数
    console.log(msg)
  },
  // 开发者可以添加任意的函数或数据到 Object 参数中，用 this 可以访问
  globalData: 'I am global data'
})

getApp(Object)

不要在定义于 App() 内的函数中调用 getApp() ，使用 this 就可以拿到 app 实例。

Page(Object)

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

//index.js
Page({
  data: { 
    //页面的初始数据，Object数据类型
    //页面加载时，data 将会以JSON字符串的形式由逻辑层传至渲染层，因此data中的数据必须是可以转成JSON的类型：字符串，数字，布尔值，对象，数组。
    text: "This is page data."
  },
  onLoad: function(query) {
    // 页面加载时触发。一个页面只会调用一次，可以在 onLoad 的参数中获取打开当前页面路径中的参数。
    // query，Object类型，打开当前页面路径中的参数。
  },
  onReady: function() {
    // 页面初次渲染完成时触发。一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。
  },
  onShow: function() {
    // 页面显示/切入前台时触发。
  },
  onHide: function() {
    // 页面隐藏/切入后台时触发。 如 navigateTo 或底部 tab 切换到其他页面，小程序切入后台等。
  },
  onUnload: function() {
    // 页面卸载时触发。如redirectTo或navigateBack到其他页面时。
  },
  onPullDownRefresh: function() {
    // 监听用户下拉刷新事件。
    // 需要在app.json的window选项中或页面配置中开启enablePullDownRefresh。
  },
  onReachBottom: function() {
    // 监听用户上拉触底事件。
    // 可以在app.json的window选项中或页面配置中设置触发距离onReachBottomDistance。
  },
  onShareAppMessage: function () {
    // 监听用户点击页面内转发按钮（ 组件 open-type="share"）或右上角菜单“转发”按钮的行为，并自定义转发内容。
  },
  onPageScroll: function() {
    // 监听用户滑动页面事件。
  },
  onTabItemTap(item) {
    // 点击 tab 时触发
    console.log(item.index)
    console.log(item.pagePath)
    console.log(item.text)
  },
  // Event handler.
  viewTap: function() {
    this.setData({
      text: 'Set some data for updating view.'
    }, function() {
      // this is setData callback
    })
  },
  customData: {
    hi: 'MINA'
  }
})

组件事件处理函数

Page 中还可以定义组件事件处理函数。

返回路由 - Page.route

到当前页面的路径，类型为String。

修改data - Page.prototype.setData(Object data, Function callback)

setData 函数用于将数据从逻辑层发送到视图层（异步），同时改变对应的 this.data 的值（同步）。
Object 以 key: value 的形式表示，将 this.data 中的 key 对应的值改变成 value。
直接修改 this.data 而不调用 this.setData 是无法改变页面的状态的，还会造成数据不一致。

路由

在小程序中所有页面的路由全部由框架进行管理。
框架以栈的形式维护了当前的所有页面。
getCurrentPages() 函数用于获取当前页面栈的实例，以数组形式按栈的顺序给出，第一个元素为首页，最后一个元素为当前页面。

模块

可以将一些公共的代码抽离成为一个单独的 js 文件，作为一个模块。模块只有通过 module.exports 或者 exports 才能对外暴露接口。

exports 是 module.exports 的一个引用，因此在模块里边随意更改 exports 的指向会造成未知的错误。所以更推荐开发者采用 module.exports 来暴露模块接口。
小程序目前不支持直接引入 node_modules , 开发者需要使用到 node_modules 时候建议拷贝出相关的代码到小程序的目录中或者使用小程序支持的 npm 功能。

在需要使用这些模块的文件中，使用 require(path) 将公共代码引入。
require 暂时不支持绝对路径。

API规范

1. 事件监听 API： 我们约定，以 on 开头的 API 用来监听某个事件是否触发，如：wx.onSocketOpen，wx.onCompassChange 等。
   这类 API 接受一个回调函数作为参数，当事件触发时会调用这个回调函数，并将相关数据以参数形式传入。
2. 同步 API：我们约定，以 Sync 结尾的 API 都是同步 API， 如 wx.setStorageSync，wx.getSystemInfoSync 等。此外，也有一些其他的同步 API，如 wx.createWorker，wx.getBackgroundAudioManager 等，详情参见 API 文档中的说明。
   同步 API 的执行结果可以通过函数返回值直接获取，如果执行出错会抛出异常。
3. 异步 API：大多数 API 都是异步 API，如 wx.request，wx.login 等。这类 API 接口通常都接受一个 Object 类型的参数，这个参数都支持按需指定以下字段来接收接口调用结果：

success, function, 接口调用成功的回调函数
fail, function, 接口调用失败的回调函数
complete, function, 接口调用结束的回调函数（调用成功、失败都会执行）
其他  Any -   接口定义的其他参数

★小程序视图层

框架的视图层由 WXML 与 WXSS 编写，由组件来进行展示。
WXML(WeiXin Markup language) 用于描述页面的结构。
WXS(WeiXin Script) 是小程序的一套脚本语言，结合 WXML，可以构建出页面的结构。
WXSS(WeiXin Style Sheet) 用于描述页面的样式。
组件(Component)是视图的基本组成单元。

WXML

数据绑定：WXML 中的动态数据均来自对应 Page 的 data。数据绑定使用 Mustache 语法（双大括号）将变量包起来。
列表渲染：wx:for
条件渲染：wx:if
模版：定义模板，使用 name 属性，作为模板的名字。然后在