MiniApp Common UI Components

The MiniAPP UI component is the key to creating the MiniApp page. Each component builds an independent interactive function unit by simply encapsulating data and methods. This allows developers to reuse components in MiniApp to realize functions such as view containers, texts, and forms.

This document specifics a set of standard common UI components for MiniApp, that allows the developers to develop programs by combing these components. The standard MiniApp common UI component can help to improve the cross-platform capability of MiniApp and allows codes to easily migrate to different native apps and operating systems, improving developer work efficiency.

Introduction

An Overview of MiniApp UI Components

MiniApp is a concept of light software application, that can be distributed through any digital means, and accessed through the Web. Normally, MiniApps are made of high-level building blocks called Components, which allow developers to quickly construct the UI for a MiniApp.

MiniApp common UI components are usually stored in the common directory of the MiniApp package. Each component contains the following files:

.html

.html files describe the page layout.

.css

.css files describe the page style.

.js

.js files process the interactions between pages and users.

Summarize of MiniApp UI Components

MiniApp UI components can be classified into the following types: basic component, container component, and Meida component.

Basic Components

Basic components provide the minimum interactive blocks that can be reused for the MiniApp. Developers can define the user interface of the MiniApp by combining these basic components. It may include the following components such as 'Image', 'Progress', 'Text', 'Input', 'Button', 'Label', 'Select', 'Slider', 'Switch', 'Picker', 'Video', and 'Canvas'.

Container Components

Container components provide the structure of a MiniApp page. It may inculdes the following components such as 'Div', 'List', 'Swiper', 'Tabs', and 'Refresh'.

Common Attributes

Common attributes are used to set component identities and appearance. Generally, all components support the following attributes:

Common Attributes
Attribute	Type	Mandatory	Description
`id`	string	No	Unique ID of a component.
`style`	string	No	Style declaration of a component.
`class`	string	No	Style class of a component, which is used to refer to a style table.

The following codes shown an example to introduce how to use above common attributes:

<!-- Associate this component with the style code in the .container block in example.css. -->		  
<div class="container"> 
    <text id="title" style="font-size: {{fontSize}}; color: {{fontColor}};"> 
        Hello World
    </text>
</div>

/* Class selector. All components with the container class use this style. */
.container { 
    flex-direction: column;
    display: flex;
    justify-content: center;
    align-items: center;
    left: 0px;
    top: 0px;
    width: 454px;
    height: 454px;
}

Common Events

Common events can be bound to most components.

Common Events
Attribute	Parameter	Type	Description
`Click`			Triggered when a component is clicked.
`Longpress`			Triggered when a component is long pressed.
`Swipe`	Direction	string	Triggered when a user quickly slides on a component. Sliding direction. The value can be one of the following: 1) left: Slide from right to left; 2) right: Slide from left to right; 3) up: Slide upwards; 4) down: Slide downwards
`Touchstart`	TouchEvent		This event is triggered when a finger touches the screen.
`Touchmove`	TouchEvent		This event is triggered when a finger moves on the screen.
`Touchcancel`	TouchEvent		This event is triggered when the touch operation on the screen is interrupted.
`Touchend`	TouchEvent		This event is triggered when the touch ends.

The TouchEvent defined as an object to present different touch types. The attributes of the TouchEvent object are shown as following:

TouchEvent
Attribute	Type	Description
`Touches`	Array <Object>	Attribute set of the touch event, including the information array of the touch points on the screen.
`ChangedTouches`	Array <Object>	Attribute set when a touch event occurs, including the information array of changed touch points on the screen. changedTouches has the same data format as touches and indicates touch point changes, such as from no touch point to newly generated touch points, from some touch points to no touch point, and location changes. For example, when the user's finger leaves the touchscreen, no data exists in the touches array, but changedTouches will save the generated data.

The parameters filled in Array<Object> of TouchEvent are shown as following:

Array <Object>
Attribute	Type	Description
`globalX`	Number	Horizontal distance from the upper left corner of the screen (excluding the status bar). The upper left corner of the screen acts as the coordinate origin.
`globalY`	Number	Vertical distance from the upper left corner of the screen (excluding the status bar). The upper left corner of the screen acts as the coordinate origin.
`localX`	Number	Horizontal distance from the upper left corner of the touched component. The upper left corner of the component acts as the coordinate origin.
`localY`	Number	Vertical distance from the upper left corner of the touched component. The upper left corner of the component acts as the coordinate origin.
`size`	Number	Touch area.

MiniApp UI Components Container Component

div

The 'div' component is a basic container that is used as the root node of the page structure or is used to group the content.

The 'div' component has no additional attributes except the common attributes.

The 'div' component not support additional events except the common events.

list

The 'list' component has no additional attributes except the common attributes.

In addition to common events, the component supports the following private events as well:

Events for list component
Name	Parameter	Description
`Scrollend`		Triggered when the list stops scrolling.

list-item

The 'list-item' is a child component of 'list' and is used to display items in a list.

The 'list-item' component has no additional attributes except the common attributes.

The 'list-item' component not support additional events except the common events.

swiper

The 'swiper' component provides a swiper container that enables the switch of child components.

In addition to common attributes, the 'swiper' component supports the following attributes:

Attributes for swiper component
Name	Type	Default Value	Mandatory	Description
`index`	Number	0	No	Index of the child component currently displayed in the container.
`loop`	Boolean	True	No	Whether to enable looping.
`vertical`	Boolean	False	No	Style class of a component, which is used to refer to a style table.

In addition to common events, the 'swiper' component supports the following private events as well:

Events for swiper component
Name	Parameter	Description
`change`	{index:currentIndex}	Triggered when the index of the currently displayed component changes.

tabs

The 'tabs' component is a label that is used to classify a set of attributes.

In addition to common attributes, the 'tabs' component supports the following attributes:

Attributes for tab component
Name	Type	Default Value	Mandatory	Description
`index`	Number	0	No	Index of the child component currently displayed in the container.
`vertical`	Boolean	False	No	Whether the tab is vertical. Available values are as follows: 1- false: The 'tab-bar' and 'tab-content' are arranged vertically. 2- true: The 'tab-bar' and 'tab-content' are arranged horizontally.
`disabled`	Boolean	False	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'tabs' component not support additional events except the common events.

tab-bar

The 'tab-bar' is a child component of and is used to provide the area to display tab labels. Its child components are horizontally arranged.

Attributes supported by 'tab-bar' are similar to those supported by 'tabs'. In addition to the attributes supported by 'tabs', 'tab-bar' supports the following attributes as well:

Attributes for tab-bar component
Name	Type	Default Value	Mandatory	Description
`mode`	String	scrollable	No	Extensibility of the component width. Available values are as follows: 1- scrollable: The width of a child component is the configured width. When the total width of all child components is greater than the tab-bar width, the child component can scroll horizontally. -fixed: The width of a child component equals the tab-bar width divided by the number of child components.

The 'tab-bar' component not support additional events except the common events.

tab-content

The 'tab-content' is a child component of 'tabs' and is used to provide the area for displaying the tab content. By default, its height is such that all the remaining space of the 'tabs' component is filled. The child components are arranged horizontally. When 'tab-content' is used as a child element in a container, the length on the main axis direction must be specified. Otherwise, the child element cannot be displayed.

Attributes supported by 'tab-content' are similar to those supported by 'tabs'. In addition to the attributes supported by 'tabs', 'tab-content' supports the following attributes as well:

Attributes for tab-bar component
Name	Type	Default Value	Mandatory	Description
`Scrollable`	Boolean	Truth	No	Whether the tabs can be switched by swiping left or right. The default value is true. If this attribute is set to false, tab switching is implemented only through the association with tab-bar.

The 'tab-content' component not support additional events except the common events.

tab-content

Attributes supported by 'tab-content' are similar to those supported by 'tabs'. In addition to the attributes supported by 'tabs', 'tab-content' supports the following attributes as well:

Attributes for tab-bar component
Name	Type	Default Value	Mandatory	Description
`Scrollable`	Boolean	Truth	No	Whether the tabs can be switched by swiping left or right. The default value is true. If this attribute is set to false, tab switching is implemented only through the association with tab-bar.

The 'tab-content' component not support additional events except the common events.

refresh

The 'refresh' component is used to pull down to refresh the page.

In addition to common attributes, the 'refresh' component supports the following attributes:

Attributes for refresh component
Name	Type	Default Value	Mandatory	Description
`offset`	<length>		No	Distance to the top of the parent component from the 'refresh' component that comes to rest after a successful swipe gesture.
`type`	String	auto	No	Dynamic effect when the component is refreshed. Two options are available and cannot be modified dynamically. 1-auto: default effect. When the list is pulled to the top, the list does not move. When the list is pulled to the bottom, a circle is displayed. 2- pulldown: When the list is pulled to the top, users can continue to pull down to trigger a refresh. The rebound effect will appear after the refresh. If the child component contains a list, set scrolleffect of the list to no to prevent drop-down effect conflicts.
`Refreshing`	Boolean	False	No	Whether the 'refresh' component is being refreshed.
`Lasttime`	Boolean	False	No	Whether to display the last update time. The character string format is last update time: XXXX, where XXXX is displayed based on the time and date display specifications and cannot be dynamically modified. (It is recommended that this attribute be used when type is set to pulldown. The fixed distance is at the bottom of the content drop-down area. Pay attention to the offset attribute setting to prevent overlapping.)
`Friction`	Number		No	Pull-down friction coefficient. The value ranges from 0 to 100. A larger value indicates a more responsive component. For example, if a user pulls the component down 100 px, it will actually move 100 * friction% px.
`discabled`	Boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'refresh' component not support additional events except the common events.

Basic Components

image

The 'image' component is used to render and display images.

In addition to common attributes, the 'image' component supports the following attributes:

Attributes for image component
Name	Type	Default Value	Mandatory	Description
`Src`	String		No	Image path, which supports both local and cloud paths. The supported image formats include PNG, JPG, BMP, SVG, and GIF.
`Alt`	String		No	Placeholder image displayed during image loading.
`disabled`	Boolean	False	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

In addition to common events, the component supports the following private events as well:

Events for image component
Name	Parameter	Description
`complete`	{width: width, height: height}	Triggered when an image is successfully loaded. The loaded image is returned.
`Error`	{width: width, height: height}	Triggered when an exception occurs during image loading. In this case, the width and height are 0.

progress

The 'progress' component is used to provide a progress bar that displays the progress of content loading or operation processing.

In addition to common attributes, the 'progress' component supports the following attributes:

Attributes for progress component
Name	Type	Default Value	Mandatory	Description
`Type`	String	horizontal	No	Type of the progress bar, which cannot be changed dynamically. Available values are as follows: horizontal: linear progress bar; circular: loading progress bar; ring: ring progress bar; scale-ring: ring progress bar with a scale; arc: arc progress bar.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'progress' component not support additional events except the common events.

text

The 'text' component is used to display a piece of textual information.

In addition to common attributes, the 'text' component supports the following attributes:

Attributes for text component
Name	Type	Default Value	Mandatory	Description
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'text' component not support additional events except the common events.

input

The 'input' component provides an interactive interface to receive user input. It can be a radio button, check box, button, single-line text box, and more.

In addition to common attributes, the 'input' component supports the following attributes:

Attributes for input component
Name	Type	Default Value	Mandatory	Description
`type`	String	Text	No	Type of the 'input' component. Available values include text, email, date, time, number, password, button, checkbox, and radio.
`checked`	boolean	false	No	Whether the 'input' component is selected. This attribute is valid only when type is set to checkbox or radio.
`name`	string		No	Name of the 'input' component.
`value`	string		No	Value of the 'input' component. When type is radio, this attribute is mandatory and the value must be unique for radio buttons with the same name.
`placeholder`	string		No	Content of the hint text. This attribute is available only when the component type is set to text, email, date, time, number, or password.
`maxlength`	number		No	Maximum number of characters that can be entered in the input box. If no value is specified, the number of characters is not limited.
`headericon`	string		No	Icon resource path before text input. This icon does not support click events and is unavailable for button, checkbox, and radio types. The supported icon image formats are JPG, PNG, and SVG.
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

In addition to common events, the 'input' component supports the following private events as well:

Attributes for text component
Name	Parameter	Description
`change`	{value:inputValue}	Triggered when the content entered in the text box changes. The most recent text entered by the user is returned.

button

The 'button' component includes capsule, circle, text, arc, and download buttons.

In addition to common attributes, the 'button' component supports the following attributes:

Attributes for button component
Name	Type	Default Value	Mandatory	Description
`type`	string	Text	No	Dynamic modification is not supported. If this attribute is not set, capsule-like buttons are displayed. Different from the capsule button, the four rounded corners of a capsule-like button can be configured using border-radius. Available button types are as follows, 1) capsule: a capsule button with fillets, background color, and text; 2) circle: a circle button which can be used to place icons; 3) text: a text button which displays the text only; 4) arc: an arc button. This value is applicable to wearables only. 5) download: a download button. The download progress bar is added. This value is applicable to smart TVs and smartphones.
`value`	string		No	Text value of the button. This attribute is unavailable for circle buttons.
`icon`	string		No	Path of the button icon. This parameter is valid only for the circle button. The supported icon formats are JPG, PNG, and SVG.
`waiting`	boolean		No	Waiting status. When waiting is set to true, the waiting transition is displayed on the left of the text.
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'button' component not support additional events except the common events.

label

The 'label' component defines labels for the 'input', 'button', and 'text' components. When a label is clicked, the click effect of the component associated with the label will be triggered.

In addition to common attributes, the 'label' component supports the following attributes:

Attributes for label component
Name	Type	Default Value	Mandatory	Description
`target`	string		No	Attribute ID of the target component.
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'label' component do not support any event.

select

The 'select' component provides a drop-down list that allows users to select among multiple options.

In addition to common attributes, the 'select' component supports the following attributes:

Attributes for select component
Name	Type	Default Value	Mandatory	Description
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

In addition to common events, the 'select' component supports the following private events as well:

Events for select component
Name	Parameter	Description
`change`	{newValue: newValue}	Triggered after a value is selected from the drop-down list.

slider

The 'slider' component is used to quickly adjust settings, such as volume and brightness.

In addition to common attributes, the 'slider' component supports the following attributes:

Attributes for slider component
Name	Type	Default Value	Mandatory	Description
`Min`	Number		No	Minimum value of the slider.
`Max`	Number		No	Maximum value of the slider.
`Value`	Number		No	Initial value of the slider.
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

In addition to common events, the 'slider' component supports the following private events as well:

Events for slider component
Name	Parameter	Description
`change`	{newValue: newValue}	Triggered when the value changes.

switch

The 'switch' component is used to enable or disable a function.

In addition to common attributes, the 'switch' component supports the following attributes:

Attributes for switch component
Name	Type	Default Value	Mandatory	Description
`checked`	boolean	false	No	Whether the component is checked or not.
`showtext`	boolean	false	No	Whether the component displays text.
`texton`	string	on	No	Text displayed when the component is checked.
`textoff`	string	off	No	Text displayed when the component is not checked.
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

In addition to common events, the 'switch' component supports the following private events as well:

Events for switch component
Name	Parameter	Description
`change`	{checked: checkedValue}	Triggered when the checked state changes.

picker

The 'picker' component supports common, date, time, data and time, and multi-column text selectors.

In addition to common attributes, the 'picker' component supports the following attributes:

Attributes for picker component
Name	Type	Default Value	Mandatory	Description
`type`	string		No	Dynamic modification is not supported. Available values include: 1) text: text selector; 2) data: date selector; 3) time: time selector; 4) datetime: date and time selector; 5) multi-text: multi-column text selector.
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'picker' component not support additional events except the common events.

video

The 'video' component provides a video player.

In addition to common attributes, the 'video' component supports the following attributes:

Attributes for text component
Name	Type	Default Value	Mandatory	Description
`Muted`	Boolean	false	No	Whether a video is muted.
`Src`	String		No	Path of the video content to play.
`Autoplay`	Boolean	False	No	Whether a video is played automatically after being rendered.
`poster`	string		No	Preview poster of a video.
`controls`	boolean	True	No	Whether the control bar is displayed during video playback. If the value is set to false, the control bar is not displayed. The default value is true, indicating that the platform can either show or hide the control bar.
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

In addition to common events, the 'video' component supports the following private events as well:

Events for video component
Name	Parameter	Description
`prepared`		Triggered when a video preparation is complete.
`start`		Triggered when a video is played.
`pause`		Triggered when a video is paused.
`Finish`		Triggered when the video playback is finished.
`error`		Triggered when the playback fails.
`seeking`	{currenttime: value (second)}	Triggered to report the time when the progress bar is being dragged.
`seeked`	{currenttime: value (second)}	Triggered to report the playback time when the user finishes dragging the progress bar.
`timeupdate`	{currenttime: value (second)}	Triggered once per 250 ms when the playback progress changes.
`fullscreenchange`	{fullscreen: fullscreenValue }	Triggered when a video enters or exits the full screen mode.

canvas

The 'canvas' component is used for customizing drawings.

In addition to common attributes, the 'canvas' component supports the following attributes:

Attributes for canvas component
Name	Type	Default Value	Mandatory	Description
`disable`	boolean	false	No	Whether the component is disabled. If it is disabled, it cannot respond to user interaction.
`focusable`	Boolean	Truth	No	Whether the component can gain focus. When focusable is set to true, the component can gain focus if there is a focusable child component. If this attribute is set to false, the component and its child components cannot gain focus.
`data`	String		No	Attribute set for components to facilitate data storage and reading.

The 'canvas' component not support additional events except the common events.