框架

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

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

入口文件

入口文件默認(rèn)是 src 目錄下的 app.js。

代碼示例

一個(gè)普通的入口文件示例如下

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

import './app.scss'

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

  componentWillMount () {}

  componentDidMount () {}

  componentDidShow () {}

  componentDidHide () {}

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

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

全局配置

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

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

配置項(xiàng)列表

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

pages

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

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

如開發(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 {
  // 項(xiàng)目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ]
  }
  ...
}

window

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

各端支持程度如下

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

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

配置示例如下：

class App extends Component {
  // 項(xiàng)目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    window: {
      navigationBarBackgroundColor: '#ffffff',
      navigationBarTextStyle: 'black',
      navigationBarTitleText: '微信接口功能演示',
      backgroundColor: '#eeeeee',
      backgroundTextStyle: 'light'
    }
  }
  ...
}

tabBar

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

其配置項(xiàng)如下

各端支持程度如下

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

networkTimeout

只在微信小程序上支持

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

debug

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

functionalPages

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

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

subPackages

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

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

workers

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

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

requiredBackgroundModes

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

申明需要后臺(tái)運(yùn)行的能力，類型為數(shù)組。目前支持以下項(xiàng)目：

• audio: 后臺(tái)音樂播放

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

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

plugins

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

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

preloadRule

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

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

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

resizable

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

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

navigateToMiniProgramAppIdList

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

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

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 {
  // 項(xiàng)目配置
  config = {
    pages: [
      'pages/index/index',
      'pages/logs/logs'
    ],
    permission: {
      'scope.userLocation': {
        desc: '你的位置信息將用于小程序位置接口的效果展示'
      }
    }
  }
  ...
}

生命周期

而且由于入口文件繼承自 Component 組件基類，它同樣擁有組件生命周期，但因?yàn)槿肟谖募奶厥庑裕纳芷诓⒉煌暾?，具體如下

componentWillMount()

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

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

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

參數(shù)格式如下

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

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

componentDidMount()

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

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

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

componentDidShow()

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

程序啟動(dòng)，或從后臺(tái)進(jìn)入前臺(tái)顯示時(shí)觸發(fā)，微信小程序中也可以使用 Taro.onAppShow 綁定監(jiān)聽

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

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

componentDidHide()

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

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

componentDidCatchError(String error)

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

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

componentDidNotFound(Object)

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

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

參數(shù)如下

Taro.getApp(Object)

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

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

入口文件 render 方法說明

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

頁面

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

指定頁面

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

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

代碼示例

一個(gè)普通的頁面文件示例如下

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 組件基類，每一個(gè)頁面都擁有自己配置 config，這個(gè)配置是針對(duì)當(dāng)前頁面配置，配置規(guī)范基于微信小程序的頁面配置進(jìn)行制定，所有平臺(tái)進(jìn)行統(tǒng)一。

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

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

配置示例：

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

配置項(xiàng)列表

各端支持程度如下

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

頁面說明

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

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

生命周期

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

componentWillMount()

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

componentDidMount()

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

shouldComponentUpdate(nextProps, nextState)

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

componentWillUpdate(nextProps, nextState)

頁面即將更新

componentDidUpdate(prevProps, prevState)

頁面更新完畢

componentWillUnmount()

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

componentDidShow()

頁面顯示/切入前臺(tái)時(shí)觸發(fā)

componentDidHide()

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

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

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

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

onPullDownRefresh()

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

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

onReachBottom()

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

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

onPageScroll(Object)

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

Object 參數(shù)說明：

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

onShareAppMessage(Object)

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

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

Object 參數(shù)說明：

此事件需要 return 一個(gè) 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ā)標(biāo)題',
      path: '/page/user?id=123'
    }
  }

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

onResize(object)

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

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

onTabItemTap(Object)

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

點(diǎn)擊 tab 時(shí)觸發(fā)

Object 參數(shù)說明：

componentWillPreload()

目前只有微信小程序支持

預(yù)加載鉤子

onTitleClick()

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

點(diǎn)擊標(biāo)題觸發(fā)

onOptionMenuClick()

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

點(diǎn)擊導(dǎo)航欄額外圖標(biāo)觸發(fā)

onPopMenuClick()

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

暫無說明

onPullIntercept()

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

下拉截?cái)鄷r(shí)觸發(fā)

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

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

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

組件

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

組件配置

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

配置項(xiàng)如下

usingComponents 中通過 組件名: 組件相對(duì)路徑 這種 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 語法進(jìn)行引入。

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

生命周期

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

componentWillMount()

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

componentDidMount()

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

componentWillReceiveProps(nextProps)

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

shouldComponentUpdate(nextProps, nextState)

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

componentWillUpdate(nextProps, nextState)

組件即將更新

componentDidUpdate(prevProps, prevState)

組件更新完畢

componentWillUnmount()

組件卸載時(shí)觸發(fā)

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