引言

目錄結(jié)構(gòu)

小程序包含一個描述整體程序的 app 和多個描述各自頁面的 page。

一個小程序主體部分由三個文件組成，必須放在項目的根目錄，如下：

一個小程序頁面由四個文件組成，分別是：

注意：為了方便開發(fā)者減少配置項，描述頁面的四個文件必須具有相同的路徑與文件名。

一、配置(.json)

1. 全局配置

小程序根目錄下的 app.json 文件用來對微信小程序進行全局配置，決定頁面文件的路徑、窗口表現(xiàn)、設(shè)置網(wǎng)絡(luò)超時時間、設(shè)置多 tab 等。

配置示例

以下是一個包含了部分常用配置選項的 app.json ：

{
  "pages": ["pages/index/index", "pages/logs/index"],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首頁"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志"
      }
    ]
  },
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 10000
  },
  "debug": true,
  "navigateToMiniProgramAppIdList": ["wxe5f52902cf4de896"]
}

app.json 配置項列表

pages

用于指定小程序由哪些頁面組成，每一項都對應(yīng)一個頁面的 路徑+文件名 信息。文件名不需要寫文件后綴，框架會自動去尋找對于位置的 .json, .js, .wxml, .wxss 四個文件進行處理。

數(shù)組的第一項代表小程序的初始頁面（首頁）。小程序中新增/減少頁面，都需要對 pages 數(shù)組進行修改。

如開發(fā)目錄為：

├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils

則需要在 app.json 中寫

{
  "pages": ["pages/index/index", "pages/logs/logs"]
}

window

用于設(shè)置小程序的狀態(tài)欄、導(dǎo)航條、標題、窗口背景色。

• 注1：HexColor（十六進制顏色值），如"#ff00ff"
• 注2：關(guān)于navigationStyle
  • 客戶端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。
  • 客戶端 6.7.2 版本開始，navigationStyle: custom 對 <web-view> 組件無效
  • 開啟 custom 后，低版本客戶端需要做好兼容。開發(fā)者工具基礎(chǔ)庫版本切到 1.7.0（不代表最低版本，只供調(diào)試用）可方便切到舊視覺

如 app.json ：

{
  "window": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "微信接口功能演示",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
  }
}

tabBar

如果小程序是一個多 tab 應(yīng)用（客戶端窗口的底部或頂部有 tab 欄可以切換頁面），可以通過 tabBar 配置項指定 tab 欄的表現(xiàn)，以及 tab 切換時顯示的對應(yīng)頁面。

其中 list 接受一個數(shù)組，只能配置最少2個、最多5個 tab。tab 按數(shù)組的順序排序，每個項都是一個對象，其屬性值如下：

networkTimeout

各類網(wǎng)絡(luò)請求的超時時間，單位均為毫秒。

debug

可以在開發(fā)者工具中開啟 debug 模式，在開發(fā)者工具的控制臺面板，調(diào)試信息以 info 的形式給出，其信息有Page的注冊，頁面路由，數(shù)據(jù)更新，事件觸發(fā)等?？梢詭椭_發(fā)者快速定位一些常見的問題。

functionalPages

啟用插件功能頁時，插件所有者小程序需要設(shè)置其 functionalPages 為 true。

subpackages

微信客戶端 6.6.0 ，基礎(chǔ)庫 1.7.3 及以上版本支持

啟用分包加載時，聲明項目分包結(jié)構(gòu)。

寫成 subPackages 也支持。

workers

基礎(chǔ)庫 1.9.90 開始支持，低版本需做兼容處理。

使用 Worker 處理多線程任務(wù)時，設(shè)置 Worker 代碼放置的目錄

requiredBackgroundModes

微信客戶端 6.7.2 及以上版本支持

申明需要后臺運行的能力，類型為數(shù)組。目前支持以下項目：

• audio: 后臺音樂播放
  如：

{
  "pages": ["pages/index/index"],
  "requiredBackgroundModes": ["audio"]
}

注：在此處申明了后臺運行的接口，開發(fā)版和體驗版上可以直接生效，正式版還需通過審核。

plugins

基礎(chǔ)庫 1.9.6 開始支持，低版本需做兼容處理。

聲明小程序需要使用的插件。

preloadRule

基礎(chǔ)庫 2.3.0 開始支持，低版本需做兼容處理。

聲明分包預(yù)下載的規(guī)則。

resizable

基礎(chǔ)庫 2.3.0 開始支持，低版本需做兼容處理。

在 iPad 上運行的小程序可以設(shè)置支持屏幕旋轉(zhuǎn)。

navigateToMiniProgramAppIdList

基礎(chǔ)庫 2.4.0 開始支持，低版本需做兼容處理。

當小程序需要使用 wx.navigateToMiniProgram 接口跳轉(zhuǎn)到其他小程序時，需要先在配置文件中聲明需要跳轉(zhuǎn)的小程序 appId 列表，最多允許填寫 10 個。

usingComponents

開發(fā)者工具 1.02.1810190 及以上版本支持

在此處聲明的自定義組件視為全局自定義組件，在小程序內(nèi)的頁面或自定義組件中可以直接使用而無需再聲明。

permission

微信客戶端 7.0.0 及以上版本支持

小程序接口權(quán)限相關(guān)設(shè)置。字段類型為 Object，結(jié)構(gòu)為：

PermissionObject 結(jié)構(gòu)

如：

{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息將用于小程序位置接口的效果展示"
    }
  }
}

2. 頁面配置

每一個小程序頁面也可以使用.json文件來對本頁面的窗口表現(xiàn)進行配置。

頁面的配置只能設(shè)置app.json 中部分 window 配置項的內(nèi)容，頁面中配置項會覆蓋 app.json 的 window中相同的配置項。

配置示例

{
  "navigationBarBackgroundColor": "#ffffff",
  "navigationBarTextStyle": "black",
  "navigationBarTitleText": "微信接口功能演示",
  "backgroundColor": "#eeeeee",
  "backgroundTextStyle": "light"
}

頁面配置項列表

頁面的.json只能設(shè)置 window 相關(guān)的配置項，以決定本頁面的窗口表現(xiàn)，所以無需寫 window 這個屬性。

二、邏輯層 App Service(.js)

小程序開發(fā)框架的邏輯層使用 JavaScript 引擎為小程序提供開發(fā)者 JavaScript 代碼的運行環(huán)境以及微信小程序的特有功能。

邏輯層將數(shù)據(jù)進行處理后發(fā)送給視圖層，同時接受視圖層的事件反饋。

開發(fā)者寫的所有代碼最終將會打包成一份 JavaScript 文件，并在小程序啟動的時候運行，直到小程序銷毀。這一行為類似 ServiceWorker，所以邏輯層也稱之為 App Service。

在 JavaScript 的基礎(chǔ)上，我們增加了一些功能，以方便小程序的開發(fā)：

• 增加 App 和 Page 方法，進行程序和頁面的注冊。
• 增加 getApp 和 getCurrentPages 方法，分別用來獲取 App 實例和當前頁面棧。
• 提供豐富的 API，如微信用戶數(shù)據(jù)，掃一掃，支付等微信特有能力。
• 每個頁面有獨立的作用域，并提供模塊化能力。

注意：小程序框架的邏輯層并非運行在瀏覽器中，因此 JavaScript 在 web 中一些能力都無法使用，如 window，document 等。

1. 小程序 App

App(Object)

App() 函數(shù)用來注冊一個小程序。接受一個 Object 參數(shù)，其指定小程序的生命周期回調(diào)等。

App() 必須在 app.js 中調(diào)用，必須調(diào)用且只能調(diào)用一次。不然會出現(xiàn)無法預(yù)期的后果。

Object 參數(shù)說明：

前臺、后臺定義： 當用戶點擊左上角關(guān)閉，或者按了設(shè)備 Home 鍵離開微信，小程序并沒有直接銷毀，而是進入了后臺；當再次進入微信或再次打開小程序，又會從后臺進入前臺。

需要注意的是：只有當小程序進入后臺一定時間，或者系統(tǒng)資源占用過高，才會被真正的銷毀。

關(guān)閉小程序（基礎(chǔ)庫版本1.1.0開始支持）： 當用戶從掃一掃、轉(zhuǎn)發(fā)等入口（場景值為1007, 1008, 1011, 1025）進入小程序，且沒有置頂小程序的情況下退出，小程序會被銷毀。

小程序運行機制在基礎(chǔ)庫版本 1.4.0 有所改變： 上一條關(guān)閉邏輯在新版本已不適用。詳情

示例代碼：

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

onLaunch(Object)

小程序初始化完成時觸發(fā)，全局只觸發(fā)一次。參數(shù)也可以使用 wx.getLaunchOptionsSync 獲取。

參數(shù)說明：

與 wx.getLaunchOptionsSync 一致

onShow(Object)

小程序啟動，或從后臺進入前臺顯示時觸發(fā)。也可以使用 wx.onAppShow 綁定監(jiān)聽。

參數(shù)說明：

與 wx.onAppShow 一致

onHide()

小程序從前臺進入后臺時觸發(fā)。也可以使用 wx.onAppHide 綁定監(jiān)聽。

onError(String error)

小程序發(fā)生腳本錯誤或 API 調(diào)用報錯時觸發(fā)。也可以使用 wx.onError 綁定監(jiān)聽。

參數(shù)說明

與 wx.onError 一致

onPageNotFound(Object)

基礎(chǔ)庫 1.9.90 開始支持，低版本需做兼容處理。

小程序要打開的頁面不存在時觸發(fā)。也可以使用 wx.onPageNotFound 綁定監(jiān)聽。注意事項請參考 wx.onPageNotFound。

參數(shù)說明：

與 wx.onPageNotFound 一致

示例代碼：

App({
  onPageNotFound(res) {
    wx.redirectTo({
      url: 'pages/...'
    }) // 如果是 tabbar 頁面，請使用 wx.switchTab
  }
})

getApp(Object)

全局的 getApp() 函數(shù)可以用來獲取到小程序 App 實例。

Object 參數(shù)說明：

示例代碼：

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

注意：

• 不要在定義于 App() 內(nèi)的函數(shù)中調(diào)用 getApp() ，使用 this 就可以拿到 app 實例。
• 通過 getApp() 獲取實例之后，不要私自調(diào)用生命周期函數(shù)。

2. 場景值

• 對于小程序，可以在 App 的 onLaunch 和 onShow，或wx.getLaunchOptionsSync 中獲取上述場景值。
• 對于小游戲，可以在 wx.getLaunchOptionsSync 和 wx.onShow 中獲取上述場景值

部分場景值下還可以獲取來源應(yīng)用、公眾號或小程序的appId。

Tip: 由于Android系統(tǒng)限制，目前還無法獲取到按 Home 鍵退出到桌面，然后從桌面再次進小程序的場景值，對于這種情況，會保留上一次的場景值。

3. 頁面 Page

Page(Object) 構(gòu)造器

Page(Object) 函數(shù)用來注冊一個頁面。接受一個 Object 類型參數(shù)，其指定頁面的初始數(shù)據(jù)、生命周期回調(diào)、事件處理函數(shù)等。

Object 參數(shù)說明：

示例代碼：

// index.js
Page({
  data: {
    text: 'This is page data.'
  },
  onLoad(options) {
    // Do some initialize when page load.
  },
  onReady() {
    // Do something when page ready.
  },
  onShow() {
    // Do something when page show.
  },
  onHide() {
    // Do something when page hide.
  },
  onUnload() {
    // Do something when page close.
  },
  onPullDownRefresh() {
    // Do something when pull down.
  },
  onReachBottom() {
    // Do something when page reach bottom.
  },
  onShareAppMessage() {
    // return custom share data when user share.
  },
  onPageScroll() {
    // Do something when page scroll
  },
  onResize() {
    // Do something when page resize
  },
  onTabItemTap(item) {
    console.log(item.index)
    console.log(item.pagePath)
    console.log(item.text)
  },
  // Event handler.
  viewTap() {
    this.setData({
      text: 'Set some data for updating view.'
    }, function () {
      // this is setData callback
    })
  },
  customData: {
    hi: 'MINA'
  }
})

除了 Page ，作為高級用法，頁面可以像自定義組件一樣使用 Component 來創(chuàng)建，這樣就可以使用自定義組件的特性，如 behaviors 等。具體細節(jié)請閱讀 Component 構(gòu)造器 章節(jié)。

data

data 是頁面第一次渲染使用的初始數(shù)據(jù)。

頁面加載時，data 將會以JSON字符串的形式由邏輯層傳至渲染層，因此data中的數(shù)據(jù)必須是可以轉(zhuǎn)成JSON的類型：字符串，數(shù)字，布爾值，對象，數(shù)組。

渲染層可以通過 WXML 對數(shù)據(jù)進行綁定。

示例代碼：

在開發(fā)者工具中預(yù)覽效果

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

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

生命周期回調(diào)函數(shù)

生命周期的觸發(fā)以及頁面的路由方式詳見

onLoad(Object query)

頁面加載時觸發(fā)。一個頁面只會調(diào)用一次，可以在 onLoad 的參數(shù)中獲取打開當前頁面路徑中的參數(shù)。

參數(shù)說明

onShow()

頁面顯示/切入前臺時觸發(fā)。

onReady()

頁面初次渲染完成時觸發(fā)。一個頁面只會調(diào)用一次，代表頁面已經(jīng)準備妥當，可以和視圖層進行交互。

注意：對界面內(nèi)容進行設(shè)置的 API 如wx.setNavigationBarTitle，請在onReady之后進行。詳見生命周期

onHide()

頁面隱藏/切入后臺時觸發(fā)。 如 navigateTo 或底部 tab 切換到其他頁面，小程序切入后臺等。

onUnload()

頁面卸載時觸發(fā)。如redirectTo或navigateBack到其他頁面時。

頁面事件處理函數(shù)

onPullDownRefresh()

監(jiān)聽用戶下拉刷新事件。

• 需要在app.json的window選項中或頁面配置中開啟enablePullDownRefresh。
• 可以通過wx.startPullDownRefresh觸發(fā)下拉刷新，調(diào)用后觸發(fā)下拉刷新動畫，效果與用戶手動下拉刷新一致。
• 當處理完數(shù)據(jù)刷新后，wx.stopPullDownRefresh可以停止當前頁面的下拉刷新。

onReachBottom()

監(jiān)聽用戶上拉觸底事件。

• 可以在app.json的window選項中或頁面配置中設(shè)置觸發(fā)距離onReachBottomDistance。
• 在觸發(fā)距離內(nèi)滑動期間，本事件只會被觸發(fā)一次。

onPageScroll(Object)

監(jiān)聽用戶滑動頁面事件。

Object 參數(shù)說明：

注意：請只在需要的時候才在 page 中定義此方法，不要定義空方法。以減少不必要的事件派發(fā)對渲染層-邏輯層通信的影響。 注意：請避免在 onPageScroll 中過于頻繁的執(zhí)行 setData 等引起邏輯層-渲染層通信的操作。尤其是每次傳輸大量數(shù)據(jù)，會影響通信耗時。

onShareAppMessage(Object)

監(jiān)聽用戶點擊頁面內(nèi)轉(zhuǎn)發(fā)按鈕（<button> 組件 open-type="share"）或右上角菜單“轉(zhuǎn)發(fā)”按鈕的行為，并自定義轉(zhuǎn)發(fā)內(nèi)容。

注意：只有定義了此事件處理函數(shù)，右上角菜單才會顯示“轉(zhuǎn)發(fā)”按鈕

Object 參數(shù)說明：

此事件需要 return 一個 Object，用于自定義轉(zhuǎn)發(fā)內(nèi)容，返回內(nèi)容如下：

自定義轉(zhuǎn)發(fā)內(nèi)容

示例代碼

在開發(fā)者工具中預(yù)覽效果

Page({
  onShareAppMessage(res) {
    if (res.from === 'button') {
      // 來自頁面內(nèi)轉(zhuǎn)發(fā)按鈕
      console.log(res.target)
    }
    return {
      title: '自定義轉(zhuǎn)發(fā)標題',
      path: '/page/user?id=123'
    }
  }
})

onResize(object)

基礎(chǔ)庫 2.4.0 開始支持，低版本需做兼容處理。

小程序屏幕旋轉(zhuǎn)時觸發(fā)。詳見 響應(yīng)顯示區(qū)域變化

onTabItemTap(Object)

基礎(chǔ)庫 1.9.0 開始支持，低版本需做兼容處理。

點擊 tab 時觸發(fā)

Object 參數(shù)說明：

示例代碼：

Page({
  onTabItemTap(item) {
    console.log(item.index)
    console.log(item.pagePath)
    console.log(item.text)
  }
})

組件事件處理函數(shù)

Page 中還可以定義組件事件處理函數(shù)。在渲染層的組件中加入事件綁定，當事件被觸發(fā)時，就會執(zhí)行 Page 中定義的事件處理函數(shù)。

示例代碼：

在開發(fā)者工具中預(yù)覽效果

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

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

Page.route

基礎(chǔ)庫 1.2.0 開始支持，低版本需做兼容處理。

到當前頁面的路徑，類型為String。

Page({
  onShow() {
    console.log(this.route)
  }
})

Page.prototype.setData(Object data, Function callback)

setData 函數(shù)用于將數(shù)據(jù)從邏輯層發(fā)送到視圖層（異步），同時改變對應(yīng)的 this.data 的值（同步）。

參數(shù)說明

Object 以 key: value 的形式表示，將 this.data 中的 key 對應(yīng)的值改變成 value。

其中 key 可以以數(shù)據(jù)路徑的形式給出，支持改變數(shù)組中的某一項或?qū)ο蟮哪硞€屬性，如 array[2].message，a.b.c.d，并且不需要在 this.data 中預(yù)先定義。

注意：

1. 直接修改 this.data 而不調(diào)用 this.setData 是無法改變頁面的狀態(tài)的，還會造成數(shù)據(jù)不一致。
2. 僅支持設(shè)置可 JSON 化的數(shù)據(jù)。
3. 單次設(shè)置的數(shù)據(jù)不能超過1024kB，請盡量避免一次設(shè)置過多的數(shù)據(jù)。
4. 請不要把 data 中任何一項的 value 設(shè)為 undefined ，否則這一項將不被設(shè)置并可能遺留一些潛在問題。

示例代碼：

在開發(fā)者工具中預(yù)覽效果

<!--index.wxml-->
<view>{{text}}</view>
<button bindtap="changeText">Change normal data</button>
<view>{{num}}</view>
<button bindtap="changeNum">Change normal num</button>
<view>{{array[0].text}}</view>
<button bindtap="changeItemInArray">Change Array data</button>
<view>{{object.text}}</view>
<button bindtap="changeItemInObject">Change Object data</button>
<view>{{newField.text}}</view>
<button bindtap="addNewField">Add new data</button>

// index.js
Page({
  data: {
    text: 'init data',
    num: 0,
    array: [{text: 'init data'}],
    object: {
      text: 'init data'
    }
  },
  changeText() {
    // this.data.text = 'changed data' // 不要直接修改 this.data
    // 應(yīng)該使用 setData
    this.setData({
      text: 'changed data'
    })
  },
  changeNum() {
    // 或者，可以修改 this.data 之后馬上用 setData 設(shè)置一下修改了的字段
    this.data.num = 1
    this.setData({
      num: this.data.num
    })
  },
  changeItemInArray() {
    // 對于對象或數(shù)組字段，可以直接修改一個其下的子字段，這樣做通常比修改整個對象或數(shù)組更好
    this.setData({
      'array[0].text': 'changed data'
    })
  },
  changeItemInObject() {
    this.setData({
      'object.text': 'changed data'
    })
  },
  addNewField() {
    this.setData({
      'newField.text': 'new data'
    })
  }
})

生命周期

以下內(nèi)容你不需要立馬完全弄明白，不過以后它會有幫助。

下圖說明了 Page 實例的生命周期。