Version: 3.0.5

项目模板

1.3.9 开始支持

一直以来,在使用 Taro CLI 的 taro init 命令创建项目时,CLI 会提供若干内置模板给开发者选择。但是很多团队都有自己独特的业务场景,需要使用和维护的模板也不尽一致,因此从 1.3.9 开始我们把项目模板打包成一个能力赋予给开发者。

1.3.9 对 CLI 的模板功能做了以下修改:

  1. CLI 只保留最基础的 default 模板,其它模板被移除。
  2. CLI 会从 CLI 全局配置中读取模版源配置项,然后从模板源拉取模板供开发者选择。
  3. 开发者可以通过修改模板源来使用自己的模板。

模板源

模板源为 CLI 配置项的 templateSource 字段,可以使用 taro config 命令对其进行操作。

默认模版源

默认模板源为 taro-project-templates 仓库,原本内置的模板都被抽离到此处。

配置模板源

模板源支持两种格式,git 模板源url 模板源

git 模板源

  • GitHub - github:owner/name
  • GitLab - gitlab:owner/name
  • Direct - direct:url
# 初始化项目时可以使用 --clone 选项指定拉取远程模板时使用git clone
taro init --clone

url 模板源

指向某 zip 包的 url。

编写模板

模板组织格式

模板目录组织支持两种,分别是单模板模式模板组模式

单模板模式

git

仓库根目录存在 package.json。

模板名为仓库名。

zip 包

zip 包解压出单文件夹,文件夹根目录包含 package.json。

模板名为 zip 包解压出的文件夹名。

template

模板组模式

git

默认模板源,仓库根目录下存放着若干模板。

模板名对应根目录下所有文件夹名。

zip 包

zip 包解压出单文件夹,文件夹内包含若干模板。

模板名对应文件夹内所有文件夹名。

templates

静态模板

静态模板表示不带逻辑的模板,CLI 会遍历整个模板文件夹,把文件一一拷贝到目标位置。

动态模板

很多情况下需要为模板加入一些逻辑,从而根据不同的环境生成不同的模板内容。

开发者可以在模板根目录加入 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 作为模板语言,各模板文件都将接收到全局模板参数。

默认全局模板参数(模板中可直接使用的变量)
变量类型说明
projectNamestring项目名
descriptionstring项目描述
versionstringTaro CLI 版本
datestring模板创建时间戳
css'none' or 'sass' or 'stylus' or 'less'样式预处理工具
cssExtstring样式文件后缀
typescriptboolean是否使用 TS
pageNamestringtaro create 时传入的页面名称,默认 'index'
templatestring模板名称
例子
// 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 用于控制是否生成某文件,或给文件传入特定参数。

handler: object
属性类型value
文件路径function处理函数

文件路径以 “/” 开头,代表模板文件夹根目录

处理函数

params: object

属性类型说明
projectNamestring项目名
descriptionstring项目描述
versionstringTaro CLI 版本
datestring模板创建时间戳
css'none' or 'sass' or 'stylus' or 'less'样式预处理工具
typescriptboolean是否使用 TS
pageNamestring页面名称
templatestring模板名称
templatePathstring模板路径
projectPathstring目标路径
period'createApp' or 'createPage'taro init 创建项目或 taro create 创建页面

return: boolean/object

返回值说明

取值说明
true创建文件
false不创建文件
object创建文件,返回的 object 的字段会被合并到全局模板参数中。

若返回值为 object,其中某些属性有特殊作用:

属性类型说明
setPageNamestring将替换当前文件的输出路径
changeExtboolean是否自动替换文件后缀
例子

当用户选择了使用 typescript 时,才生成 global.d.tstsconfig.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,当用户使用 taro create 命令创建页面时,创建以下文件。

例子

结合 handler 字段,创建新页面。

当用户使用命令 taro create --page=detail 时,会创建 /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
}