Components Overview

Introduction to the uni-app Component System

uni-app provides a rich set of cross-platform components that are encapsulated based on native components of various platforms, combining cross-platform compatibility with high performance. By using these components, developers can quickly build fully functional application interfaces.

Component Categories

uni-app components are mainly divided into the following categories:

Basic Components

Basic components are the most commonly used components for constructing the basic structure and layout of pages:

• view: View container, similar to div in HTML
• text: Text component for displaying text content
• button: Button component
• image: Image component
• scroll-view: Scrollable view area
• swiper: Swiper component
• etc.

Form Components

Form components are used to collect user input:

• form: Form container
• input: Input field
• textarea: Multi-line text input field
• checkbox: Checkbox
• radio: Radio button
• switch: Toggle switch
• slider: Slider
• picker: Popup selector
• etc.

Navigation Components

Navigation components are used for page navigation:

• navigator: Page link

Media Components

Media components are used to handle multimedia content:

• audio: Audio playback component
• video: Video playback component
• camera: Camera component
• etc.

Map Components

• map: Map component

Canvas Components

• canvas: Canvas component for drawing graphics

Open Capability Components

Open capability components are used to call platform-specific open capabilities:

• web-view: Web container
• ad: Advertisement component
• etc.

How to Use Components

Using components in uni-app is very simple, just use the corresponding tag in the template:

<template>
  <view class="container">
    <text>This is a text component</text>
    <button type="primary" @click="handleClick">This is a button</button>
    <image src="/static/logo.png" mode="aspectFit"></image>
  </view>
</template>

<script>
export default {
  methods: {
    handleClick() {
      console.log('Button was clicked');
    }
  }
}
</script>

<style>
.container {
  padding: 20px;
}
</style>

Common Component Properties

All components support the following properties:

Property Name	Type	Description	Notes
id	String	Unique identifier of the component	ID must be unique within a page
class	String	Style class of the component	Style class defined in the corresponding CSS
style	String	Inline style of the component	Inline style that can be set dynamically
hidden	Boolean	Whether the component is hidden	true means hidden, false means visible
data-*	Any	Custom attributes	Sent to event handlers when events are triggered on the component
@event-name	HandlerName	Component events	See detailed documentation for each component

Component Lifecycle

The lifecycle of uni-app components is consistent with Vue components:

• beforeCreate: Before the component instance is created
• created: After the component instance is created
• beforeMount: Before the component is mounted to the page
• mounted: After the component is mounted to the page
• beforeUpdate: Before the component is updated
• updated: After the component is updated
• beforeDestroy: Before the component is destroyed
• destroyed: After the component is destroyed

Component Data Binding

Data binding in uni-app components is consistent with Vue data binding, supporting interpolation expressions, directives, etc.:

<template>
  <view>
    <text>{{ message }}</text>
    <view v-if="showMessage">Conditionally rendered content</view>
    <view v-for="(item, index) in list" :key="index">{{ item }}</view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      message: 'Hello uni-app',
      showMessage: true,
      list: ['Item 1', 'Item 2', 'Item 3']
    }
  }
}
</script>

Component Event Handling

Event handling in uni-app components is consistent with Vue event handling, using @ or v-on to bind events:

<template>
  <view>
    <button @click="handleClick">Click me</button>
    <input @input="handleInput" v-model="inputValue" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      inputValue: ''
    }
  },
  methods: {
    handleClick(event) {
      console.log('Button was clicked', event);
    },
    handleInput(event) {
      console.log('Input content:', this.inputValue);
    }
  }
}
</script>

Custom Components

In addition to using built-in components, uni-app also supports custom components, in the same way as Vue component development:

1. Create a .vue file
2. Import and register the component in the page where it's needed
3. Use the component in the template

<!-- CustomComponent.vue -->
<template>
  <view class="custom-component">
    <text>{{ title }}</text>
    <slot></slot>
  </view>
</template>

<script>
export default {
  name: 'CustomComponent',
  props: {
    title: {
      type: String,
      default: 'Default Title'
    }
  }
}
</script>

<style>
.custom-component {
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 5px;
}
</style>

Using custom components:

<template>
  <view>
    <custom-component title="Custom Component Title">
      <text>This is slot content</text>
    </custom-component>
  </view>
</template>

<script>
import CustomComponent from '@/components/CustomComponent.vue'

export default {
  components: {
    CustomComponent
  }
}
</script>

Platform Differences

Although uni-app components are cross-platform, there may be some differences on different platforms, mainly in:

1. Component appearance and style
2. Component-specific properties
3. Component event behavior

During development, you can use conditional compilation to handle platform differences:

<template>
  <view>
    <!-- #ifdef APP-PLUS -->
    <text>This content is only displayed in App</text>
    <!-- #endif -->
    
    <!-- #ifdef MP-WEIXIN -->
    <text>This content is only displayed in WeChat Mini Program</text>
    <!-- #endif -->
    
    <!-- #ifndef H5 -->
    <text>This content is displayed on all platforms except H5</text>
    <!-- #endif -->
  </view>
</template>

Further Reading

• Basic Components
• Form Components
• Navigation Components
• Media Components
• Map Components
• Canvas Components
• Open Capability Components
• Custom Components