非常详细的Taro入门教程

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

简介

Taro 是一个遵循 React 语法规范的开放式跨端跨框架解决方案&＃xff0c;支持使用 React/Vue/Nerv 等框架来开发微信/京东/百度/支付宝/字节跳动/ QQ 小程序/H5 等应用&＃xff0c;内置了UI组件&＃xff0c;还有物料市场&＃xff0c;只编写一套代码就能够适配到多端。

Tara 遵循 React 语法&＃xff0c;集成的是 Nerv 框架。

Nerv是一款基于virtual dom技术的类React UI框架&＃xff0c;它基于React标准&＃xff0c;拥有和React一致的API与生命周期。得益于与React保持一致API的特性&＃xff0c;Nerv可以无缝兼容到React的相关生态&＃xff0c;例如react-router&＃xff0c;react-redux&＃xff0c;以及使用React开发的组件&＃xff0c;所以对于旧的React项目&＃xff0c;可以无痛地将React替换成Nerv。

环境准备

Taro 仅提供一种开发方式&＃xff1a;安装 Taro 命令行工具&＃xff08;Taro CLI&＃xff09;进行开发。
在终端输入命令 npm i -g &＃64;tarojs/cli 安装 Taro CLI。
Taro CLI 依赖于 Node.js 环境&＃xff08;>&＃61;8.0.0&＃xff09;。

框架

项目目录结构

编译配置

编译配置存放于项目根目录下 config 目录中&＃xff0c;包含三个文件:

index.js: 通用配置
dev.js : 开发环境配置
prod.js : 生产环境配置

入口文件

每一个 Taro 应用都需要一个入口组件用来注册应用&＃xff0c;入口文件默认是 src/app.js。

页面文件

页面组件是每一项路由将会渲染的页面&＃xff0c;Taro 的页面默认放在 src/pages 中&＃xff0c;每一个 Taro 项目至少有一个页面组件。页面创建好后如果需要渲染展示&＃xff0c;需要在项目入口文件 app.config.js 的 pages 数组中进行指定。

文件配置

全局配置&＃xff1a;可以通过 app.config.js 的文件进行全局配置&＃xff0c; 配置页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。

一个简单的全局配置如下&＃xff1a;

// app.config.js
export default {pages: [&＃39;pages/index/index&＃39;,&＃39;pages/list/index&＃39;],window: {backgroundTextStyle: &＃39;light&＃39;,navigationBarBackgroundColor: &＃39;#fff&＃39;,}
}


未指定 entryPagePath 时&＃xff0c;数组的第一项代表初始页面。
新增/减少页面&＃xff0c;都需要对 pages 数组进行修改。

页面配置&＃xff1a;每一个页面组件&＃xff08;例如 index.js&＃xff09;也会有一个页面配置&＃xff08;例如 index.config.js&＃xff09;&＃xff0c;可以在页面配置文件中设置页面的导航栏、背景颜色等参数。

一个最简单的页面配置如下&＃xff1a;

// ./pages/index/index.jsx
export default {navigationBarTitleText: &＃39;首页&＃39;
}


配置规范基于微信小程序的全局配置进行制定&＃xff0c;所有平台进行统一。在配置文件中&＃xff0c;Taro 并不关心框架的区别&＃xff0c;Taro CLI 会直接在编译时在 Node.js 环境直接执行全局配置的代码&＃xff0c;并把 export default 导出的对象序列化为一个 JSON 文件。

因此&＃xff0c;我们必须保证配置文件是在 Node.js 环境中是可以执行的&＃xff0c;不能使用一些在 H5 环境或小程序环境才能运行的包或者代码&＃xff0c;否则编译将会失败。

项目配置

为了能够适配到各个小程序平台&＃xff0c;满足不同小程序平台配置文件不同的情况&＃xff0c; Taro 支持为各个小程序平台添加不同的项目配置文件。

通过 Taro 模板创建的项目都会默认拥有 project.config.json 文件&＃xff0c;若要兼容到其他小程序平台&＃xff0c;按如下对应规则来增加相应平台的配置文件&＃xff0c;其配置与各自小程序平台要求的一致。

组件生命周期与事件处理函数

以Hooks为例&＃xff1a;

css 工具

在 Taro 中&＃xff0c;我们可以自由地使用 CSS 预处理器和后处理器&＃xff0c;使用的方法也非常简单&＃xff0c;只要在编译配置添加相关的插件即可&＃xff1a;

// config/index.js
const config &＃61; {designWidth: 750,sourceRoot: &＃39;src&＃39;,outputRoot: &＃39;dist&＃39;,plugins: [&＃39;&＃64;tarojs/plugin-sass&＃39;, // 使用 Sass// &＃39;&＃64;tarojs/plugin-less&＃39;, // 使用 Less// &＃39;&＃64;tarojs/plugin-stylus&＃39;, // 使用 Stylus],defineConstants: {},mini: {},h5: {}
}module.exports &＃61; function (merge) {if (process.env.NODE_ENV &＃61;&＃61;&＃61; &＃39;development&＃39;) {return merge({}, config, require(&＃39;./dev&＃39;))}return merge({}, config, require(&＃39;./prod&＃39;))
}


除了 CSS 预处理器之外&＃xff0c;Taro 还支持 CSS Modules 和 CSS-in-JS。通过 自定义编译 &＃xff0c;还可以支持更多 CSS 工具。

路由功能

在 Taro 中&＃xff0c;路由功能是默认自带的&＃xff0c;不需要开发者进行额外的路由配置。

入口组件和页面组件是通过配置文件来交互的&＃xff0c;我们只需要在入口文件的 config 配置中指定好 pages&＃xff0c;然后就可以在代码中通过 Taro 提供的 API 来跳转到目的页面&＃xff0c;例如&＃xff1a;

// 跳转到目的页面&＃xff0c;打开新页面
Taro.navigateTo({url: &＃39;/pages/page/path/name&＃39;
})// 跳转到目的页面&＃xff0c;在当前页面打开
Taro.redirectTo({url: &＃39;/pages/page/path/name&＃39;
})


尺寸单位

在 Taro 中, 尺寸单位建议使用px, %&＃xff0c;Taro 默认会对所有单位进行转换。当转成微信小程序的时候&＃xff0c;尺寸单位将默认转换以 rpx为单位&＃xff0c;当转成 H5 时将默认转换以 rem 为单位。

如果你希望部分 px 单位不被转换成 rpx 或者 rem &＃xff0c;最简单的做法就是在 px 单位中增加一个大写字母&＃xff0c;例如 Px 或者 PX 这样&＃xff0c;则会被转换插件忽略。

Taro 默认以 750px 作为换算尺寸标准&＃xff0c;如果设计稿不是以 750px 为标准&＃xff0c;则需要在项目配置 config/index.js 中进行设置&＃xff0c;例如设计稿尺寸是 640px&＃xff0c;则需要修改项目配置 config/index.js 中的 designWidth 配置为 640&＃xff1a;

const config &＃61; {designWidth: 640,
}


目前 Taro 支持 750、 640 、 828 三种尺寸设计稿&＃xff0c;他们的换算规则如下&＃xff1a;

const DEVICE_RATIO &＃61; {&＃39;640&＃39;: 2.34 / 2,&＃39;750&＃39;: 1,&＃39;828&＃39;: 1.81 / 2
}


多端开发

由于不同的平台之间还是存在一些无法消除的差异&＃xff0c;所以为了更好的实现跨平台开发&＃xff0c;Taro 中提供了两种解决方案&＃xff1a;

1. 内置环境变量&＃xff1a;process.env.TARO_ENV

process.env.TARO_ENV 用于判断当前编译类型&＃xff0c;目前有 weapp / swan / alipay / h5 / rn / tt / qq / quickapp 八个取值。通过这个变量来写对应一些不同环境下的代码&＃xff0c;在编译时会将不属于当前编译类型的代码去掉&＃xff0c;只保留当前编译类型下的代码。

render () {return ({process.env.TARO_ENV &＃61;&＃61;&＃61; &＃39;weapp&＃39; && }{process.env.TARO_ENV &＃61;&＃61;&＃61; &＃39;h5&＃39; && })
}


缺点&＃xff1a;虽然可以解决大部分跨端的问题&＃xff0c;但是会让代码中充斥着逻辑判断&＃xff0c;影响代码的可维护性&＃xff0c;而且也让代码变得愈发丑陋。

2. 统一接口的多端文件

针对一项功能&＃xff0c;如果多个端之间都有差异&＃xff0c;开发者可以通过将文件修改成 原文件名.端类型 的命名形式实现多端文件。Taro 在编译时&＃xff0c;会根据编译平台类型&＃xff0c;将加载的文件变更为带有对应端类型文件名的文件&＃xff0c;从而达到不同的端加载对应文件的目的。

使用要点

• 不同端的对应文件一定要对外暴露统一接口&＃xff0c;统一调用方式&＃xff0c;接受一致的参数

• 最好有一个平台无关的默认文件&＃xff0c;这样在使用 ts 的时候也不会出现报错

• 引用文件的时候&＃xff0c;只需要写默认文件名&＃xff0c;不用带文件后缀

多端文件简单的例子&＃xff1a;

1、多端组件

// 1. 定义多端组件
-test
--test.js // Test组件默认的形式&＃xff0c;编译到微信小程序和H5之外的端
--test.h5.js // Test 组件的 H5 版本
--test.weapp.js // Test 组件的 微信小程序 版本// 2. 引用组件
import Test from &＃39;../../components/test&＃39;;


2、多端方法

// 1.定义多端方法
-utils
--set_title.js
--set_title.h5.js
--set_title.weapp.js// 2. 使用方法
import setTitle from &＃39;../utils/set_title&＃39;setTitle(&＃39;页面标题&＃39;)


跨平台组件库

相对于我们熟悉的 div、span 元素而言&＃xff0c;在 Taro 中我们要全部使用跨平台组件进行开发。

Taro 以 微信小程序组件库 为标准&＃xff0c;结合 jsx 语法规范&＃xff0c;定制了一套自己的组件库规范。基于这个原则&＃xff0c;在小程序端&＃xff0c;可以使用所有的小程序原生组件&＃xff0c;在其他端&＃xff0c;Taro提供了对应的组件库实现:

• H5 端: &＃64;tarojs/components&＃xff0c;需要引入的默认标准组件库

• RN 端: &＃64;tarojs/components-rn

开发规范

• 首字母大写与驼峰式命名

• 组件的事件传递都要以 on 开头

组件种类

使用

在使用时&＃xff0c;我们需要先从 Taro 标准组件库 &＃64;tarojs/components 引用组件&＃xff0c;再进行使用。

import Taro, { Component } from &＃39;&＃64;tarojs/taro&＃39;;
// 使用 、 组件
import { View, Text } from &＃39;&＃64;tarojs/components&＃39;;export default class C extends Component {render () {return (c component)}
}


Taro UI

Taro UI 是一款基于 Taro 框架开发的多端 UI 组件库。

特性

• 基于 Taro 开发 UI 组件

• 一套组件可以在 微信小程序&＃xff0c;支付宝小程序&＃xff0c;百度小程序&＃xff0c;H5 多端适配运行&＃xff08;ReactNative 端暂不支持&＃xff09;

• 提供友好的 API&＃xff0c;可灵活的使用组件

组件种类

使用

1. 引入组件样式

引入组件样式有三种方式&＃xff1a;

全局引入&＃xff08;JS中&＃xff09;&＃xff1a; 在入口文件app.js中引入 taro-ui 所有的样式

import &＃39;taro-ui/dist/style/index.scss&＃39; // 引入组件样式


全局引入&＃xff08;CSS中&＃xff09;&＃xff1a; 在 app.scss 样式文件中 import 组件样式并按照文档说明使用

&＃64;import "~taro-ui/dist/style/index.scss"; // 引入组件样式


按需引入&＃xff1a; 在页面样式或全局样式中 import 需要的组件样式

&＃64;import "~taro-ui/dist/style/components/button.scss"; // 引入所需的组件样式


2. 引入所需组件

// index.js
import { AtButton } from &＃39;taro-ui&＃39;;


一个使用AtButton的完整例子&＃xff1a;

// src/pages/index/index.tsx
import Taro, { Component, Config } from &＃39;&＃64;tarojs/taro&＃39;
import { View } from &＃39;&＃64;tarojs/components&＃39;
import { AtButton } from &＃39;taro-ui&＃39;
import &＃39;./index.scss&＃39;;export default class Index extends Component {config: Config &＃61; {navigationBarTitleText: &＃39;首页&＃39;}render () {return (按钮文案)}
}


/* app.scss*/
&＃64;import "~taro-ui/dist/style/index.scss";


自定义主题

Taro UI 目前只有一套默认的主题配色&＃xff0c;为满足业务和品牌上多样化的视觉需求&＃xff0c;UI 库支持一定程度的样式定制。&＃xff08;请确保微信基础库版本在 v2.2.3 以上&＃xff09;

目前支持三种自定义主题的方式&＃xff0c;可以进行不同程度的样式自定义&＃xff1a;

• SCSS 变量覆盖

• globalClass 全局样式类

• 配置 customStyle 属性&＃xff08;仅有部分组件支持&＃xff0c;请查看组件文档&＃xff0c;不建议使用&＃xff09;

SCSS 主题变量覆盖

Taro UI 的组件样式是使用 SCSS 编写的&＃xff0c;如果你的项目中也使用了 SCSS&＃xff0c;那么可以直接在项目中改变 Taro UI 的样式变量。

1. 覆写的变量&＃xff0c;需要在引入 taro ui 默认样式之前定义&＃xff0c;默认主题变量命名。

2. Slider, Switch 组件暂时不支持 SCSS 变量覆盖的方式自定义主题。

1、在app.scss文件写入以下内容&＃xff1a;

// app.scss
$color-brand: #6190E8; /* 改变主题变量 */&＃64;import "~taro-ui/dist/style/index.scss"; /* 引入 Taro UI 默认样式 */


2、在app.js中引入以上的样式文件即可

// app.js
import &＃39;./app.scss&＃39;;

改变主题变量前后对比图&＃xff1a;

全局样式类

全局样式类是微信小程序定义的一套用于修改组件内部样式的方案。如果希望组件外样式类能够影响组件内部&＃xff0c;可以在组件构造器中的 options.addGlobalClass 字段设置为 true&＃xff08;Taro UI 的组件均开启了此特性&＃xff09;。

addGlobalClass 只对 Page 上的 class 起作用。换言之&＃xff0c;如果在自定义的组件中使用 taro-ui&＃xff0c;是无法在自定义组件内部通过 全局样式类 的方式去更改组件样式的。

当开放了全局样式类&＃xff0c;存在外部样式无意间污染组件样式的风险。由于 Taro UI 的组件样式采用 BEM 的命名方式&＃xff0c;从一定程度上避免了样式污染的问题。

/* page/index/index.js */
import Taro from &＃39;&＃64;tarojs/taro&＃39;
import { AtButton } from &＃39;taro-ui&＃39;
import "./index.scss"export default IndexPage extends Taro.Component { render () {return }
}/*** page/index/index.scss 必须在 Page 上* .at-button 为组件内部类名&＃xff0c;只需要写一样的类名去覆盖即可**/
.my-button .at-button {color: red;
}


设计思想与编译原理

在 Taro 中先按照 Nerv语法编写一份源代码&＃xff0c;然后通过编译工具将源代码编译成对应的代码。

编译工具采用的是编译原理的思想&＃xff0c;所谓编译原理&＃xff0c;就是一个对输入的源代码进行语法分析&＃xff0c;语法树构建&＃xff0c;随后对语法树进行转换操作再解析生成目标代码的过程。

Taro标准&＃xff1a;抹平多端差异

基于编译原理&＃xff0c;可以将 Taro 源码编译成不同端上可以运行的代码了&＃xff0c;但是这对于实现多端开发还是远远不够。不同的平台都有自己的特性&＃xff0c;每一个平台都不尽相同&＃xff0c;这些差异主要体现在不同的组件标准与不同的 API 标准以及不同的运行机制上。

以小程序和 Web 端为例&＃xff1a;

可以看出小程序和 Web 端上组件标准与 API 标准有很大差异&＃xff0c;这些差异仅仅通过代码编译手段是无法抹平的&＃xff0c;例如不能直接在编译时将小程序的  直接编译成