非常詳細的Taro入門教程

來源 | https://segmentfault.com/a/1190000039033249

簡介

環(huán)境準備

Taro 僅提供一種開發(fā)方式：安裝 Taro 命令行工具（Taro CLI）進行開發(fā)。
在終端輸入命令 npm i -g @tarojs/cli 安裝 Taro CLI。
Taro CLI 依賴于 Node.js 環(huán)境（>=8.0.0）。

框架

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

編譯配置

編譯配置存放于項目根目錄下 config 目錄中，包含三個文件:

index.js: 通用配置
dev.js : 開發(fā)環(huán)境配置
prod.js : 生產(chǎn)環(huán)境配置

入口文件

每一個 Taro 應(yīng)用都需要一個入口組件用來注冊應(yīng)用，入口文件默認是 src/app.js。

頁面文件

頁面組件是每一項路由將會渲染的頁面，Taro 的頁面默認放在 src/pages 中，每一個 Taro 項目至少有一個頁面組件。頁面創(chuàng)建好后如果需要渲染展示，需要在項目入口文件 app.config.js 的 pages 數(shù)組中進行指定。

文件配置

全局配置：可以通過 app.config.js 的文件進行全局配置， 配置頁面文件的路徑、窗口表現(xiàn)、設(shè)置網(wǎng)絡(luò)超時時間、設(shè)置多 tab 等。

一個簡單的全局配置如下：

// app.config.jsexport default {  pages: [    'pages/index/index',    'pages/list/index'  ],  window: {    backgroundTextStyle: 'light',    navigationBarBackgroundColor: '#fff',  }}

未指定 entryPagePath 時，數(shù)組的第一項代表初始頁面。
新增/減少頁面，都需要對 pages 數(shù)組進行修改。

頁面配置：每一個頁面組件（例如 index.js）也會有一個頁面配置（例如 index.config.js），可以在頁面配置文件中設(shè)置頁面的導航欄、背景顏色等參數(shù)。

一個最簡單的頁面配置如下：

// ./pages/index/index.jsxexport default {  navigationBarTitleText: '首頁'}

配置規(guī)范基于微信小程序的全局配置進行制定，所有平臺進行統(tǒng)一。在配置文件中，Taro 并不關(guān)心框架的區(qū)別，Taro CLI 會直接在編譯時在 Node.js 環(huán)境直接執(zhí)行全局配置的代碼，并把 export default 導出的對象序列化為一個 JSON 文件。

因此，我們必須保證配置文件是在 Node.js 環(huán)境中是可以執(zhí)行的，不能使用一些在 H5 環(huán)境或小程序環(huán)境才能運行的包或者代碼，否則編譯將會失敗。

項目配置

為了能夠適配到各個小程序平臺，滿足不同小程序平臺配置文件不同的情況， Taro 支持為各個小程序平臺添加不同的項目配置文件。

通過 Taro 模板創(chuàng)建的項目都會默認擁有 project.config.json 文件，若要兼容到其他小程序平臺，按如下對應(yīng)規(guī)則來增加相應(yīng)平臺的配置文件，其配置與各自小程序平臺要求的一致。

組件生命周期與事件處理函數(shù)

以Hooks為例：

css 工具

在 Taro 中，我們可以自由地使用 CSS 預(yù)處理器和后處理器，使用的方法也非常簡單，只要在編譯配置添加相關(guān)的插件即可：

// config/index.jsconst config = {  designWidth: 750,  sourceRoot: 'src',  outputRoot: 'dist',  plugins: [    '@tarojs/plugin-sass', // 使用 Sass    // '@tarojs/plugin-less', // 使用 Less    // '@tarojs/plugin-stylus', // 使用 Stylus  ],  defineConstants: {},  mini: {},  h5: {}}
module.exports = function (merge) {  if (process.env.NODE_ENV === 'development') {    return merge({}, config, require('./dev'))  }  return merge({}, config, require('./prod'))}

除了 CSS 預(yù)處理器之外，Taro 還支持 CSS Modules 和 CSS-in-JS。通過 自定義編譯 ，還可以支持更多 CSS 工具。

路由功能

在 Taro 中，路由功能是默認自帶的，不需要開發(fā)者進行額外的路由配置。

入口組件和頁面組件是通過配置文件來交互的，我們只需要在入口文件的 config 配置中指定好 pages，然后就可以在代碼中通過 Taro 提供的 API 來跳轉(zhuǎn)到目的頁面，例如：

// 跳轉(zhuǎn)到目的頁面，打開新頁面Taro.navigateTo({  url: '/pages/page/path/name'})
// 跳轉(zhuǎn)到目的頁面，在當前頁面打開Taro.redirectTo({  url: '/pages/page/path/name'})

尺寸單位

在 Taro 中, 尺寸單位建議使用px, %，Taro 默認會對所有單位進行轉(zhuǎn)換。當轉(zhuǎn)成微信小程序的時候，尺寸單位將默認轉(zhuǎn)換以 rpx為單位，當轉(zhuǎn)成 H5 時將默認轉(zhuǎn)換以 rem 為單位。

如果你希望部分 px 單位不被轉(zhuǎn)換成 rpx 或者 rem ，最簡單的做法就是在 px 單位中增加一個大寫字母，例如 Px 或者 PX 這樣，則會被轉(zhuǎn)換插件忽略。

Taro 默認以 750px 作為換算尺寸標準，如果設(shè)計稿不是以 750px 為標準，則需要在項目配置 config/index.js 中進行設(shè)置，例如設(shè)計稿尺寸是 640px，則需要修改項目配置 config/index.js 中的 designWidth 配置為 640：

const config = {  designWidth: 640,}

目前 Taro 支持 750、 640 、 828 三種尺寸設(shè)計稿，他們的換算規(guī)則如下：

const DEVICE_RATIO = {  '640': 2.34 / 2,  '750': 1,  '828': 1.81 / 2}

多端開發(fā)

由于不同的平臺之間還是存在一些無法消除的差異，所以為了更好的實現(xiàn)跨平臺開發(fā)，Taro 中提供了兩種解決方案：

1. 內(nèi)置環(huán)境變量：process.env.TARO_ENV

process.env.TARO_ENV 用于判斷當前編譯類型，目前有 weapp / swan / alipay / h5 / rn / tt / qq / quickapp 八個取值。通過這個變量來寫對應(yīng)一些不同環(huán)境下的代碼，在編譯時會將不屬于當前編譯類型的代碼去掉，只保留當前編譯類型下的代碼。

render () {  return (    <View>      {process.env.TARO_ENV === 'weapp' && <ScrollViewWeapp />}      {process.env.TARO_ENV === 'h5' && <ScrollViewH5 />}    </View>  )}

缺點：雖然可以解決大部分跨端的問題，但是會讓代碼中充斥著邏輯判斷，影響代碼的可維護性，而且也讓代碼變得愈發(fā)丑陋。

2. 統(tǒng)一接口的多端文件

針對一項功能，如果多個端之間都有差異，開發(fā)者可以通過將文件修改成 原文件名.端類型 的命名形式實現(xiàn)多端文件。Taro 在編譯時，會根據(jù)編譯平臺類型，將加載的文件變更為帶有對應(yīng)端類型文件名的文件，從而達到不同的端加載對應(yīng)文件的目的。

使用要點

• 不同端的對應(yīng)文件一定要對外暴露統(tǒng)一接口，統(tǒng)一調(diào)用方式，接受一致的參數(shù)

• 最好有一個平臺無關(guān)的默認文件，這樣在使用 ts 的時候也不會出現(xiàn)報錯

• 引用文件的時候，只需要寫默認文件名，不用帶文件后綴

多端文件簡單的例子：

1、多端組件

// 1. 定義多端組件-test--test.js // Test組件默認的形式，編譯到微信小程序和H5之外的端--test.h5.js // Test 組件的 H5 版本--test.weapp.js // Test 組件的 微信小程序 版本
// 2. 引用組件import Test from '../../components/test';
<Test argA={1} argA={2} />

2、多端方法

// 1.定義多端方法-utils--set_title.js--set_title.h5.js--set_title.weapp.js
// 2. 使用方法import setTitle from '../utils/set_title'
setTitle('頁面標題')

跨平臺組件庫

• H5 端: @tarojs/components，需要引入的默認標準組件庫
• RN 端: @tarojs/components-rn

開發(fā)規(guī)范

• 首字母大寫與駝峰式命名
• 組件的事件傳遞都要以 on 開頭

組件種類

使用

在使用時，我們需要先從 Taro 標準組件庫 @tarojs/components 引用組件，再進行使用。

import Taro, { Component } from '@tarojs/taro';// 使用 <View />、 <Text /> 組件import { View, Text } from '@tarojs/components';
export default class C extends Component {  render () {    return (      <View className='c'>        <Text>c component</Text>      </View>    )  }}

Taro UI

Taro UI 是一款基于 Taro 框架開發(fā)的多端 UI 組件庫。

特性

• 基于 Taro 開發(fā) UI 組件

• 一套組件可以在 微信小程序，支付寶小程序，百度小程序，H5 多端適配運行（ReactNative 端暫不支持）

• 提供友好的 API，可靈活的使用組件

組件種類

使用

1. 引入組件樣式

引入組件樣式有三種方式：

全局引入（JS中）： 在入口文件app.js中引入 taro-ui 所有的樣式

import 'taro-ui/dist/style/index.scss' // 引入組件樣式

全局引入（CSS中）： 在 app.scss 樣式文件中 import 組件樣式并按照文檔說明使用

@import "~taro-ui/dist/style/index.scss"; // 引入組件樣式

按需引入： 在頁面樣式或全局樣式中 import 需要的組件樣式

@import "~taro-ui/dist/style/components/button.scss"; // 引入所需的組件樣式

2. 引入所需組件

// index.jsimport { AtButton } from 'taro-ui';

一個使用AtButton的完整例子：

// src/pages/index/index.tsximport Taro, { Component, Config } from '@tarojs/taro'import { View } from '@tarojs/components'import { AtButton } from 'taro-ui'import './index.scss';
export default class Index extends Component {  config: Config = {    navigationBarTitleText: '首頁'  }
  render () {    return (      <View className='index'>         <AtButton type='primary'>按鈕文案</AtButton>      </View>    )  }}

/* app.scss*/@import "~taro-ui/dist/style/index.scss";

自定義主題

Taro UI 目前只有一套默認的主題配色，為滿足業(yè)務(wù)和品牌上多樣化的視覺需求，UI 庫支持一定程度的樣式定制。（請確保微信基礎(chǔ)庫版本在 v2.2.3 以上）

目前支持三種自定義主題的方式，可以進行不同程度的樣式自定義：

• SCSS 變量覆蓋

• globalClass 全局樣式類

• 配置 customStyle 屬性（僅有部分組件支持，請查看組件文檔，不建議使用）

SCSS 主題變量覆蓋

Taro UI 的組件樣式是使用 SCSS 編寫的，如果你的項目中也使用了 SCSS，那么可以直接在項目中改變 Taro UI 的樣式變量。

1. 覆寫的變量，需要在引入 taro ui 默認樣式之前定義，默認主題變量命名。

2. Slider, Switch 組件暫時不支持 SCSS 變量覆蓋的方式自定義主題。

1、在app.scss文件寫入以下內(nèi)容：

// app.scss$color-brand: #6190E8; /* 改變主題變量 */
@import "~taro-ui/dist/style/index.scss"; /* 引入 Taro UI 默認樣式 */

// app.js
import './app.scss';

改變主題變量前后對比圖：

全局樣式類

全局樣式類是微信小程序定義的一套用于修改組件內(nèi)部樣式的方案。如果希望組件外樣式類能夠影響組件內(nèi)部，可以在組件構(gòu)造器中的 options.addGlobalClass 字段設(shè)置為 true（Taro UI 的組件均開啟了此特性）。

addGlobalClass 只對 Page 上的 class 起作用。換言之，如果在自定義的組件中使用 taro-ui，是無法在自定義組件內(nèi)部通過 全局樣式類 的方式去更改組件樣式的。

當開放了全局樣式類，存在外部樣式無意間污染組件樣式的風險。由于 Taro UI 的組件樣式采用 BEM 的命名方式，從一定程度上避免了樣式污染的問題。

/* page/index/index.js */import Taro from '@tarojs/taro'import { AtButton } from 'taro-ui'import "./index.scss"
export default IndexPage extends Taro.Component {    render () {    return <AtButton className='my-button' />  }}
/** * page/index/index.scss 必須在 Page 上 * .at-button 為組件內(nèi)部類名，只需要寫一樣的類名去覆蓋即可 **/.my-button .at-button {  color: red;}

設(shè)計思想與編譯原理

在 Taro 中先按照 Nerv語法編寫一份源代碼，然后通過編譯工具將源代碼編譯成對應(yīng)的代碼。

編譯工具采用的是編譯原理的思想，所謂編譯原理，就是一個對輸入的源代碼進行語法分析，語法樹構(gòu)建，隨后對語法樹進行轉(zhuǎn)換操作再解析生成目標代碼的過程。

Taro標準：抹平多端差異

基于編譯原理，可以將 Taro 源碼編譯成不同端上可以運行的代碼了，但是這對于實現(xiàn)多端開發(fā)還是遠遠不夠。不同的平臺都有自己的特性，每一個平臺都不盡相同，這些差異主要體現(xiàn)在不同的組件標準與不同的 API 標準以及不同的運行機制上。

以小程序和 Web 端為例：

可以看出小程序和 Web 端上組件標準與 API 標準有很大差異，這些差異僅僅通過代碼編譯手段是無法抹平的，例如不能直接在編譯時將小程序的 <view /> 直接編譯成 <div />，因為他們雖然看上去有些類似，但是他們的組件屬性有很大不同。

僅僅依靠代碼編譯，無法做到一致，同理，眾多 API 也面臨一樣的情況。針對這樣的情況，Taro 采用了定制一套運行時標準來抹平不同平臺之間的差異。

這一套標準主要以三個部分組成，包括標準運行時框架、標準基礎(chǔ)組件庫、標準端能力 API，其中運行時框架和 API 對應(yīng) @taro/taro，組件庫對應(yīng) @tarojs/components，通過在不同端實現(xiàn)這些標準，從而達到去差異化的目的。

taro build命令

taro build 命令是整個 taro 項目的靈魂和核心，主要負責 多端代碼編譯（h5，小程序，React Native等）。不同的平臺，編譯傳參不同，編譯規(guī)則不同。

// package.json 
"scripts": {
    // 微信小程序 weapp
    "build:weapp": "taro build --type weapp",
    // h5
    "build:h5": "taro build --type h5",
    // 支付寶小程序 alipay
    "build:alipay": "taro build --type alipay",
    // ....
  },

編譯工作流與抽象語法樹（AST）

一般來說，將一種結(jié)構(gòu)化語言的代碼編譯成另一種類似的結(jié)構(gòu)化語言的代碼包括以下幾個步驟：

首先是 parse，將代碼 解析（Parse）成 抽象語法樹（Abstract Syntex Tree），然后對抽象語法樹 AST 進行 遍歷（traverse）和 替換(replace)（可以類比 DOM 樹的操作），最后是 生成（generate），根據(jù)新的 AST 生成編譯后的代碼。

Babel模塊

Babel 是一個通用的多功能的 JavaScript編譯器，更確切地說是源碼到源碼的編譯器，通常也叫做轉(zhuǎn)換編譯器（transpiler）。Taro 項目的代碼編譯部分就是基于 Babel 的以下模塊實現(xiàn)：

• babylon Babylon 是 Babel 的解析器。最初是 從Acorn項目fork出來的。Acorn非常快，易于使用，并且針對非標準特性(以及那些未來的標準特性) 設(shè)計了一個基于插件的架構(gòu)。

• babel-traverse Babel Traverse（遍歷）模塊維護了整棵樹的狀態(tài)，并且負責替換、移除和添加節(jié)點。

• babel-types Babel Types模塊是一個用于 AST 節(jié)點的 Lodash 式工具庫， 它包含了構(gòu)造、驗證以及變換 AST 節(jié)點的方法。該工具庫包含考慮周到的工具方法，對編寫處理AST邏輯非常有用。

• babel-generator Babel Generator模塊是 Babel 的代碼生成器，它讀取AST并將其轉(zhuǎn)換為代碼和源碼映射（sourcemaps）。

• babel-template babel-template 是另一個雖然很小但卻非常有用的模塊。它能讓你編寫字符串形式且?guī)в姓嘉环拇a來代替手動編碼， 尤其是生成的大規(guī)模 AST的時候。在計算機科學中，這種能力被稱為準引用（quasiquotes）。