Taro3.x-React

开放式跨端跨组件解决方案，持使用 React/Vue/Nerv 等框架来开发微信 / 京东 / 百度 / 支付宝 / 字节跳动 / QQ / 飞书 / 快手小程序 / H5 / RN 等应用。

组件

Taro3中，使用的是真实的React，可以从React包中获取所需API。

import React, {Component, useState, useEffect} from 'react';

Taro应用由一个入口组件和至少一个页面组成。

入口组件

可以在入口组件中设置全局状态/全局生命周期。
一个入口组件（app.js）伴随一个全局配置文件（app.config.js）。
- 可以在全局配置文件中设置页面组件的路径、全局窗口、路由等信息。

页面组件

页面组件是每一项路由将会渲染的页面。
一个页面组件（index.jsx）也会有一个页面配置（index.config.js）。
- 可以在页面配置中设置页面的导航栏、背景颜色等参数。

内置组件

Taro中可以使用小程序规范的内置组件进行开发：等。
Taro3.3之后，支持使用H5标签进行开发。

自定义组件

Taro规范

在React中使用内置组件前，必须从@tarojs/components进行引入。
组件属性遵从大驼峰式命名规范。
内置事件名以on开头，遵从小驼峰命名规范。
React中点击事件使用onClick。

导航栏（tabBar）

tabBar是Taro内置的导航栏，在app.config.js中进行配置。
list接受一个数组，对少配置2个，最多配置5个。

export default defineAppConfig({
  pages: [
    'pages/index/index',
    'pages/hot/hot',
    'pages/latest/latest',
  ],
  tabBar: {
    color: '#000',
    selectedColor: '#fff',
    list: [
      {
        iconPath: 'resource/index.png',
        selectedIconPath: 'resource/index_on.png',
        pagePath: 'pages/index/index',
        text: '首页',
      },
      {
        iconPath: 'resource/hotest.png',
        selectedIconPath: 'resource/hotest_on.png',
        pagePath: 'pages/hot/hot',
        text: '最热',
      },
      {
        iconPath: 'resource/latest.png',
        selectedIconPath: 'resource/latest_on.png',
        pagePath: 'pages/latest/latest',
        text: '最新',
      },
    ],
  },
  window: {
    backgroundTextStyle: 'light',
    navigationBarBackgroundColor: '#fff',
    navigationBarTitleText: 'WeChat',
    navigationBarTextStyle: 'black',
  }
})

属性	类型	必填	默认值	描述
color	HexColor（十六进制颜色值）	是		tab 上的文字默认颜色，仅支持十六进制颜色
selectedColor	HexColor（十六进制颜色值）	是		tab 上的文字选中时的颜色，仅支持十六进制颜色
backgroundColor	HexColor（十六进制颜色值）	是		tab 的背景色，仅支持十六进制颜色
borderStyle	String	是	black	tabbar 上边框的颜色，仅支持 black / white
list	Array	是		tab 的列表，详见 list 属性说明，最少 2 个、最多 5 个 tab
position	String	否	bottom	tabBar 的位置，仅支持 bottom / top
custom	Boolean	否	false	自定义 tabBar

生命周期

入口组件

onLaunch(options)

小程序初始化完成时，会触发onLaunch（全局只触发一次）。
在此生命周期中通过访问options参数或者调用getCurrentInstance().router，可以访问到程序初始化参数。

componentDidShow(options)

类组件中使用。
程序启动，或切前台时触发。
在此生命周期中通过访问options参数或者调用getCurrentInstance().router，可以访问到程序初始化参数。

componentDidHide()

类组件中使用。
程序切后台时触发。

onError(error)

小程序发生脚本错误或API调用报错时触发。

  import {onError} from '@tarojs/taro'
  onError(error => {
    console.log(error);
  })

onPageNotFound(Object)

程序要打开的页面不存在时触发。

import {onPageNotFound} from '@tarojs/taro'
  onPageNotFound(() => {
    console.log('onPageNotFound');
  })

onUnHandledRejection(Object)

小程序有未处理的Promise拒绝时触发。

  import {onUnhandledRejection} from '@tarojs/taro'
  onUnhandledRejection(rejection => { 
    console.log('onUnhandledRejection', rejection);
  })

页面组件

在类组件中使用。

onLoad(options)

在此生命周期中通过访问options参数或调用getCurrentInstance().router，可以访问到页面路由参数。

import { View, Text } from '@tarojs/components'
import './hot.less'

export default class Hot {
  onLoad (options) {
    console.log('onload',options)
  }
  render() {
    return (
      <View className='hot'>
        <Text>Hot!</Text>
      </View>
      )
  }
}

onUnload()

一般情况下建议使用React的componentWillUnmount生命周期处理页面卸载时的逻辑。当某些特殊情况需要在页面的onUnload的同一事件循环中实现逻辑时才使用它（如对小程序的生命周期执行顺序有强依赖关系时）。

  onUnload () {
    console.log('onunload');
  }

onReady()

从此生命周期开始可以使用createCanvasContext或createSelectorQuery等API访问小程序渲染层的DOM节点。
只有在页面组件才会触发onReady生命周期。子组件可以使用Taro内置的消息机制监听页面的onReady()生命周期。
- 当子组件是按需加载的时候，页面的onReady早已触发。

componentDidShow()

在小程序环境中对应页面的onShow（onShow用于vue框架中）。
页面显示/切入前台时触发。
只有在页面组件才会触发onShow生命周期。子组件可以使用Taro内置的消息机制监听页面的onShow()生命周期。

  componentDidShow () {
    console.log('componentDidShow');
  }

componentDidHide()

在小程序环境中对应页面的onHide（onHide用于Vue框架中）。
页面隐藏/切入后台时触发。
只有在页面组件才会触发onHide生命周期。子组件可以使用Taro内置的消息机制监听页面的onHide()生命周期。

  componentDidHide () {
    console.log('componentDidHide');
  }

onPullDownRefresh()

监听用户下拉动作。
- 需要在全局配置的window选项中或页面配置中设置：enablePullDownRefresh:true。
- 可以通过Taro.startPullDownRefresh触发下拉刷新，调用后触发下拉刷新动画，效果与用户手动下拉刷新一致。
- 当处理完数据刷新后，Taro.stopPullDownRefresh可以停止当前页面的下拉刷新。

onReachBottom()

需要enablePullDownRefresh配置。
监听用户上拉触底事件。
- 可以在全局配置的window选项中或页面配置中设置触发距离onReachBottomDistance。
- 在触发距离内滑动期间，本事件只会被触发一次。

onPageScroll(Object)

需要enablePullDownRefresh配置。
监听用户滑动页面事件。

onAddToFavorites(Object)

Taro3.0.3版本开始支持。
监听用户点击右上角菜单“收藏”按钮的行为，并自定义收藏内容。

onAddToFavorites (res) {
    console.log('res',res);
    return {
      title: 'AAA',
      imageUrl: '',
      query:''
    }
}

onShareAppMessage(Object)

监听用户点击页面内转发按钮（Button组件openType='share'）或右上角菜单“转发”按钮的行为，并自定义转发内容。
当onShareAppMessage没有触发时，在页面配置中设置enableShareAppMessage:true。
只有定义了此事件处理函数，右上角菜单才会显示“转发”按钮。

//hot.config.ts
export default {
  enableShareAppMessage:true
}

  onShareAppMessage(res) {
    console.log(res);
    if (res.from === 'menu') {
      // 来自页面内转发按钮
      console.log(res.target)
    }
    return {
      title: 'AAA',
      path: 'pages/hot/hot' ,
    }
  }

参数	类型	说明
from	String	转发事件来源。 button：页面内转发按钮； menu：右上角转发菜单
target	Object	如果 `from` 值是 `button`，则 `target` 是触发这次转发事件的 `button`，否则为 `undefined`
webViewUrl	String	页面中包含 `WebView` 组件时，返回当前 `WebView` 的 url

return一个object用于自定义转发内容

字段	类型	说明
title	转发标题	当前小程序名称
path	转发路径	当前页面 path ，必须是以 / 开头的完整路径
imageUrl	自定义图片路径，可以是本地文件路径、代码包文件路径或者网络图片路径。支持 PNG 及 JPG 。显示图片长宽比是 5:4	使用默认截图

onShareTimeline()

Taro3.0.3版本开始支持。
监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。
当onShareTimeline没有触发时，在页面配置中设置enableShareTimeline:true。
只有定义了此事件处理函数，同时监听了onShareAppMessage，右上角菜单才会显示“分享到朋友圈”按钮。

  onShareAppMessage(res) {
    console.log(res);
    if (res.from === 'menu') {
      // 来自页面内转发按钮
      console.log(res.target)
    }
    return {
      title: 'AAA',
      path: 'pages/hot/hot' ,
    }
  }

  onShareTimeline() {
    console.log('onShareTimeline');
    return {
      title: 'AAA',
      query: ''
    }
  }

onResize()

小程序屏幕旋转时触发。

onTabItemTap(Object)

点击Tab时触发。

  onTabItemTap(res) {
    console.log('onTabItemTap',res);
  }

参数	类型	说明
index	String	被点击 tabItem 的序号，从 0 开始
pagePath	String	被点击 tabItem 的页面路径
text	String	被点击 tabItem 的按钮文字

onSaveExitState

Taro3.5.0+开始支持。
每当小程序可能被销毁之前，页面回调函数onSaveExitState会被调用，可以进行退出状态的保存。

onTitleClick()

只有支付宝小程序支持。
点击标题触发。

onOptionMenuClick()

只有支付宝小程序支持。
点击导航栏额外图标触发。

onPopMenuClick()

只有支付宝小程序支持。

onPullIntercept()

只有支付宝小程序支持。
下拉截断时触发。

Hooks

函数式组件中使用。
Taro专有的钩子从@tarojs/taro中引入，框架自己的Hooks从对应的框架引入。

import {usePageScroll, useReachBottom} from '@tarojs/taro';
import {useState, useEffect} from 'react';

Taro Hooks

函数式组件中使用。

useLaunch

Taro3.5.0+开始支持。
等同于App入口的onLaunch生命周期钩子。

import { PropsWithChildren } from 'react'
import { useLaunch } from '@tarojs/taro'
import './app.less'

function App({ children }: PropsWithChildren<any>) {

  useLaunch(options => {
    console.log('useLaunch',options);
  })

  // children 是将要会渲染的页面
  return children
}

export default App

属性	类型	说明
path	string	启动小程序的路径
scene	number	启动小程序的场景值
query	object	启动小程序的query参数
referrerInfo	object	来源信息。从另一个小程序、公众号或App进入小程序时返回，否则返回{}
shareTicket	string

useError

Taro3.5.0+开始支持。
等同于App入口的onError生命周期钩子。

usePageNotFound

Taro3.5.0+开始支持。
等同于App入口的onPageNotFound生命周期钩子。

uesUnhandleRejection

Taro3.5.10+开始支持。
等同于App入口的onUnhandleRejection生命周期钩子。

useRouter

等同于Class Component的getCurrentInstance().router。

useLoad

Taro3.5.0+开始支持。
等同于页面的onLoad生命周期钩子。

useReady

等同于页面的onReady生命周期钩子。
从此生命周期开始，可以使用createCanvasContext或createSelectorQuery等API访问小程序渲染层的DOM节点。

useDidShow

页面显示/切入前台时触发。
等同于componentDidShow页面生命周期钩子。

useDidHide

页面隐藏/切入后台时触发。
等同于componentDidHide页面生命周期钩子。

useUnload

Taro3.5.0+开始支持。
等同于页面的onUnload生命周期钩子。

unPullDownRefresh

监听用户下拉动作。
等同于onPullDownRefresh页面生命周期钩子。

useReachBottom

监听用户上拉触底事件。
等同于onReachBottom页面生命周期钩子。

usePageScroll

监听用户滑动页面事件。
等同于onPageScroll页面生命周期钩子。

useResize

小程序屏幕旋转时触发。
等同于onResize页面生命周期钩子。

useShareAppMessage

Taro3.0.3开始，使用此Hook时必须为页面配置enableShareAppMessage:true。
监听用户点击页面内转发按钮（Button组件openType='share'）或右上角菜单“转发”按钮的行为，并自定义转发内容。
等同于onShareAppMessage页面生命周期钩子。

useTabItemTap

点击tab时触发。
等同于onTabItemTap页面生命周期钩子。

useAddToFavorites

Taro3.0.3开始支持，只有微信小程序支持。
监听用户点击右上角“收藏”按钮的行为，并自定义收藏内容。等同于 onAddToFavorites 页面生命周期钩子。

useShareTimeline

Taro 3.0.3 开始支持,只有微信小程序支持。
使用时，必须为页面配置 enableShareTimeline:true。
监听右上角菜单“分享到朋友圈”按钮的行为，并自定义分享内容。等同于 onShareTimeline 页面生命周期钩子。

useSaveExitState

Taro3.5.0+开始支持，只有微信小程序支持。
每当小程序可能被销毁之前，页面回调函数onSaveExitState会被调用，可以进行退出状态的保存。

useTitleClick

只有支付宝小程序支持。
等同于onTitleClick页面生命周期钩子。
点击标题触发。

useOptionMenuClick

只有支付宝小程序支持。
等同于onOptionMenuClick页面生命周期钩子。
点击导航栏额外图标触发。

usePullIntercept

只有支付宝小程序支持。
等同于onPullIntercept。

React Hooks

路由

路由配置

Taro遵循微信小程序的路由规范，只需要修改全局配置的pages属性，配置为Taro应用中每个页面的路径即可。

路由跳转

Taro.switchTab(option)

跳转到tabbar页面，并关闭其他所有非tabbar页面。

Taro.reLaunch(option)

关闭所有页面，打开到应用内的某个页面。

Taro.redirectTo(option)

关闭当前页面，跳转到应用内的某个页面。但是不允许跳转到tabbar页面。

Taro.navigateTo(option)

保留当前页面，跳转至应用内的某个页面。但不能跳到tabbar页面。小程序页面栈最多十层。

Taro.navigateBack(option)

关闭当前页面，返回上衣页面或多级页面。可通过getCurrentPages获取当前的页面栈，决定需要返回几层。
H5: 若入参 delta 大于现有页面数时，返回应用打开的第一个页面（如果想要返回首页请使用 reLaunch 方法）。

EventChannel

页面间事件通信通道。

路由传参

可以通过在所有跳转的url后面添加查询字符串参数进行跳转传参。

获取路由参数

跳转成功后，在目标页面的生命周期方法中，可以通过Taro.getCurrentInstance().router.params获取路由参数。

路由库

组件库

首字母大写与驼峰式命名。
组件的事件传递都要以on开头。

视图容器

CoverImage

覆盖在原生组件之上的图片视图。可覆盖的原生组件同cover-view，支持嵌套在cover-view里面。
展示一个占据父容器宽度的图片，常用于文章封面、商品主图等场景，提供一种全屏或区块的视觉效果。它会使图片按原图宽高比缩放，以适应容器的宽度，并保持图片的长宽比不变。
src为必填参数。

import { View, Text, CoverImage } from '@tarojs/components'
import './latest.less'

export default function News() {

  return (
    <View className='latest'>
      <Text>News!</Text>
      <CoverImage src='https://img2.baidu.com/it/u=2124848576,3207513143&fm=253&app=120&size=w931&n=0&f=JPEG&fmt=auto?sec=1718989200&t=a8243be687d5c968096c541d713209d8'></CoverImage>
    </View>
  )
}

CoverView

覆盖在原生组件之上的文本视图。可覆盖的原生组件包括 map、video、canvas、camera、live-player、live-pusher 只支持嵌套 cover-view、cover-image，可在 cover-view 中使用 button。

CustomWrapper

自定义组件包裹器，当数据更新层级较深时，可用此组件将需要更新的区域包裹起来，这样更新层级将大大减少。

export default function Index() {

  return (
    <View className='index'>
      <CustomWrapper>
        <Text>Hello world!</Text>
      </CustomWrapper>
    </View>
  )
}

MatchMedia

media query匹配检测节点。可以指定一组media query规则，满足时，这个节点才会被展示。通过这个节点可以实现“页面宽高在某个范围时才展示某个区域”这样的效果。

//News！只有在高度达到30000px时才会展示
export default function News() {

  return (
    <View className='hot'>
      <MatchMedia minHeight={30000}>
        <Text>News!</Text>
      </MatchMedia>
      <CoverImage src='https://img2.baidu.com/it/u=2124848576,3207513143&fm=253&app=120&size=w931&n=0&f=JPEG&fmt=auto?sec=1718989200&t=a8243be687d5c968096c541d713209d8'></CoverImage>
    </View>
  )
}

参数	类型	必填	说明
minWidth	number	否	页面最小宽度（ px 为单位）
maxWidth	number	否	页面最大宽度（ px 为单位）
width	number	否	页面宽度（ px 为单位）
minHeight	number	否	页面最小高度（ px 为单位）
maxHeight	number	否	页面最大高度（ px 为单位）
height	number	否	页面高度（ px 为单位）
orientation	string	否	屏幕方向（ landscape 或 portrait ）

MovableArea

movable-view的可移动区域。

MovableView

可移动的视图容器，在页面中可以拖拽滑动。movable-view必须在movable-area组件中，并且必须是直接子节点，否则不能移动。

粉色块可拖拽

export default function News() {

  return (
    <View className='hot'>
      <MovableArea style='height: 200px; width: 200px; background: skyblue;'>
        <MovableView style='height: 70px; width: 70px; background: pink;' direction='all'>Movable</MovableView>
      </MovableArea>
    </View>
  )
}

NativeSlot

编译的原生组件支持使用slot插槽。

PageContainer

页面容器
小程序如果在页面内进行复杂的界面设计（如在页面内弹出半屏的弹窗、在页面内加载一个全屏的子页面等），用户进行返回操作会直接离开当前页面，不符合用户预期，预期应为关闭当前弹出的组件。为此提供“假页”容器组件，效果类似于 popup 弹出层，页面内存在该容器时，当用户进行返回操作，关闭该容器不关闭页面。返回操作包括三种情形，右滑手势、安卓物理返回键和调用 navigateBack 接口。
当前页面最多只有 1 个容器，若已存在容器的情况下，无法增加新的容器。
wx.navigateBack 无法在页面栈顶调用，此时没有上一级页面。

RootPortal

root-portal使整个子树从页面脱离出来。主要用于制作弹窗、弹出层等。

点击之后：

export default function Index() {
  const [show, setShow] = useState(false)
  const toggle = () => {
    setShow(!show)
  }

  return (
    <View className='index'>
      <Button onClick={toggle}>显示root-portal</Button>
        {
          show && (<RootPortal><View>content</View></RootPortal>)
        }
    </View>
  )
}

Script

类似微信小程序的wxs标签，支持引用各种小程序的xs文件，只能在CompileMode中使用。

ScrollView

可滚动视图区域。使用竖向滚动时，需要给scroll-view一个固定高度，通过 WXSS 设置 height。组件属性的长度单位默认为 px。

Slot

slot插槽。

Swiper

滑块视图容器。其中只可以放置swiper-item组件，否则会导致未定义行为。

SwiperItem

仅可放置在 swiper 组件中，宽高自动设置为100%。
不要为SwiperItem设置style属性，可以通过class设置样式。

export default function Index() {

  return (
    <Text>Hello world!</Text>
    <Swiper style={{height:300}} indicatorColor='#999' indicatorActiveColor='#333' vertical circular indicatorDots autoplay>
        <SwiperItem>
          <View><CoverImage src='https://img2.baidu.com/it/u=2124848576,3207513143&fm=253&app=120&size=w931&n=0&f=JPEG&fmt=auto?sec=1718989200&t=a8243be687d5c968096c541d713209d8'></CoverImage>            </View>
        </SwiperItem>
        <SwiperItem>
          <View><CoverImage src='https://img0.baidu.com/it/u=508513605,220007307&fm=253&app=120&size=w931&n=0&f=JPEG&fmt=auto?sec=1718989200&t=fad0fd4334133b50dfe55a1219e5b933'></CoverImage>            </View>
        </SwiperItem>
      </Swiper>
    </View>
  )
}

View

视图容器。

基础内容

Icon

图标。组件属性的长度单位默认为px。

参数	说明
success	成功图标
success_no_circle	成功图标（不带外圈）
info	信息图标
warn	警告图标
waiting	等待图标
cancel	取消图标
download	下载图标
search	搜索图标
clear	清除图标
circle	圆环图标(多选控件图标未选择)「微信文档未标注属性」
info_circle	带圆环的信息图标「微信文档未标注属性」

export default function News() {

  return (
    <View className='hot'>
      <Icon size='60' type='success' />
      <Icon size='60' type='info' />
      <Icon size='60' type='warn' color='#ccc' />
      <Icon size='60' type='warn' />
      <Icon size='60' type='waiting' />
      <Icon size='20' type='success_no_circle' />
      <Icon size='20' type='warn' />
      <Icon size='20' type='success' />
      <Icon size='20' type='download' />
      <Icon size='20' type='clear' color='red' />
      <Icon size='20' type='search' />
    </View>
  )
}

Text

文本。

Progress

进度条。组件属性的长度单位默认为px。

RichText

富文本。
使用ts时，需要手动引入props类型。

import { View, RichText } from '@tarojs/components'
//使用ts时引入node数据类型
import { RichTextProps } from '@tarojs/components/types/RichText'
export default function Index() {

  const nodes: RichTextProps['nodes'] =[{
      name: 'div',
      attrs: {
        class: 'div_class',
        style: 'line-height: 60px; color: pink;'
      },
      children: [{
        type: 'text',
        text: 'Hello World!'
      }]
    }]
  return (
    <View className='index'>
      <RichText nodes={nodes} />
    </View>
  )
}

参考：Taro官方文档

Taro从入门到出门

Taro3.x-React

组件

入口组件

页面组件

内置组件

自定义组件

Taro规范

导航栏（tabBar）

生命周期

入口组件

onLaunch(options)

componentDidShow(options)

componentDidHide()

onError(error)

onPageNotFound(Object)

onUnHandledRejection(Object)

页面组件

onLoad(options)

onUnload()

onReady()

componentDidShow()

componentDidHide()

onPullDownRefresh()

onReachBottom()

onPageScroll(Object)

onAddToFavorites(Object)

onShareAppMessage(Object)

onShareTimeline()

onResize()

onTabItemTap(Object)

onSaveExitState

onTitleClick()

onOptionMenuClick()

onPopMenuClick()

onPullIntercept()

Hooks

Taro Hooks

useLaunch

useError

usePageNotFound

uesUnhandleRejection

useRouter

useLoad

useReady

useDidShow

useDidHide

useUnload

unPullDownRefresh

useReachBottom

usePageScroll

useResize

useShareAppMessage

useTabItemTap

useAddToFavorites

useShareTimeline

useSaveExitState

useTitleClick

useOptionMenuClick

usePullIntercept

React Hooks

路由

路由配置

路由跳转

Taro.switchTab(option)

Taro.reLaunch(option)

Taro.redirectTo(option)

Taro.navigateTo(option)

Taro.navigateBack(option)

EventChannel

路由传参

获取路由参数

路由库

组件库

视图容器

CoverImage

CoverView

CustomWrapper

MatchMedia

MovableArea