Skip to main content
Version: 3.x

Using HTML Tags

Taro v3.3+ support started

Over the years, we have accumulated a lot of excellent libraries and components on the web side, and we want to reuse them directly on the mini program side. In addition, we want to reduce the cost of migrating H5 apps to the mini program side, and even run them directly on the mini program side. Therefore, from v3.3 onwards, we support writing Taro apps using HTML tags.

How to use

Configuration Plugin

  1. First download and install the plugin @tarojs/plugin-html
yarn add @tarojs/plugin-html
  1. Then add the use of the plugin in the project configuration
// config/index.js
config = {
// ...
plugins: ['@tarojs/plugin-html']
}

Sample Code

Sample Code
function Index () {
return (
<div>Hello World!</div>
)
}

Sample Project

Default browser style

Taro provides two built-in browser default styles that can be introduced according to project needs.

As a rule of thumb, web-side projects often write styles to reset some of the browser defaults, so in general developers do not need all of these defaults. We recommend manually selecting the default styles needed by the project and adding them to the global styles.

1. HTML4

Built-in styles for W3C HTML4. Only HTML4 tag styles are available, smaller and more compatible to fit most situations.

Usage:

app.js
import '@tarojs/taro/html.css';

2. HTML5

Chrome(Blink) Built-in styles for HTML5. The built-in styles are rich and include most HTML5 tags, are large and do not necessarily support all mini program containers.

Usage:

app.js
import '@tarojs/taro/html5.css';

The size of the third-party component library has doubled

Taro will use postcss to scale px to rpx by default, see Design Draft and Size Units for details.

However, many third-party H5 component libraries do not need to parse px units, and users can configure the pxtransformBlackList option of the @tarojs/plugin-html plugin to filter.

<span> Default representation is block-level style

<span> is an inline element and would have been mapped to the <Text> component, which is also an inline element.

The <Text> component of the mini program has a limitation that it can only nest <Text> itself; nesting <View>, <Image>, and other components will not be displayed. That is, if <span> is mapped to <Text>, <span> can only nest <i>, <b>, and other in-line elements that are also mapped to <Text>.

However, when adapting some H5 component libraries, we found that <span> is likely to have <div>, <img> and other tags nested inside it, and the usage is very diverse. So we decided to map <span> to <View> to be compatible with the diversity of H5 tag writing.

The downside of this is that developers need to use their own style order <span> to behave as an in-line style by default: <span>.

app.css
// Method 1: Use only some of the required browser default styles
.h5-span {
display: inline;
}

// Method 2: Directly introduce a full set of browser default styles
import '@tarojs/taro/html.css';

As for inline tags such as <i>, they are still mapped to <Text> by default. If you need to change the mapping policy, you can configure the modifyElements option of the @tarojs/plugin-html plugin.

Partial CSS selectors are not supported

Some CSS selectors will not take effect in the mini program, eg.

  • Wildcard *
  • Media queries
  • Property selector, when the property is not a built-in property of the corresponding mini program component

The use of rem is not supported.

rem is not supported at this time.

Other limitations

There are significant differences between HTML standards and mini program standards, some of which Taro was able to smooth out, but there are still some differences that cannot be handled.

Form Components

The major difference between the two specifications for HTML tags and mini program components is mainly in the form component.

  1. When using <input type='checkbox'> or <input type='radio'>, the <CheckboxGroup>, <RadioGroup> components need to be supplemented manually.
  2. HTML uses <select> + <option> to implement selectors, while mini program use <Picker>. The two are very different, so they are not mapped. When the user uses <select>, the user is prompted to use the <Picker> component directly.

Cannot get element size synchronously

In H5 we can call the DOM API Sync to get the size of the element.

h5
const el = document.getElementById('#inner')
const res = el.getBoundingClientRect()
console.log(res)

But in the mini program, the API for getting the element size is asynchronous.

mini program
const query = Taro.createSelectorQuery()
query.select('#inner')
.boundingClientRect()
.exec(res => {
console.log(res)
})

But in the mini program, the API for getting the element size is asynchronous. So Taro provides asynchronous versions of these APIs, such as getBoundingClientRect. (If you miss any, you can submit Issues for official additions)

Taro
const el = document.getElementById('#inner')
const res = await el.getBoundingClientRect()
console.log(res)

DOM API Differences

Elements such as canvas, video, audio, etc. can call the methods on HTMLElement directly on the H5 side.

h5
const el = document.getElementById('myVideo')
el.play()

However, in Taro, to call a native method on a component, you must first create the corresponding Context.

mini program
const ctx = Taro.createVideoContext('myVideo')
ctx.play()

<img> Image Size Problem

In H5, when the width of <img> is not set, the browser will use the width of the original image as the width of the tag.

In the mini program, if the width and height of <Image> is not set, the width and height specified in the default style will be used.

Solution: The user must explicitly set the width and height of <img> when using it.

ReactDOM partial API is not supported

Taro uses React Reconciler to implement a custom renderer, which is very lean compared to the ReactDOM.

Therefore, some H5 components based on ReactDOM implementation will not work, such as using: unstable_renderSubtreeIntoContainer.

React Portal is not supported

Vue3 Teleport is not supported

SVG is not supported

The use of SVG is not supported at this time.

Plugin Configuration Items

pxtransformBlackList

regexp array

A class name selector that hits any regular expression in the array will not have the px units in its style declaration block parsed by Taro.

Usage:

config/index.js
config = {
plugins: [
['@tarojs/plugin-html', {
// The px units in class name selectors containing `demo-`, `van-` will not be resolved
pxtransformBlackList: [/demo-/, /van-/]
}]
]
}

modifyElements

function

修改普通块级元素和行内元素的映射规则。

用法:

config/index.js
config = {
plugins: [
['@tarojs/plugin-html', {
modifyElements (inline: string[], block: string[]) {
// Add <xxx> to inline elements
inline.push('xxx')
// Add <span> to inline elements and remove <span> from block level elements
inline.push('span')
block.splice(block.indexOf('span'), 1)
}
}]
]
}

enableSizeAPIs

boolean

Default value: true

Sets whether the asynchronous version of the H5 API for synchronously getting the size of an element, such as getBoundingClientRect, can be used.

Usage:

config/index.js
config = {
plugins: [
['@tarojs/plugin-html', {
// The code for these asynchronous APIs will be removed from the runtime code
enableSizeAPIs: false
}]
]
}

Detailed Design

RFC Documentation《0004-rendering-html》

Appendix

一、Tag name mapping rules

HTML TagMini program components
Block level Tagview
Inline level Tagtext
spanview
imgimage
anavigator
a["href=javascript;"]view
inputinput
input["type=checkbox"]checkbox
input["type=radio"]radio
buttonbutton
textareatextarea
progressprogress
labellabel
formform
audioaudio
canvascanvas
videovideo
iframeweb-view
slotslot

二、Property Name Mapping Rules

1. HTML <a> Tag

<a> Property<Navigator> Property
hrefurl
targetopenType

1.1 The value of the target attribute of the <a> tag corresponds to:

a[target] Property ValueNavigator[open-type] Property Value
_blanknavigate
_selfredirect

2. HTML <input> Tag

<input> Property<Input> Property
autofocusfocus
readonlydisabled

2.1 Correspondence between the values of the type attribute of the <input> tag:

input[type] Property ValueInput[type] Property Value
telnumber
input[type=password]input[password=true]

3. HTML <textarea> Tag

<textarea> Property<Textarea> Property
autofocusfocus
readonlydisabled

4. HTML <progress> Tag

<progress> Property<Progress> Property
value / max * 100precent

5. HTML <button> tag's type attribute value correspondence

button[type]Button[form-type]
button[type=submit]Button[form-type=submit]
button[type=reset]Button[form-type=reset]

三、Event Mapping Rules

1. General rule

HTML EventMini program Component Events
clicktap

2. HTML <input> Tag

<input> Event<Input> Event
onChangeonInput
keypressonConfirm

2. HTML checkbox controls

input[type=checkbox] Event<Checkbox> Event
onChangebindtap

3. HTML radio controls

input[type=radio] Event<Radio> Event
onChangebindtap