Taro从入门到出门Taro3.0开放式跨端跨组件解决方案，持使用 React/Vue/Nerv 等框架来开发 微信 / - 掘金

Taro3.x-React

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

组件

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

ts

体验AI代码助手

代码解读

复制代码

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个。

ts

体验AI代码助手

代码解读

复制代码

`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调用报错时触发。

ts

体验AI代码助手

代码解读

复制代码

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

onPageNotFound(Object)

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

ts

体验AI代码助手

代码解读

复制代码

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

onUnHandledRejection(Object)

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

ts

体验AI代码助手

代码解读

复制代码

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

页面组件

  • 在类组件中使用。

onLoad(options)

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

ts

体验AI代码助手

代码解读

复制代码

`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的同一事件循环中实现逻辑时才使用它（如对小程序的生命周期执行顺序有强依赖关系时）。

ts

体验AI代码助手

代码解读

复制代码

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

onReady()

  • 从此生命周期开始可以使用createCanvasContext或createSelectorQuery等API访问小程序渲染层的DOM节点。

  • 只有在页面组件才会触发onReady生命周期。子组件可以使用Taro内置的消息机制监听页面的onReady()生命周期。

    • 当子组件是按需加载的时候，页面的onReady早已触发。

componentDidShow()

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

ts

体验AI代码助手

代码解读

复制代码

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

componentDidHide()

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

ts

体验AI代码助手

代码解读

复制代码

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

onPullDownRefresh()

  • 监听用户下拉动作。

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

onReachBottom()

  • 需要enablePullDownRefresh配置。

  • 监听用户上拉触底事件。

    • 可以在全局配置的window选项中或页面配置中设置触发距离onReachBottomDistance。
    • 在触发距离内滑动期间，本事件只会被触发一次。

onPageScroll(Object)

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

onAddToFavorites(Object)

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

ts

体验AI代码助手

代码解读

复制代码

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

onShareAppMessage(Object)

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

ts

体验AI代码助手

代码解读

复制代码

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

ts

体验AI代码助手

代码解读

复制代码

`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，右上角菜单才会显示“分享到朋友圈”按钮。

ts

体验AI代码助手

代码解读

复制代码

`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时触发。

ts

体验AI代码助手

代码解读

复制代码

`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从对应的框架引入。

ts

体验AI代码助手

代码解读

复制代码

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

Taro Hooks

  • 函数式组件中使用。

useLaunch

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

ts

体验AI代码助手

代码解读

复制代码

`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为必填参数。

tsx

体验AI代码助手

代码解读

复制代码

`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

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

tsx

体验AI代码助手

代码解读

复制代码

`export default function Index() {
return (
<View className='index'>
<CustomWrapper>
<Text>Hello world!</Text>
</CustomWrapper>
</View>
)
}`

MatchMedia

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

tsx

体验AI代码助手

代码解读

复制代码

`//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组件中，并且必须是直接子节点，否则不能移动。

粉色块可拖拽

tsx

体验AI代码助手

代码解读

复制代码

`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使整个子树从页面脱离出来。主要用于制作弹窗、弹出层等。

点击之后：

tsx

体验AI代码助手

代码解读

复制代码

`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设置样式。

tsx

体验AI代码助手

代码解读

复制代码

`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

带圆环的信息图标「微信文档未标注属性」

tsx

体验AI代码助手

代码解读

复制代码

`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类型。

tsx

体验AI代码助手

代码解读

复制代码

`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官方文档

原网址: 访问
创建于: 2025-07-17 18:22:08
目录: default
标签: 无

未标明原创文章均为采集，版权归作者所有，转载无需和我联系，请注明原出处，南摩阿彌陀佛，知识，不只知道，要得到

请先后发表评论
  • 最新评论
  • 总共0条评论