This page is translated by Google Cloud Translation API

Switch to Chinese

Component Usage Tutorial

• Components are the basic building blocks of the view layer.
• A component is an encapsulation of a standalone and reusable functional module.

Each component consists of several parts: a start tag and end tag marked by the component name, component content, component attributes, and attribute values.

• The component name is wrapped in angle brackets and is called a tag, which has a start tag and an end tag. The end tag uses / after < to indicate closure. The end tag is also called a closing tag. For example, <component-name> is a start tag, </component-name> is an end tag.
• The content between the start and end tags is called the component content, such as content in the example below.
• Attributes can be written on the start tag, and there can be multiple attributes separated by spaces, such as property1 and property2 in the example below. Note that attributes cannot be written on the closing tag.
• Each attribute is assigned a value using =, as in the example below where the value of property1 is set to the string "value".

Note: All component and attribute names are lowercase, and words are connected with hyphens -.

<component-name property1="value" property2="value">
	content
</component-name>

The following is an example of a basic component. A <button> component is inserted inside the root <view> component of a vue page. The content area of this component is set to the text "Button" (button), and an attribute "size" is set to "mini".

Note: According to the Vue Single File Component Specification, the root node of each vue file must be <template>. In vue2, there must be and only one root <view> component under <template>. Vue3 has no such restriction.

In vue2, there must be and only one root <view> component under <template>. Vue3 has no such restriction.

<template>
	<view>
		<button size="mini">按钮</button>
	</view>
</template>

通过了解button组件的文档，我们知道上述代码将在页面中绘制一个按钮，按钮显示的文字是“按钮”，按钮的大小是小尺寸的。 From the documentation of the button component, we know that the above code will render a button on the page, with the text "按钮" displayed and the button size set to small.

Attribute Types of Components

Component attributes have various types:

Type	Description	Notes
Boolean	Boolean value	If the attribute is present on the component, its value is always true regardless of its assigned value; only if the attribute is not present will it be false. If the attribute value is a variable, the variable will be converted to Boolean type.
Number	Number	Examples: 1, 2.5
String	String	Examples: "string"
Array	Array	Examples: [ 1, "string" ]
Object	Object	Examples: { key: value }
EventHandler	Event handler function name	handlerName refers to a function defined in methods
Any	Any attribute

The following example demonstrates setting component attributes with Boolean and Number values. Note that when using false as a JS variable in a component attribute, a : prefix is required before the attribute name. The attribute value is enclosed in quotes, but inside the quotes is JS code, not a string.

<template>
	<view>
		<button size="mini" :disabled="false" hover-start-time=20 >按钮</button>
	</view>
</template>

Common Attribute List

Each component has its own attributes, but all uni-app components share the following attributes:

Attribute Name	Type	Description	Notes
id	String	Component's unique identifier	Usually used to obtain the component context object (such as VideoContext), must be unique within the page
ref	String	Component's unique identifier in Vue	Used to register reference information for child components, see Vue Documentation
class	String	Component's CSS class	Defined in the corresponding CSS
style	String	Component's inline style	Can be dynamically set
hidden	Boolean	Whether the component is hidden	All components are shown by default
data-*	Any	Custom attribute	Data will be sent to the event handler when an event is triggered
@*	EventHandler	Component event	See detailed documentation for each component, event binding refers to event handler

Apart from the above common attributes, there are special attributes starting with v-, called Vue directives, such as v-if, v-else, v-for, v-model. See Vue Directives

Using script data variables in components

Variables defined in the script's data can be used within components, but their usage differs between attribute values and content areas.

• In the text content area, wrap the variable with double curly braces, such as below.
• When used as an attribute value, add a colon prefix before the attribute name.

The following button component example is equivalent to the previous one, except that the static content is replaced with dynamic JS.

<template>
	<view>
		<button size="mini" :disabled="buttondisble" hover-start-time=20 >{{buttonText}}</button>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				"buttondisble":false
			}
		}
	}
</script>

Component Events

Every component has "events". An event triggers a JS method under certain conditions.

For example, the button component has a click event, which is triggered when the user taps the button.

Events are also component attributes, but they use the @ prefix.

The value of the event attribute points to a JS method defined in the script's methods, and you can pass parameters to the method.

The following is an example of a component event:

• click is the click event of the button component, triggered when the user clicks the button.
• click points to the goto method defined in methods and passes in the parameter '/pages/about/about'

<template>
	<view>
		<button size="mini" @click="goto('/pages/about/about')">按钮</button>
	</view>
</template>
<script>
    export default {
        methods: {
            goto(url) {
            }
        }
    }
</script>

Basic Components

uni-app components are divided into basic components and extension components.

Basic components are built into the uni-app framework. You don't need to import or register them, and can use them directly, such as the <view> component.

All components other than basic components are called extension components. You need to import extension components into your project before you can use them.

uni-app provides a series of basic components for developers, similar to basic tag elements in HTML.

However, uni-app components are different from HTML and are similar to mini-programs, which better suit mobile usage habits.

Although HTML tags are not recommended, if you use tags like div, the compiler will convert them to view tags when compiling to non-H5 platforms. Similarly, span will be converted to text, a to navigator, and CSS selectors will also be converted. For management and consistency, it's recommended to use components like view when writing new code.

Developers can quickly build applications by combining these basic components. For reuse, you can encapsulate them into extension components.

The specification of uni-app basic components is similar to that of mini-program components. If you are familiar with mini-program development, uni-app's basic components will feel familiar. But note that event binding must use Vue's syntax, for example, bindchange="eventName" should be written as @change="eventName".

	<picker mode="date" :value="date" start="2015-09-01" end="2020-09-01" @change="bindDateChange">
		<view class="picker">
		  当前选择: {{date}}
		</view>
	</picker>

Basic Component List

Basic components are divided into more than ten categories:

View Containers:

Component Name	Description
view	View container, similar to div in HTML
scroll-view	Scrollable view container
swiper	Slider view container, used for banners
match-media	Screen adaptive component, e.g., hiding content on narrow screens
movable-area	Draggable area
movable-view	Movable view container, can be dragged or zoomed with two fingers. Must be inside movable-area component
cover-view	Text component that can overlay native components
cover-image	Image component that can overlay native components

Basic Content:

Component Name	Description
icon	Icon
text	Text
rich-text	Rich text display component
progress	Progress bar

Form Components:

Tag Name	Description
button	Button
checkbox	Multiple choice selector
editor	Rich text input box
form	Form
input	Input box
label	Label
picker	Popup list selector
picker-view	Embedded list selector in form
radio	Single choice selector
slider	Slider selector
switch	Switch selector
textarea	Multi-line text input box

Navigation:

Component Name	Description
navigator	Page link. Similar to the <a> tag in HTML

Media Components:

Component Name	Description
audio	Audio
camera	Camera
image	Image
video	Video
live-player	Live streaming player
live-pusher	Real-time audio/video recording, also called live streaming push

Map:

Component Name	Description
map	Map

Canvas:

Component Name	Description
canvas	Canvas

webview（Web-view）： Web-view:

Component Name	Description
web-view	Web browser component

Advertisement:

Component Name	Description
ad	Advertisement component
ad-draw	Immersive video stream advertisement component

Page Attribute Configuration:

Component Name	Description
custom-tab-bar	Custom bottom tab bar component
navigation-bar	Top navigation bar of the page
page-meta	Page attribute configuration node

uniCloud uniCloud:

Component Name	Description
unicloud-db component	uniCloud database access and manipulation component

Platform-specific components

There are also platform-specific components such as open-data in mini-program and nvue platforms. See the sidebar navigation for details.

The Significance of Extension Components

Although all business needs can be met with basic components, using only basic components is inefficient. In actual development, many encapsulated components are used.

For example, if you need a five-star rating component, you can get it from the DCloud plugin marketplace: https://ext.dcloud.net.cn/plugin?id=33

Import the uni-rate component into your uni-app project and use it in the desired vue page to display the five-star component.

	<!-- 在index.vue页面引用 uni-rate 组件-->
	<template>
		<view>
			<uni-rate></uni-rate><!-- 这里会显示一个五角星，并且点击后会自动亮星 -->
		</view>
	</template>

Advantages of encapsulating extension components:

• Components can be reused any number of times.
• Proper division of components helps improve application performance.
• Code organization and management are easier, with stronger extensibility, making team collaboration more convenient.
• Component-based development greatly improves development efficiency, testability, reusability, etc.

Types of Components

uni-app supports Vue components and custom mini-program components.

If you are not familiar with these two types of components, refer to their documentation.

• Vue components: Documentation
• 小程序自定义组件：其规范不是vue规范，而是小程序规范，文档
• Custom mini-program components: They follow the mini-program specification, not the Vue specification. Documentation

For daily development, it is recommended to use Vue components. uni-app's support for mini-program components is mainly for broader ecosystem compatibility.

If the extension component follows uni-app's easycom component specification, you can use it directly without registration. For example, uni-ui extension components comply with the easycom specification.

If the component does not comply with the easycom specification, you must manually import and register it in the code before use.

Besides the easycom specification, extension components also include concepts such as uni_module, datacom, native component, and uniCloud component.

The following sections will explain these concepts one by one.

easycom Component Specification

Supported since HBuilderX 2.5.5

Traditional Vue components require three steps: install, import, and register before use. easycom simplifies this to one step.

As long as the component is installed in the project's components directory or uni_modules directory and follows the components/component-name/component-name.(vue|uvue) structure (when both vue and uvue exist, uni-app prefers vue files, uni-app x prefers uvue files, details), you can use the component directly in the page without import or registration.

For example, the uni-rate component is imported to your uni-app project and stored at /components/uni-rate/uni-rate.vue

Its component name is also uni-rate, so such components do not need to be registered or imported in the script.

As follows:

<template>
		<view>
			<uni-rate></uni-rate><!-- 这里会显示一个五角星，并且点击后会自动亮星 -->
		</view>
	</template>
<script>
	// No need to import or register the uni-list component, just use it directly in the template.
	export default {
		data() {
			return {

			}
		}
	}
</script>

No matter how many components are installed under the components directory, unused components will be automatically excluded during easycom packaging, making it especially friendly for component libraries.

Component libraries can be installed in bulk, used as needed, and packaged automatically. For example, with the official uni-ui, you can select the uni-ui template when creating a new project in HBuilderX, type 'u' in the page, pull out component code blocks, select and use them directly—greatly improving development efficiency and lowering the entry barrier.

Any component downloaded from the DCloud Plugin Market that follows the components/component-name/component-name.vue structure can be used directly.

easycom is enabled automatically and does not require manual activation.

If your component name or path doesn't match the default easycom specification, you can customize matching strategies in the easycom node of pages.json. See also

If not using easycom, you must manually import and register Vue components, as shown in the three steps below:

1. Import the component
2. Register the component in components
3. Use the component in the template

	<template>
		<view>
			<uni-rate text="1"></uni-rate><!-- 3.使用组件 -->
		</view>
	</template>
	<script>
		export default {
		}
	</script>

uni_module Specification

uni_module serves not only components but also JS libraries, pages, projects, and all categories supported by the DCloud plugin market.

Components that comply with the uni_module specification are stored under the project's uni_modules directory, with each plugin ID as its directory. (Project templates are not stored in uni_modules)

Right-click in HBuilderX to easily update plugins; plugin authors can easily upload plugins.

uni_module also supports cloud-integrated plugins.

There is detailed documentation on uni_module. Please refer to uni_module specification.

uniCloud Components

uniCloud is a cloud development service provided by DCloud for uni-app.

Among uni-app's basic components, there is a special one: <unicloud-db>.

It allows direct frontend access and manipulation of uniCloud's cloud database.

See unicloud-db component documentation for details.

In addition to the built-in database component, the uni-ui extension library also includes uniCloud file selection and upload components, such as uni-file-picker

Native Components and Native Plugins

Native components in basic components

Some basic components in uni-app are native components, such as video, map...

If these components are used in Vue pages (i.e., rendered in webview), their layer will be higher than normal frontend components.

Their layers require special components like cover-view to overlay, and there are some caveats during usage.

These issues do not occur in app-nvue.

See uni-app built-in native component instructions for details.

Native plugins for uni-app App

The App side of uni-app supports native plugins, which are written in native iOS or Android languages, encapsulated as plugins, and can be called by other developers using JS.

Native plugins are divided into native component (component) and native module (module).

In fact, native component can only be used in App-nvue environment.

See uni-app native plugin development for details.

datacom

datacom

The datacom component is a data-driven component that can be cloud-integrated.

Traditional components involve only frontend concepts, while datacom bridges uniCloud cloud data, making it an essential efficiency tool for uni-app + uniCloud collaborative development.

See datacom component documentation for details.

How to encapsulate components

Encapsulating components involves multiple concepts. See Vue Component Details for more information.

Extension Components (uni-ui)

See: Introduction to uni-ui