Taro 項(xiàng)目模板

自 1.3.9 開(kāi)始支持

一直以來(lái)，在使用 Taro CLI 的 taro init 命令創(chuàng)建項(xiàng)目時(shí)，CLI 會(huì)提供若干內(nèi)置模板給開(kāi)發(fā)者選擇。但是很多團(tuán)隊(duì)都有自己獨(dú)特的業(yè)務(wù)場(chǎng)景，需要使用和維護(hù)的模板也不盡一致，因此從 1.3.9 開(kāi)始我們把項(xiàng)目模板打包成一個(gè)能力賦予給開(kāi)發(fā)者。

1.3.9 對(duì) CLI 的模板功能做了以下修改：

1. CLI 只保留最基礎(chǔ)的 default 模板，其它模板被移除。
2. CLI 會(huì)從 CLI 全局配置中讀取模版源配置項(xiàng)，然后從模板源拉取模板供開(kāi)發(fā)者選擇。
3. 開(kāi)發(fā)者可以通過(guò)修改模板源來(lái)使用自己的模板。

模板源

模板源為 CLI 配置項(xiàng)的 templateSource 字段，可以使用 taro config 命令對(duì)其進(jìn)行操作。

默認(rèn)模版源

默認(rèn)模板源為 taro-project-templates 倉(cāng)庫(kù)，原本內(nèi)置的模板都被抽離到此處。

配置模板源

模板源支持兩種格式，git 模板源 和 url 模板源。

git 模板源

• GitHub - github:owner/name
• GitLab - gitlab:owner/name
• Direct - direct:url

# 初始化項(xiàng)目時(shí)可以使用 --clone 選項(xiàng)指定拉取遠(yuǎn)程模板時(shí)使用git clone
taro init --clone

url 模板源

指向某 zip 包的 url。

編寫(xiě)模板

模板組織格式

模板目錄組織支持兩種，分別是單模板模式和模板組模式。

單模板模式

git

倉(cāng)庫(kù)根目錄存在 package.json。

模板名為倉(cāng)庫(kù)名。

zip 包

zip 包解壓出單文件夾，文件夾根目錄包含 package.json。

模板名為 zip 包解壓出的文件夾名。

模板組模式

git

如默認(rèn)模板源，倉(cāng)庫(kù)根目錄下存放著若干模板。

模板名對(duì)應(yīng)根目錄下所有文件夾名。

zip 包

zip 包解壓出單文件夾，文件夾內(nèi)包含若干模板。

模板名對(duì)應(yīng)文件夾內(nèi)所有文件夾名。

靜態(tài)模板

靜態(tài)模板表示不帶邏輯的模板，CLI 會(huì)遍歷整個(gè)模板文件夾，把文件一一拷貝到目標(biāo)位置。

動(dòng)態(tài)模板

很多情況下需要為模板加入一些邏輯，從而根據(jù)不同的環(huán)境生成不同的模板內(nèi)容。

開(kāi)發(fā)者可以在模板根目錄加入 template_creator.js 文件，文件對(duì)外 exports 包含 handler 與 basePageFiles 字段的對(duì)象：

function createWhenTs (params) {
  return params.typescript ? true : false
}
const handler = {
  '/global.d.ts': createWhenTs,
  '/tsconfig.json': createWhenTs,
  '/src/pages/index/index.jsx' ({ pageName }) {
    return { setPageName: `/src/pages/${pageName}/${pageName}.jsx` }
  },
  '/src/pages/index/index.css' ({ pageName}) {
    return { setPageName: `/src/pages/${pageName}/${pageName}.css` }
  }
}
const basePageFiles = [
  '/src/pages/index/index.jsx',
  '/src/pages/index/index.css'
]
module.exports = {
  handler,
  basePageFiles
}

模板語(yǔ)言

請(qǐng)使用 ejs 作為模板語(yǔ)言，各模板文件都將接收到全局模板參數(shù)。

默認(rèn)全局模板參數(shù)（模板中可直接使用的變量）

變量	類(lèi)型	說(shuō)明
projectName	string	項(xiàng)目名
description	string	項(xiàng)目描述
version	string	Taro CLI 版本
date	string	模板創(chuàng)建時(shí)間戳
css	‘none’ or ‘sass’ or ‘stylus’ or ‘less’	樣式預(yù)處理工具
cssExt	string	樣式文件后綴
typescript	boolean	是否使用 TS
pageName	string	taro create 時(shí)傳入的頁(yè)面名稱(chēng)，默認(rèn) ‘index’
template	string	模板名稱(chēng)

例子

// index.js
<%if (typescript) {-%>
import Taro, { Component, Config } from '@tarojs/taro'
<%} else { -%>
import Taro, { Component } from '@tarojs/taro'
<%}-%>
import { View, Text } from '@tarojs/components'
import './<%= pageName %>.<%= cssExt %>'

handler 字段

handler 用于控制是否生成某文件，或給文件傳入特定參數(shù)。

handler: object

屬性	類(lèi)型	value
文件路徑	function	處理函數(shù)

文件路徑以 “/” 開(kāi)頭，代表模板文件夾根目錄

處理函數(shù)

params: object

屬性	類(lèi)型	說(shuō)明
projectName	string	項(xiàng)目名
description	string	項(xiàng)目描述
version	string	Taro CLI 版本
date	string	模板創(chuàng)建時(shí)間戳
css	‘none’ or ‘sass’ or ‘stylus’ or ‘less’	樣式預(yù)處理工具
typescript	boolean	是否使用 TS
pageName	string	頁(yè)面名稱(chēng)
template	string	模板名稱(chēng)
templatePath	string	模板路徑
projectPath	string	目標(biāo)路徑
period	‘createApp’ or ‘createPage’	taro init 創(chuàng)建項(xiàng)目或 taro create 創(chuàng)建頁(yè)面

return: boolean/object

返回值說(shuō)明

取值	說(shuō)明
true	創(chuàng)建文件
false	不創(chuàng)建文件
object	創(chuàng)建文件，返回的 object 的字段會(huì)被合并到全局模板參數(shù)中。

若返回值為 object，其中某些屬性有特殊作用：

屬性	類(lèi)型	說(shuō)明
setPageName	string	將替換當(dāng)前文件的輸出路徑
changeExt	boolean	是否自動(dòng)替換文件后綴

例子

當(dāng)用戶(hù)選擇了使用 typescript 時(shí)，才生成 global.d.ts 和 tsconfig.json 文件。

// template_creator.js
function createWhenTs (params) {
  return params.typescript ? true : false
}
const handler = {
  '/global.d.ts': createWhenTs,
  '/tsconfig.json': createWhenTs
}
module.exports = { handler }

basePageFiles 字段

basePageFiles 告訴 CLI，當(dāng)用戶(hù)使用 taro create 命令創(chuàng)建頁(yè)面時(shí)，創(chuàng)建以下文件。

例子

結(jié)合 handler 字段，創(chuàng)建新頁(yè)面。

當(dāng)用戶(hù)使用命令 taro create --page=detail 時(shí)，會(huì)創(chuàng)建 /src/pages/detail/detail.jsx 與 /src/pages/detail/detail.css 兩個(gè)文件。

// template_creator.js
const handler = {
  '/src/pages/index/index.jsx' ({ pageName }) {
    return { setPageName: `/src/pages/${pageName}/${pageName}.jsx` }
  },
  '/src/pages/index/index.css' ({ pageName}) {
    return { setPageName: `/src/pages/${pageName}/${pageName}.css` }
  }
}
const basePageFiles = [
  '/src/pages/index/index.jsx',
  '/src/pages/index/index.css'
]
module.exports = {
  handler,
  basePageFiles
}