框架

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

├── dist                   編譯結(jié)果目錄
├── config                 配置目錄
|   ├── dev.js             開發(fā)時配置
|   ├── index.js           默認配置
|   └── prod.js            打包時配置
├── src                    源碼目錄
|   ├── pages              頁面文件目錄
|   |   ├── index          index 頁面目錄
|   |   |   ├── index.js   index 頁面邏輯
|   |   |   └── index.css  index 頁面樣式
|   ├── app.css            項目總通用樣式
|   └── app.js             項目入口文件
└── package.json

入口文件

入口文件默認是 src 目錄下的 app.js。

代碼示例

一個普通的入口文件示例如下

import Taro, { Component } from '@tarojs/taro'
import Index from './pages/index'

import './app.scss'

class App extends Component {
  // 項目配置
  config = {
    pages: [
      'pages/index/index'
    ],
    window: {
      backgroundTextStyle: 'light',
      navigationBarBackgroundColor: '#fff',
      navigationBarTitleText: 'WeChat',
      navigationBarTextStyle: 'black'
    }
  }

  componentWillMount () {}

  componentDidMount () {}

  componentDidShow () {}

  componentDidHide () {}

  render () {
    return (
      <Index />
    )
  }
}

可以看出入口文件也是 React 風格的寫法，首先需要引用依賴 @tarojs/taro，這是 Taro 方案的基礎(chǔ)框架，在這里我們繼承了 Component 組件基類。

全局配置

通常入口文件會包含一個 config 配置項，這個配置是整個應(yīng)用的全局的配置，配置規(guī)范基于微信小程序的全局配置進行制定，所有平臺進行統(tǒng)一。

入口文件中的全局配置，在編譯后將生成全局配置文件 app.json。

配置項列表

Taro 中全局配置所包含的配置項及各端支持程度如下

pages

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

數(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

則需要在入口文件配置中寫

class App extends Component {
  // 項目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ]
  }
  ...
}

window

用于設(shè)置小程序的狀態(tài)欄、導航條、標題、窗口背景色，其配置項如下。

各端支持程度如下

微信小程序中，關(guān)于navigationStyle

• 客戶端 7.0.0 以下版本，navigationStyle 只在 app.json 中生效。
  
• 客戶端 6.7.2 版本開始，navigationStyle: custom 對 <web-view> 組件無效
  
• 開啟 custom 后，低版本客戶端需要做好兼容。開發(fā)者工具基礎(chǔ)庫版本切到 1.7.0（不代表最低版本，只供調(diào)試用）可方便切到舊視覺

配置示例如下：

class App extends Component {
  // 項目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    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

微信小程序基礎(chǔ)庫 2.1.0 開始支持

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

subPackages

微信客戶端 6.6.0 ，基礎(chǔ)庫 1.7.3 及以上版本支持
百度小程序支持
H5 和 RN 會把 subPackages 合入 pages

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

workers

微信小程序基礎(chǔ)庫 1.9.90 開始支持

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

requiredBackgroundModes

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

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

• audio: 后臺音樂播放

class App extends Component {
  // 項目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    requiredBackgroundModes: ['audio']
  }
  ...
}

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

plugins

微信小程序基礎(chǔ)庫 1.9.6 開始支持

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

preloadRule

微信小程序基礎(chǔ)庫 2.3.0 開始支持

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

微信小程序文檔 百度小程序文檔

resizable

微信小程序基礎(chǔ)庫 2.3.0 開始支持

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

navigateToMiniProgramAppIdList

微信小程序基礎(chǔ)庫 2.4.0 開始支持

當小程序需要使用 Taro.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)

class App extends Component {
  // 項目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    permission: {
      'scope.userLocation': {
        desc: '你的位置信息將用于小程序位置接口的效果展示'
      }
    }
  }
  ...
}

生命周期

而且由于入口文件繼承自 Component 組件基類，它同樣擁有組件生命周期，但因為入口文件的特殊性，他的生命周期并不完整，具體如下

componentWillMount()

在微信/百度/字節(jié)跳動/支付寶小程序中這一生命周期方法對應(yīng) app 的 onLaunch

監(jiān)聽程序初始化，初始化完成時觸發(fā)（全局只觸發(fā)一次）

在此生命周期中通過 this.$router.params，可以訪問到程序初始化參數(shù)

參數(shù)格式如下

其中，場景值 scene，在微信小程序和百度小程序中存在區(qū)別，請分別參考 微信小程序文檔 和 百度小程序文檔

來源信息 referrerInfo 的數(shù)據(jù)結(jié)構(gòu)如下

componentDidMount()

在微信/百度/字節(jié)跳動/支付寶小程序中這一生命周期方法對應(yīng) app 的 onLaunch，在 componentWillMount 后執(zhí)行

監(jiān)聽程序初始化，初始化完成時觸發(fā)（全局只觸發(fā)一次）

在此生命周期中也可以通過 this.$router.params，訪問到程序初始化參數(shù)，與 componentWillMount 中一致

componentDidShow()

在微信/百度/字節(jié)跳動/支付寶小程序中這一生命周期方法對應(yīng) onShow，在 H5/RN 中同步實現(xiàn)

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

在此生命周期中通過 this.$router.params，可以訪問到程序初始化參數(shù)

參數(shù)與 componentWillMount 中獲取的基本一致，但百度小程序中補充兩個參數(shù)如下

componentDidHide()

在微信/百度/字節(jié)跳動/支付寶小程序中這一生命周期方法對應(yīng) onHide，在 H5/RN 中同步實現(xiàn)

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

componentDidCatchError(String error)

在微信/百度/字節(jié)跳動/支付寶小程序中這一生命周期方法對應(yīng) onError，H5/RN 中尚未實現(xiàn)

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

componentDidNotFound(Object)

在微信/字節(jié)跳動小程序中這一生命周期方法對應(yīng) onPageNotFound，其他端尚未實現(xiàn)
微信小程序中，基礎(chǔ)庫 1.9.90 開始支持

程序要打開的頁面不存在時觸發(fā)，微信小程序中也可以使用 Taro.onPageNotFound 綁定監(jiān)聽

參數(shù)如下

Taro.getApp(Object)

可以用來獲取到程序 App 實例，在各個端均有實現(xiàn)

微信小程序端可以傳入一個 Object 參數(shù)，格式如下

入口文件 render 方法說明

入口文件需要包含一個 render 方法，一般返回程序的第一個頁面，但值得注意的是不要在入口文件中的 render 方法里寫邏輯及引用其他頁面、組件，因為編譯時 render 方法的內(nèi)容會被直接替換掉，你的邏輯代碼不會起作用。

頁面

Taro 項目的頁面一般都放在 src 中的 pages 目錄下，如果頁面包含 js 以及 css，建議頁面以文件夾的形式進行組織，例如 index 頁面包含 index.js 和 index.scss，則在 pages 目錄下新建 index 目錄。

指定頁面

頁面創(chuàng)建好后如果需要渲染展示，則需要在項目入口文件 app.js 中 config 的 pages 數(shù)組中進行指定，例如上面提到的 index 頁面，需要如下進行配置，頁面配置需要指定到頁面具體的 js 文件，可以不帶 .js 后綴

// ...
class App extends Component {
  // 項目配置
  config = {
    pages: [
      'pages/index/index'
    ]
  }
  // ...
}

代碼示例

一個普通的頁面文件示例如下

import Taro, { Component } from '@tarojs/taro'
import { View, Text } from '@tarojs/components'
import './index.scss'

export default class Index extends Component {
  config = {
    navigationBarTitleText: '首頁'
  }

  componentWillMount () { }

  componentDidMount () { }

  componentWillUnmount () { }

  componentDidShow () { }

  componentDidHide () { }

  render () {
    return (
      <View className='index'>
        <Text>1</Text>
      </View>
    )
  }
}

Taro 的頁面同樣是繼承自 Component 組件基類，每一個頁面都擁有自己配置 config，這個配置是針對當前頁面配置，配置規(guī)范基于微信小程序的頁面配置進行制定，所有平臺進行統(tǒng)一。

頁面文件中的 config 配置，在編譯后將生成全局配置文件 app.json。

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

配置示例：

export default class Index extends Component {
  config = {
    navigationBarBackgroundColor: '#ffffff',
    navigationBarTextStyle: 'black',
    navigationBarTitleText: '首頁',
    backgroundColor: '#eeeeee',
    backgroundTextStyle: 'light'
  }

  render () {
    return (
      <View className='index'>
        <Text>1</Text>
      </View>
    )
  }
}

配置項列表

各端支持程度如下

其中，usingComponents 一般不需要配置，只有在需要與引用原生小程序組件的時候才需要配置。

頁面說明

頁面的樣式文件建議放在與頁面 JS 的同級目錄下，然后通過 ES6 規(guī)范 import 進行引入，支持使用 CSS 預編譯處理器，目前提供了 sass 預編譯插件 @tarojs/plugin-sass，需要自行在本地進行安裝。

頁面 JS 要求必須有一個 render 函數(shù)，函數(shù)返回 JSX 代碼，具體 JSX 代碼的寫法請參考 JSX 章節(jié)。

生命周期

由于頁面 JS 也繼承自 Component 組件基類，所以頁面同樣擁有生命周期，頁面的生命周期方法如下：

componentWillMount()

頁面加載時觸發(fā)，一個頁面只會調(diào)用一次，此時頁面 DOM 尚未準備好，還不能和視圖層進行交互

componentDidMount()

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

shouldComponentUpdate(nextProps, nextState)

頁面是否需要更新，返回 false 不繼續(xù)更新，否則繼續(xù)走更新流程

componentWillUpdate(nextProps, nextState)

頁面即將更新

componentDidUpdate(prevProps, prevState)

頁面更新完畢

componentWillUnmount()

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

componentDidShow()

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

componentDidHide()

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

在以上所有的生命周期方法中，都可以通過 this.$router.params 獲取打開當前頁面路徑中的參數(shù)。

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

在小程序中，頁面還有在一些專屬的事件處理函數(shù)，如下

onPullDownRefresh()

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

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

onReachBottom()

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

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

onPageScroll(Object)

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

Object 參數(shù)說明：

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

onShareAppMessage(Object)

監(jiān)聽用戶點擊頁面內(nèi)轉(zhuǎn)發(fā)按鈕（Button 組件 openType='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)容

示例代碼

export default class Index extends Component {
  config = {
    navigationBarTitleText: '首頁'
  }

  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'
    }
  }

  render () {
    return (
      <View className='index'>
        <Text>1</Text>
      </View>
    )
  }
}

onResize(object)

只有微信小程序支持
基礎(chǔ)庫 2.4.0 開始支持

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

onTabItemTap(Object)

微信小程序中，基礎(chǔ)庫 1.9.0 開始支持

點擊 tab 時觸發(fā)

Object 參數(shù)說明：

componentWillPreload()

目前只有微信小程序支持

預加載鉤子

onTitleClick()

只有支付寶小程序支持，基礎(chǔ)庫 1.3.0 開始支持

點擊標題觸發(fā)

onOptionMenuClick()

只有支付寶小程序支持，基礎(chǔ)庫 1.3.0 開始支持

點擊導航欄額外圖標觸發(fā)

onPopMenuClick()

只有支付寶小程序支持，基礎(chǔ)庫 1.11.0 開始支持

暫無說明

onPullIntercept()

只有支付寶小程序支持，基礎(chǔ)庫 1.3.0 開始支持

下拉截斷時觸發(fā)

H5 暫時沒有同步實現(xiàn) onReachBottom 、 onPageScroll 這兩個事件函數(shù)，可以通過給 window 綁定 scroll 事件來進行模擬，而 onPullDownRefresh 下拉刷新則暫時只能用 ScrollView 組件來代替了。

頁面事件函數(shù)各端支持程度如下

以上成員方法在 Taro 的頁面中同樣可以使用，書寫同名方法即可，不過需要注意的，目前暫時只有小程序端支持（支持程度如上）這些方法，編譯到 H5/RN 端后這些方法均會失效。

組件

Taro 支持組件化開發(fā)，組件代碼可以放在任意位置，不過建議放在 src 下的 components 目錄中。一個組件通常包含組件 JS 文件以及組件樣式文件，組織方式與頁面類似。

組件配置

一般來說，Taro 組件不需要任何配置，但當你在 Taro 組件中引用原生小程序組件代碼時，則需要通過配置 config 來實現(xiàn)。

配置項如下

usingComponents 中通過 組件名: 組件相對路徑 這種 key/value 的方式定義引用的組件。

代碼示例

import Taro, { Component } from '@tarojs/taro'
import { View, Image, Button } from '@tarojs/components'
import './tab.scss'

class Tab extends Component {

  onNewTodo = () => {
    // dosth
  }

  componentWillMount () { }

  componentDidMount () { }

  componentWillUnmount () { }

  componentWillReceiveProps () { }

  render () {
    return (
      <View className='tab'>
        tab
      </View>
    )
  }
}

組件說明

組件的樣式文件可以需要在組件中通過 import 語法進行引入。

Taro 的組件同樣是繼承自 Component 組件基類，與頁面類似，組件也必須包含一個 render 函數(shù)，返回 JSX 代碼。

生命周期

由于組件 JS 也繼承自 Component 組件基類，所以頁面同樣擁有生命周期，頁面的生命周期方法如下：

componentWillMount()

組件加載時觸發(fā)，一個組件只會調(diào)用一次，此時組件 DOM 尚未準備好，還不能和視圖層進行交互

componentDidMount()

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

componentWillReceiveProps(nextProps)

已經(jīng)裝載的組件接收到新屬性前調(diào)用

shouldComponentUpdate(nextProps, nextState)

組件是否需要更新，返回 false 不繼續(xù)更新，否則繼續(xù)走更新流程

componentWillUpdate(nextProps, nextState)

組件即將更新

componentDidUpdate(prevProps, prevState)

組件更新完畢

componentWillUnmount()

組件卸載時觸發(fā)

具體生命周期的使用以及組件類的說明可以查看組件說明章節(jié)。