支付寶小程式代碼結構及組成 （二）

本章内容出自《小程式開發不求人》電子書， 點選下載下傳完整版

支付寶小程式代碼結構及組成

小程式全局結構

概述

App() 代表頂層應用，管理所有頁面和全局資料，以及提供生命周期回調等。它也是一個構造方法，生成 App 執行個體。

一個小程式就是一個 App 執行個體。

每個小程式頂層一般包含三個檔案。

• app.json：應用配置
• app.js：應用邏輯
• app.acss：應用樣式（可選）

簡單示例

一個簡單的 app.json 代碼如下：

{
 "pages": [
 "pages/index/index",
 "pages/logs/logs"
 ],
 "window": {
 "defaultTitle": "Demo"
 }
}           

這段代碼配置指定小程式包含兩個頁面（index 和 logs），以及應用視窗的預設标題設定為 “Demo”。

一個簡單的 app.js 代碼如下：

App({
 onLaunch(options) {
 // 第一次打開
 },
 onShow(options) {
 // 小程式啟動，或從背景被重新打開
 },
 onHide() {
 // 小程式從前台進入背景
 },
 onError(msg) {
 // 小程式發生腳本錯誤或 API 調用出現報錯
 console.log(msg);
 },
 globalData: {
 // 全局資料
 name: 'alipay',
 },
});           

app.json 全局配置

app.json 用于對小程式進行全局配置，設定頁面檔案的路徑、視窗表現、多 tab等。

以下是一個基本配置示例：

{
 "pages": [
 "pages/index/index",
 "pages/logs/index"
 ],
 "window": {
 "defaultTitle": "Demo"
 }
}           

完整配置項如下：

pages

app.json 中的 pages 為數組屬性，數組中每一項都是字元串，用于指定小程式的頁面。在小程式中新增或删除頁面，都需要對 pages 數組進行修改。

pages 數組的每一項代表對應頁面的路徑資訊，其中，第一項代表小程式的首頁。

頁面路徑不需要寫任何字尾，架構會自動去加載同名的 .json、.js、.axml、.acss檔案。舉例來說，如果開發目錄為：

├── pages
│ ├──index
│ │ ├── index.json
│ │ ├── index.js
│ │ ├── index.axml
│ │ └── index.acss
│ ├──logs
│ │ ├── logs.json
│ │ ├── logs.js
│ │ └── logs.axml
├── app.json
├── app.js
└── app.acss           

app.json 中應當如下配置：

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

window

window 用于設定小程式的狀态欄、導覽列、标題、視窗背景色等。

示例代碼：

{
 "window":{
 "defaultTitle": "支付寶接口功能示範"
 }
}           

屬性	類型	是否必填	描述	最低版本
defaultTitle	String	否	頁面預設标題	-
pullRefresh			是否允許下拉重新整理。預設NO, 備注：下拉重新整理生效的前提是allowsBounceVertical 值為 YES
allowsBounceVertical			是否允許向下拉拽。預設YES, 支援 YES / NO
transparentTitle			導航欄透明設定。預設none，支援 always 一直透明 / auto 滑動自适應 /none 不透明
titlePenetrate			是否允許導航欄點選穿透。預設 NO，支援 YES / NO
showTitleLoading			是否進入時顯示導航欄的loading。預設 NO，支援YES / NO
titleImage			導航欄圖檔位址
titleBarColor	HexColor		導航欄背景色，十六進制顔色值（0-255）
backgroundColor			頁面的背景色，十六進制顔色值（0-255）
backgroundImageColor			下拉露出顯示的背景圖底色，十六進制顔色值（0-255）
backgroundImageUrl			下拉露出顯示的背景圖連結
gestureBack			iOS 用，是否支援手勢傳回。預設 NO，支援 YES /NO
enableScrollBar	Boolean		Android 用，是否顯示WebView 滾動條。預設YES，支援 YES / NO
onReachBottomDistance	Number		頁面上拉觸底時觸發時距離頁面底部的距離，機關為px。相關文檔 頁面事件處理函數	1.19.0 ，目前iOS 在page.json 下設定無效，隻能全局設定。

tabBar

如果你的小程式是一個多 tab 應用（用戶端視窗的底部欄可以切換頁面），那麼可以通過 tabBar 配置項指定 tab 欄的表現，以及 tab 切換時顯示的對應頁面。

注意：

• 通過頁面跳轉（ my.navigateTo ）或者頁面重定向（ my.redirectTo ）所到達的頁面，即使它是定義在 tabBar 配置中的頁面，也不會顯示底部的 tab 欄。
• tabBar 的第一個頁面必須是首頁。

tabBar 配置項有以下：

每個 item 配置：

icon 圖示推薦大小為 60×60 px 大小，系統會對傳入的非推薦尺寸的圖檔進行非等比拉伸或縮放。

{
 "tabBar": {
 "textColor": "#dddddd",
 "selectedColor": "#49a9ee",
 "backgroundColor": "#ffffff",
 "items": [
 {
 "pagePath": "pages/index/index",
 "name": "首頁"
 },
 {
 "pagePath": "pages/logs/logs",
 "name": "日志"
 }
 ]
 }
}           

app.acss 全局樣式

app.acss 作為全局樣式，作用于目前小程式的所有頁面。

ACSS 是一套樣式語言，用于描述 AXML 的元件樣式，決定 AXML 的元件的顯示效果。

為适應廣大前端開發者，ACSS 和 CSS 規則完全一緻，100% 可以用。同時為更适合開發小程式，對 CSS 進行了擴充。

ACSS 支援 px，rpx，vh，vw 等機關。

rpx

rpx（responsive pixel）可以根據螢幕寬度進行自适應，規定螢幕寬為750rpx。以 Apple iPhone6 為例，螢幕寬度為 375px，共有 750 個實體像素，則 750rpx = 375px = 750 實體像素，1rpx = 0.5px = 1 實體像素。

樣式導入

使用 @import 語句可以導入外聯樣式表，@import 後需要加上外聯樣式表相對路徑，用;表示結束。

/** button.acss **/
.sm-button {
 padding: 5px;
}           

/** app.acss **/
@import "./button.acss";
.md-button {
 padding: 15px;
}           

導入路徑支援從 node_modules 目錄載入第三方子產品，例如 page.acss:

@import "./button.acss"; /*相對路徑*/
@import "/button.acss"; /*項目絕對路徑*/
@import "third-party/page.acss"; /*第三方 npm 包路徑*/           

内聯樣式

元件上支援使用 style、class 屬性來控制樣式。

style 屬性

用于接收動态樣式，樣式在運作時會進行解析。行内樣式不支援!important 優先級規則。

<view style="color:{{color}};" />           

class 屬性

用于接收靜态樣式，屬性值是樣式規則中類選擇器名（樣式類名）的集合，樣式類名不需要帶上.，多個類名間以空格分隔。請靜态樣式寫進 class 中，避免将靜态樣式寫進 style 中，以免影響渲染速度。

<view class="my-awesome-view" />           

選擇器

同 CSS3 保持一緻。

• .a-, .am- 開頭的類選擇器為系統元件占用，不可使用。
• 不支援屬性選擇器。

全局樣式與局部樣式

• app.acss 中的樣式為全局樣式，作用于每一個頁面。
• 頁面檔案夾内的 .acss 檔案中定義的樣式為局部樣式，隻作用在對應的頁面，并會覆寫app.acss 中相同的選擇器。

本地資源引用

ACSS 檔案裡的本地資源引用請使用絕對路徑的方式，不支援相對路徑引用。例如：

/* 支援 */
background-image: url('/images/ant.png');
/* 不支援 */
background-image: url('./images/ant.png');           

app.js 注冊小程式

App(object: Object)

App() 用于注冊小程式，接受一個 Object 作為屬性，用來配置小程式的生命周期等。

App() 必須在 app.js 中調用，必須調用且隻能調用一次。

object 屬性說明

前台/背景定義：

• 小程式使用者點選右上角關閉，或者按下裝置 Home 鍵離開支付寶時，小程式并不會直接銷毀，而是進入背景。
• 當使用者再次進入支付寶或再次打開小程式時，小程式會從背景進入前台。
• 隻有當小程式進入背景 5 分鐘後，或占用系統資源過高，才會被真正銷毀。

onLaunch(object: Object) 及 onShow(object: Object)

object 屬性說明：

query	Object	目前小程式的 query，從啟動參數的 query字段解析而來
scene	number	啟動小程式的 場景值
path	string	目前小程式的頁面位址，從啟動參數 page字段解析而來，page 忽略時預設為首頁
referrerInfo		來源資訊

比如，啟動小程式的 schema url 如下:

alipays://platformapi/startapp?appId=1999&query=number%3D1&page=x%2Fy%2
Fz           

• 小程式首次啟動時，onLaunch 方法可擷取 query、path 屬性值。
• 小程式在背景被用 schema 打開，也可從 onShow 方法中擷取 query、path 屬性值。

App({
 onLaunch(options) {
 // 第一次打開
 console.log(options.query);
 // {number:1}
 console.log(options.path);
 // x/y/z
 },
 onShow(options) {
 // 從背景被 schema 重新打開
 console.log(options.query);
 // {number:1}
 console.log(options.path);
 // x/y/z
 },
});           

referrerInfo 子屬性說明：

appId		來源小程式
sourceServiceId		來源插件，當處于插件運作模式時可見	1.11.0
extraData		來源小程式傳過來的資料。

• 不要在 onShow 中進行 redirectTo 或 navigateTo 等操作頁面棧的行為。
• 不要在 onLaunch 裡調用 getCurrentPages() ，因為此時 page 還未生成。

onHide()

小程式從前台進入背景時觸發 onHide() 。

App({
 onHide() {
 // 進入背景時
 console.log('app hide');
 },
});           

onError(error: String)

小程式發生腳本錯誤時觸發。

App({
 onError(error) {
 // 小程式執行出錯時
 console.log(error);
 },
});           

onShareAppMessage(object: Object)

全局分享配置。當頁面未設定 page.onShareAppMessage 時，調用分享會執行全局的分享設定，具體見

分享

。

globalData 全局資料

App() 中可以設定全局資料 globalData。

// app.js
App({
 globalData: 1
});           

getApp 方法

小程式提供了全局的 getApp() 方法，可擷取目前小程式執行個體，一般用于在子頁面中擷取頂層應用。

var app = getApp();
console.log(app.globalData); // 擷取 globalData           

使用過程中，請注意以下幾點：

• App() 函數中不可以調用 getApp()，可使用 this 可以擷取目前小程式執行個體。
• 通過 getApp() 擷取執行個體後，請勿私自調用生命周期回調函數。
• 請區分全局變量及頁面局部變量，比如：

// app.js
App({
 //定義全局變量 globalData，在整個 App 中有效
 globalData: 1
});           

// a.js
// 定義頁面局部變量 localValue，隻在 a.js 有效
var localValue = 'a';
// 擷取 app 執行個體
var app = getApp();
// 拿到全局資料，并改變它
app.globalData++;           

// b.js
// 定義頁面局部變量 localValue，隻在 b.js 有效
var localValue = 'b';
// 如果 a.js 先運作，globalData 會傳回 2
console.log(getApp().globalData);           

a.js 和 b.js 兩個檔案中都聲明了變量 localValue，但并不會互相影響，因為各個檔案聲明的局部變量和函數隻在目前檔案下有效。