Frontend · Vue.js · Frontend Framework

The H5 Developer's Field Manual for uni-app

By 90后晨仔 · Aug 3, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

A web developer who tries uni-app without unlearning browser reflexes will hit silent failures—missing `window`, broken navigation, and components that never render. This translation layer between the two worlds prevents those early dead ends and makes the framework's cross-platform promise actually deliverable.

Summary

A complete migration guide maps every familiar H5 concept to its uni-app equivalent. HTML files become `.vue` single-file components with separate `<template>`, `<script>`, and `<style>` blocks. The `<div>`, `<span>`, and `<img>` tags are replaced by `<view>`, `<text>`, and `<image>` components, while `document.getElementById()` gives way to Vue's MVVM data binding—modify a JavaScript variable and the UI updates automatically. Browser APIs like `window`, `document`, `localStorage`, and `fetch()` are all unavailable outside the H5 target; uni-app supplies its own `uni.*` API surface for network requests, storage, dialogs, and navigation.

The guide also details the five distinct page-navigation APIs (`navigateTo`, `redirectTo`, `switchTab`, `reLaunch`, `navigateBack`) and their page-stack semantics, the `easycom` convention that auto-imports components when folder and file names match, and the `rpx` unit that normalizes screen widths to 750rpx for responsive layouts. A decision tree for navigation, a CSS selector compatibility table, and a full lifecycle hook reference round out the practical instruction.

Takeaways

— Every page is a `.vue` file with exactly one root element inside `<template>`, a `data()` function that drives the UI, and an `export default {}` block.

— Browser globals—`window`, `document`, `localStorage`, `fetch`—do not exist on App or mini-program targets; all platform interaction goes through `uni.*` APIs.

— DOM manipulation is replaced by MVVM data binding: assign a new value to a `data` property and every bound template expression updates automatically.

— The `easycom` convention auto-imports components when the file sits at `components/name/name.vue`; no manual `import` or `components` registration is needed.

— Five navigation APIs manage a page stack: `navigateTo` pushes, `redirectTo` replaces, `switchTab` jumps to tab bars, `reLaunch` clears the stack, and `navigateBack` pops.

— The `rpx` unit treats every screen as 750rpx wide, eliminating manual media queries for layout scaling.

— Global styles belong in `App.vue` (which has no `<template>`), and the `body` selector is replaced by `page`.

— Page lifecycle hooks—`onLoad`, `onShow`, `onReady`, `onHide`, `onUnload`—sit directly on the component options object, not inside `methods`.

Conclusions

The hardest part of adopting uni-app isn't learning Vue syntax; it's suppressing the muscle memory of `document.querySelector` and `window.location` that the browser trained into every web developer.

The `easycom` convention is a sharp double-edged sword: it eliminates boilerplate but silently fails on case mismatches or missing folders, giving newcomers no error message to debug.

uni-app's API surface deliberately mirrors WeChat Mini Program's `wx.*` namespace, which means the framework inherits both the design decisions and the limitations of the mini-program ecosystem.

The 10-layer page-stack limit on WeChat Mini Programs is a runtime constraint that has no equivalent in traditional web navigation, and hitting it at runtime produces a silent failure rather than a clear error.

Concepts & terms

easycom

uni-app's automatic component-import system that scans the `components/` and `uni_modules/` directories at compile time. When a component's folder name and `.vue` file name match exactly (e.g., `components/my-button/my-button.vue`), the tag `<my-button />` works in any template without an explicit `import` or `components` registration.

rpx

A responsive pixel unit in uni-app where every screen is defined as 750rpx wide regardless of its physical pixel count. A 375px-wide iPhone 6 design draft translates to 2rpx per physical pixel, while a 750px-wide draft maps 1:1.

Page stack

A last-in-first-out data structure that tracks open pages in uni-app and mini programs. `navigateTo` pushes a page onto the stack; `navigateBack` pops it. WeChat Mini Programs enforce a hard limit of 10 stack layers.

MVVM (Model-View-ViewModel)

An architectural pattern where the View (UI) automatically reflects changes to the Model (data) through a ViewModel binding layer. In Vue and uni-app, assigning a new value to a `data` property triggers automatic DOM updates without manual element selection.

Single File Component (SFC)

A `.vue` file that encapsulates a component's template (`<template>`), logic (`<script>`), and styles (`<style>`) in one file. Each block is independent, and the `<style>` block can be scoped to prevent CSS leakage across components.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗