自 1.3.9 開始支持

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

1.3.9 對 CLI 的模板功能做了以下修改：

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

模板源

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

默認(rèn)模版源

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

配置模板源

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

git 模板源

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

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

url 模板源

指向某 zip 包的 url。

編寫模板

模板組織格式

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

單模板模式

git

倉庫根目錄存在 package.json。

模板名為倉庫名。

zip 包

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

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

模板組模式

git

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

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

zip 包

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

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

靜態(tài)模板

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

動態(tài)模板

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

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

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
}

模板語言

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

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

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

例子

// 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

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

文件路徑以 “/” 開頭，代表模板文件夾根目錄

處理函數(shù)

params: object

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

return: boolean/object

返回值說明

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

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

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

例子

當(dāng)用戶選擇了使用 typescript 時，才生成 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)用戶使用 taro create 命令創(chuàng)建頁面時，創(chuàng)建以下文件。

例子

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

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

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