Master uni-app: Build Cross‑Platform Apps with One Codebase

What is uni-app?

uni-app is a Vue.js‑based framework that enables developers to write one set of code and publish it to iOS, Android, H5, and multiple mini‑program platforms such as WeChat, Alipay, Baidu, Toutiao, QQ, DingTalk, and Taobao, as well as quick‑apps.

It excels in eight key indicators: developer count, case count, cross‑platform capability, extension flexibility, performance experience, surrounding ecosystem, learning cost, and development cost.

More developers and cases

Stronger cross‑platform ability and extension flexibility

Excellent performance experience

Rich surrounding ecosystem

Low learning cost (uses common front‑end stack and Vue syntax)

Low development cost (reduces recruitment, management, testing costs; HBuilder X boosts efficiency)

The functional architecture of uni-app is shown in the diagram below.

uni-app achieves cross‑platform development without sacrificing platform‑specific features, allowing elegant calls to native APIs.

uni-app Environment Setup

2.1 Install HBuilder X

Download HBuilder X from https://www.dcloud.io/hbuilderx.html. Choose the official version (Windows or macOS) and install it.

2.2 Create a Project

Two methods are available:

Use the HBuilder X visual interface: open HBuilder X, select File → New → Project , choose the uni‑app template, set a project name (e.g., uniappdemo), and click Create .

Use the vue‑cli command line:

npm install -g @vue/cli

vue create -p dcloudio/uni-preset-vue my-project

When prompted, select the Hello uni‑app template.

After creation, run the project with HBuilder X or via the command line:

npm run dev:%PLATFORM%   // run
npm run build:%PLATFORM% // publish

Supported %PLATFORM% values are listed in the table below.

Value

Platform

app-plus

App platform (native package)

h5

Web H5 version

mp-alipay

Alipay mini‑program

mp-baidu

Baidu mini‑program

mp-weixin

WeChat mini‑program

mp-toutiao

ByteDance mini‑program

mp-qq

QQ mini‑program

mp-360

360 mini‑program

quickapp-webview

Quick‑app (webview)

quickapp-webview-union

Quick‑app Union

quickapp-webview-huawei

Quick‑app Huawei

App Real‑Device Run

For Android, connect the device, enable USB debugging, and select Run → Run to Phone or Emulator in HBuilder X.

Alternatively, use the emulator.

uni‑app WeChat Mini‑Program Debugging

Download the WeChat Mini‑Program Developer Tool, install it, and enable the service port in its security settings.

In HBuilder X, choose Run → Run to Mini‑Program Simulator → WeChat Developer Tool to preview the app.

H5 Run and Release

Open manifest.json in HBuilder X, configure the H5 settings (choose hash routing mode), then select Release → Website – H5 Mobile (uni‑app only) . The generated files are placed in unpackage/dist/build/h5 and can be uploaded to a web server.

Size Units, Flex Layout and Background Images

Flex Layout Overview

Flex provides flexible box layout for containers. Example CSS: .box { display: flex; } Inline flex can be used with display: inline-flex. Flex containers have a main axis and a cross axis; items are arranged along the main axis.

Container Properties

Supported properties: flex-direction, flex-wrap, flex-flow, justify-content, align-items, align-content.

Item Properties

Supported properties: order, flex-grow, flex-shrink, flex-basis, flex, align-self.

Background Images

uni‑app supports background images in CSS similar to web projects, with the following considerations:

Base64‑encoded images are universally supported.

Network URLs are supported.

Mini‑programs do not support local file paths; use base64 or network URLs. From v3 compilation mode, local images are allowed.

For small images (< 40 KB), uni‑app automatically converts them to base64. Larger images should be referenced via network URLs or manually converted.

Example CSS using an absolute path:

.test2 { background-image: url('~@/static/logo.png'); }

When using a local image in a component:

<template>
  <view>
    <view class="bg"></view>
  </view>
</template>
<script></script>
<style>
  .bg {
    width: 200rpx;
    height: 200rpx;
    background-image: url('~@/static/images/1.jpg');
    background-size: 100%;
  }
</style>

Configure the WeChat mini‑program AppID in manifest.json to avoid runtime errors.

After building, the background image is automatically converted to base64 if its size is below 40 KB.