Taro 3 supports running Web frameworks directly on each platform, and developers are using real frameworks like React and Vue.
However, Taro follows the WeChat mini program specification in terms of components, APIs, routing and other specifications, so there are some differences between using React in Taro and the familiar web side for developers, which will be listed in detail below.
[Breaking] Developers upgrading from Taro 1/2 to Taro 3 need to pay extra attention to
Because developers in Taro 3 are using the real React, React APIs such as
useEffect, etc. need to be fetched from the React package.
Because Taro follows the routing specification for mini program, it introduces entry component and page component concepts, which correspond to the mini program specification's entry component
app and page component
A Taro application consists of an entry component and at least one page component.
Since Taro v3.3+, development with H5 tags is supported, see Using HTML tags for details
Development in Taro can be done using built-in components of the mini program specification, such as
- Before using these built-in components in React, they must be introduced from
- Component properties follow the Big Hump naming convention.
- See the next section for the event specification: component events.
Note: If a new component or property of a component added to a platform is not yet supported by Taro, you can submit Issues and we will fix it as soon as possible.
Events are the same as on the web side. In the event callback function, the first argument is the event object, and calling
stopPropagation in the callback will stop the bubbling.
- The built-in event names start with
onand follow the camelCase naming convention.
onClickfor click events in React.
In Taro 1 & 2, Taro determines whether the events bound in the mini program template are in the form of
catch depending on whether the developer uses
e.stopPropagation(). Thus event bubbling is controlled by the mini-program.
But in Taro 3, we have implemented a system of events in the mini-program logic layer, including event triggering and event bubbling. The events bound in the mini-program template are in the form of
In general, this system of mini-program events implemented in the logic layer works properly, with event callbacks that trigger, bubble, and stop bubbling correctly.
catchtouchmove event bound to the mini-program template prevents the callback function from bubbling through in addition to preventing the view from scrolling through**, something Taro's event system cannot do.
In the previous point, we introduced the event mechanism of Taro 3. Since events are bound as
bind, you cannot use
e.stopPropagation() to prevent scroll-through.
Two solutions are summarized for the problem of rolling penetration:
Use the style to solve. Disable scrolling of penetrated components。
This is also the most recommended practice.
Taro 3.0.21 starts to support
But the map component itself is scrollable, even if its width and height are fixed. So the first approach can't handle the scrolling events that bubble up to the map component.
This is where you can add the catchMove property to the
We recommend thinking in terms of the DSL features of React and Vue, since
dataset is a feature of mini program.
dataset is a special template property that allows you to get the
dataset data in the
event object of an event callback.
This is supported by Taro, and can be obtained in the event callback object via
As mentioned in the previous point, Taro's simulation of the mini program
dataset is implemented in the logic layer of the mini program. Not really setting this property in the template.
But when there are APIs in the mini proram (e.g.
createIntersectionObserver) that get to the node of the page, they don't get it because there is no actual corresponding property on the node.
At this point, consider using the taro-plugin-inject plugin to inject some generic properties, such as:
Taro 3 implements a web-standard BOM and DOM API on the mini-program logic layer. So the
document.removeChild, and other APIs used by React are actually implemented by Taro emulation, with the end effect of rendering React's virtual DOM tree as a Web-standard DOM tree emulated by Taro.
So in Taro3, React's lifecycle trigger timing is a little different from what we normally understand in web development.
The lifecycle methods of React components are supported in Taro.
After onLoad, the page component is triggered before rendering to Taro's virtual DOM.
Triggered after the page component is rendered to Taro's virtual DOM.
Taro's virtual DOM is accessible at this point (using methods such as React ref, document.getElementById, etc.), and modifications to it are supported (setting the style of the DOM, etc.).
However, this does not mean that Taro's virtual DOM data has been transferred from the logical layer
setData to the view layer. So at this point it is not possible to get the DOM nodes of the rendering layer of the mini program by methods like
createSelectorQuery. You can only get the DOM node in onReady lifecycle.
The methods in the mini program page can also be used in Taro's page: write the methods with the same name in the Class Component and use the corresponding Hooks in the Functional Component.
- Mini Program page methods are not supported to the same extent on each end.
- Mini Program page components that use HOC wrappers must handle forwardRef or use inherited components instead of returned components, otherwise the mini program page method may not be triggered.
The use of ref in Taro is exactly the same as in React, but the "DOM" obtained is different from the browser environment and the mini program environment.
What you get with React Ref is Taro's virtual DOM, which is similar to the browser's DOM, so you can manipulate its
style, call its API, and so on.
However, Taro's virtual DOM runs on the mini program logic layer and is not a real mini program rendering layer node, and it has no information about the size, width, etc.
To get the real mini program rendering layer node, you need to call the API used to get the DOM in the mini program during the onReady lifecycle.
On the mini program side, there are some additional configuration options and things to note when using
dangerouslySetInnerHTML, please refer to "Rendering HTML" for details.
Because the development version of React is larger, Taro uses the production version of React as the default dependency when building mini programs to reduce the size of the mini program and to facilitate real-world previews during development.
However, the production version of React does not show the error stack when there is an error. So when you encounter an error like this: [Error: Minified React error #152]. You can change the mini.debugReact option in the build configuration and turn the build back on. This will cause Taro to use the development version of React and output the error stack.
- Since mini-program do not support dynamic introduction, the
React.lazyAPI cannot be used in mini-program.
- It is not possible to insert elements outside the DOM tree of a page component, so
<Portal>is not supported.
idof all components must remain unique throughout the application (even if they are on different pages), otherwise it may cause problems with events not firing.#7317