Taro 框架

2021-09-23 20:55 更新

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

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

入口文件

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

代碼示例請(qǐng)根據(jù)你選擇的框架進(jìn)行查看：React, Nerv, Vue。

全局配置

配置項(xiàng)列表

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

屬性 類型 必填 描述 微信小程序 百度小程序 字節(jié)跳動(dòng)小程序 支付寶小程序 H5 RN
pages String Array 是 頁(yè)面路徑列表 ?? ?? ?? ?? ?? ??
window Object 否 全局的默認(rèn)窗口表現(xiàn) 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方
tabBar Object 否 底部 tab 欄的表現(xiàn) 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方 具體支持程度見(jiàn)下方
networkTimeout Object 否 網(wǎng)絡(luò)超時(shí)時(shí)間 ?? ? ? ? ? ?
debug Boolean 否 是否開啟 debug 模式，默認(rèn)關(guān)閉 ?? ? ?? ? ? ?
functionalPages Boolean 否 是否啟用插件功能頁(yè)，默認(rèn)關(guān)閉 ??（基礎(chǔ)庫(kù) 2.1.0 以上） ? ? ? ? ?
subPackages Object Array 否 分包結(jié)構(gòu)配置 ??（基礎(chǔ)庫(kù) 1.7.3 以上） ?? ? ? ?? ??
workers String 否 Worker 代碼放置的目錄 ??（基礎(chǔ)庫(kù) 1.9.90 以上） ? ? ? ? ?
requiredBackgroundModes String Array 否 需要在后臺(tái)使用的能力，如「音樂(lè)播放」 ?? ? ? ? ? ?
plugins Object 否 使用到的插件 ??（基礎(chǔ)庫(kù) 1.9.6 以上） ? ? ? ? ?
preloadRule Object 否 分包預(yù)下載規(guī)則 ??（基礎(chǔ)庫(kù) 2.3.0 以上） ?? ? ? ? ?
resizable Boolean 否 iPad 小程序是否支持屏幕旋轉(zhuǎn)，默認(rèn)關(guān)閉 ??（基礎(chǔ)庫(kù) 2.3.0 以上） ? ? ? ? ?
navigateToMiniProgramAppIdList String Array 否 需要跳轉(zhuǎn)的小程序列表，詳見(jiàn) wx.navigateToMiniProgram ??（基礎(chǔ)庫(kù) 2.4.0 以上） ? ? ? ? ?
usingComponents Object 否 全局自定義組件配置 ??（開發(fā)者工具 1.02.1810190） ? ? ? ? ?
permission Object 否 小程序接口權(quán)限相關(guān)設(shè)置 ??微信客戶端 7.0.0 ? ? ? ? ?

pages

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

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

如開發(fā)目錄為：

  1. ├── app.js
  2. ├── app.json
  3. ├── app.wxss
  4. ├── pages
  5. │   │── index
  6. │   │   ├── index.wxml
  7. │   │   ├── index.js
  8. │   │   ├── index.json
  9. │   │   └── index.wxss
  10. │   └── logs
  11. │       ├── logs.wxml
  12. │       └── logs.js
  13. └── utils

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

  1. // app.config.js
  2. export default {
  3.   pages: [
  4.     'pages/index/index',
  5.     'pages/logs/logs'
  6.   ]
  7. }

window

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

屬性 類型 默認(rèn)值 描述
navigationBarBackgroundColor HexColor（十六進(jìn)制顏色值） #000000 導(dǎo)航欄背景顏色，如 #000000
navigationBarTextStyle String white 導(dǎo)航欄標(biāo)題顏色，僅支持 black / white
navigationBarTitleText String 導(dǎo)航欄標(biāo)題文字內(nèi)容
navigationStyle String default 導(dǎo)航欄樣式，僅支持以下值：default 默認(rèn)樣式；custom 自定義導(dǎo)航欄，只保留右上角膠囊按鈕
backgroundColor String 窗口的背景色
backgroundTextStyle String dark 下拉 loading 的樣式，僅支持 dark / light
backgroundColorTop String #ffffff 頂部窗口的背景色，僅 iOS 支持
backgroundColorBottom String #ffffff 底部窗口的背景色，僅 iOS 支持
enablePullDownRefresh boolean false 是否開啟當(dāng)前頁(yè)面的下拉刷新。
onReachBottomDistance Number 50 頁(yè)面上拉觸底事件觸發(fā)時(shí)距頁(yè)面底部距離，單位為 px
pageOrientation String portrait 屏幕旋轉(zhuǎn)設(shè)置，支持 auto / portrait / landscape 詳見(jiàn) 響應(yīng)顯示區(qū)域變化

各端支持程度如下

屬性 微信小程序 百度小程序 字節(jié)跳動(dòng)小程序 支付寶小程序 H5 RN
navigationBarBackgroundColor ?? ?? ?? ?? ?? ??
navigationBarTextStyle ?? ?? ?? ? ?? ??
navigationBarTitleText ?? ?? ?? ?? ?? ??
navigationStyle ??（微信客戶端 6.6.0） ??（百度 App 版本 11.1.0） ?? ? ? ?
backgroundColor ?? ?? ?? ? ? ?
backgroundTextStyle ?? ?? ?? ? ? ?
backgroundColorTop ??（微信客戶端 6.5.16） ? ?? ? ? ?
backgroundColorBottom ??（微信客戶端 6.5.16） ? ?? ? ? ?
enablePullDownRefresh ?? ?? ?? ?? ? ?
onReachBottomDistance ?? ?? ?? ? ? ?
pageOrientation ??2.4.0 (auto) / 2.5.0 (landscape) ? ? ? ? ?

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

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

配置示例如下：

  1. // app.config.js
  2. export default {
  3.   pages: [
  4.     'pages/index/index',
  5.     'pages/logs/logs'
  6.   ],
  7.   window: {
  8.     navigationBarBackgroundColor: '#ffffff',
  9.     navigationBarTextStyle: 'black',
  10.     navigationBarTitleText: '微信接口功能演示',
  11.     backgroundColor: '#eeeeee',
  12.     backgroundTextStyle: 'light'
  13.   }
  14. }

tabBar

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

其配置項(xiàng)如下

屬性 類型 必填 默認(rèn)值 描述
color HexColor（十六進(jìn)制顏色值） 是 tab 上的文字默認(rèn)顏色，僅支持十六進(jìn)制顏色
selectedColor HexColor（十六進(jìn)制顏色值） 是 tab 上的文字選中時(shí)的顏色，僅支持十六進(jìn)制顏色
backgroundColor HexColor（十六進(jìn)制顏色值） 是 tab 的背景色，僅支持十六進(jìn)制顏色
borderStyle String 是 black tabbar 上邊框的顏色， 僅支持 black / white
list Array 是 tab 的列表，詳見(jiàn) list 屬性說(shuō)明，最少 2 個(gè)、最多 5 個(gè) tab
position String 否 bottom tabBar的位置，僅支持 bottom / top
custom Boolean 否 false 自定義 tabBar

各端支持程度如下

屬性 微信小程序 百度小程序 字節(jié)跳動(dòng)小程序 支付寶小程序 H5 RN
color ?? ?? ?? ?? ?? ??
selectedColor ?? ?? ?? ?? ?? ??
backgroundColor ?? ?? ?? ?? ?? ??
borderStyle ?? ?? ?? ? ?? ??
list ?? ?? ?? ?? ?? ??
position ?? ? ?? ? ? ?
custom ??（基礎(chǔ)庫(kù) 2.5.0 以上） ? ? ? ? ?

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

屬性 類型 必填 描述
pagePath String 是 頁(yè)面路徑，必須在 pages 中先定義
text String 是 tab 上按鈕文字
iconPath String 否 圖片路徑，icon 大小限制為40kb，建議尺寸為 81px 81px，不支持網(wǎng)絡(luò)圖片。
當(dāng) position 為 top 時(shí)，不顯示 icon。
selectedIconPath String 否 選中時(shí)的圖片路徑，icon 大小限制為40kb，建議尺寸為 81px 81px，不支持網(wǎng)絡(luò)圖片。
當(dāng) position 為 top 時(shí)，不顯示 icon。

networkTimeout

只在微信小程序上支持

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

屬性 類型 必填 默認(rèn)值 描述
request Number 否 60000 Taro.request 的超時(shí)時(shí)間，單位：毫秒
connectSocket Number 否 60000 Taro.connectSocket 的超時(shí)時(shí)間，單位：毫秒
uploadFile Number 否 60000 Taro.uploadFile 的超時(shí)時(shí)間，單位：毫秒
downloadFile Number 否 60000 Taro.downloadFile 的超時(shí)時(shí)間，單位：毫秒

debug

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

functionalPages

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

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

subPackages

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

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

workers

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

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

requiredBackgroundModes

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

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

  • audio: 后臺(tái)音樂(lè)播放
  1. export default {
  2.   pages: [
  3.     'pages/index/index',
  4.     'pages/logs/logs'
  5.   ],
  6.   requiredBackgroundModes: ['audio']
  7. }

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

plugins

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

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

preloadRule

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

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

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

resizable

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

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

navigateToMiniProgramAppIdList

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

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

usingComponents

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

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

permission

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

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

屬性 類型 必填 默認(rèn)值 描述
scope.userLocation PermissionObject 否 位置相關(guān)權(quán)限聲明

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

屬性 類型 必填 默認(rèn)值 描述
desc string 是 小程序獲取權(quán)限時(shí)展示的接口用途說(shuō)明。最長(zhǎng) 30 個(gè)字符 
  1. export default {
  2.   pages: [
  3.     'pages/index/index',
  4.     'pages/logs/logs'
  5.   ],
  6.   permission: {
  7.     'scope.userLocation': {
  8.       desc: '你的位置信息將用于小程序位置接口的效果展示'
  9.     }
  10.   }
  11. }

imageW

Taro.getApp(Object)

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

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

屬性 類型 說(shuō)明 基礎(chǔ)庫(kù)最低版本
allowDefault Boolean 在 App 未定義時(shí)返回默認(rèn)實(shí)現(xiàn)。當(dāng)App被調(diào)用時(shí)，默認(rèn)實(shí)現(xiàn)中定義的屬性會(huì)被覆蓋合并到App中。一般用于獨(dú)立分包 2.2.4

頁(yè)面

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

指定頁(yè)面

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

  1. // ...
  2. export default  {
  3.   pages: [
  4.     'pages/index/index'
  5.   ]
  6. }

頁(yè)面配置

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

配置項(xiàng)列表

屬性 類型 默認(rèn)值 描述
navigationBarBackgroundColor HexColor（十六進(jìn)制顏色值） #000000 導(dǎo)航欄背景顏色，如 #000000
navigationBarTextStyle String white 導(dǎo)航欄標(biāo)題顏色，僅支持 black / white
navigationBarTitleText String 導(dǎo)航欄標(biāo)題文字內(nèi)容
navigationStyle String default 導(dǎo)航欄樣式，僅支持以下值：default 默認(rèn)樣式；custom 自定義導(dǎo)航欄，只保留右上角膠囊按鈕
backgroundColor String 窗口的背景色
backgroundTextStyle String dark 下拉 loading 的樣式，僅支持 dark / light
backgroundColorTop String #ffffff 頂部窗口的背景色，僅 iOS 支持
backgroundColorBottom String #ffffff 底部窗口的背景色，僅 iOS 支持
enablePullDownRefresh boolean false 是否開啟當(dāng)前頁(yè)面的下拉刷新。
onReachBottomDistance Number 50 頁(yè)面上拉觸底事件觸發(fā)時(shí)距頁(yè)面底部距離，單位為 px
pageOrientation String portrait 屏幕旋轉(zhuǎn)設(shè)置，支持 auto / portrait / landscape 詳見(jiàn) 響應(yīng)顯示區(qū)域變化
disableScroll Boolean false 設(shè)置為 true 則頁(yè)面整體不能上下滾動(dòng)。
只在頁(yè)面配置中有效，無(wú)法在 app.json 中設(shè)置
disableSwipeBack Boolean false 禁止頁(yè)面右滑手勢(shì)返回
usingComponents Object 否 頁(yè)面自定義組件配置

各端支持程度如下

屬性 微信小程序 百度小程序 字節(jié)跳動(dòng)小程序 支付寶小程序 H5 RN
navigationBarBackgroundColor ?? ?? ?? ?? ?? ??
navigationBarTextStyle ?? ?? ?? ? ?? ??
navigationBarTitleText ?? ?? ?? ?? ?? ??
navigationStyle ??（微信客戶端 6.6.0） ??（百度 App 版本 11.1.0） ?? ? ? ??
backgroundColor ?? ?? ?? ? ? ??
backgroundTextStyle ?? ?? ?? ? ? ??
backgroundColorTop ??（微信客戶端 6.5.16） ? ?? ? ? ?
backgroundColorBottom ??（微信客戶端 6.5.16） ? ?? ? ? ?
enablePullDownRefresh ?? ?? ?? ?? ? ?
onReachBottomDistance ?? ?? ?? ? ? ?
pageOrientation ??2.4.0 (auto) / 2.5.0 (landscape) ? ? ? ? ?
disableScroll ?? ? ? ? ? ??
disableSwipeBack ?? ? ? ? ? ?
usingComponents ?? ?? ?? ?? ? ?

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

頁(yè)面說(shuō)明

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


以上內(nèi)容是否對(duì)您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)