hello-uniapp入门指南：从零开始掌握UniApp跨平台开发
项目地址: https://gitcode.com/gh_mirrors/he/hello-uniapp 引言：为什么选择UniApp与hello-uniapp？
你是否还在为开发多端应用而烦恼？需要为iOS、Android、H5、小程序分别编写不同的代码？UniApp（Universal Application）框架彻底解决了这一痛点，让你一套代码，多端运行。而hello-uniapp作为官方入门示例项目，是学习UniApp开发的最佳起点。
读完本文，你将获得：
- 快速搭建UniApp开发环境的完整步骤
- 深入理解hello-uniapp项目结构与核心配置
- 掌握UniApp组件、API与跨平台特性的实战应用
- 学会调试与发布多端应用的关键技巧
1. 开发环境搭建：两种方式快速上手
1.1 HBuilderX可视化界面创建（推荐）
HBuilderX是UniApp官方推荐的IDE，集成了开发所需的全部环境，开箱即用：
-
下载安装HBuilderX
访问HBuilderX官方下载地址，选择App开发版下载安装。 -
创建hello-uniapp项目
- 打开HBuilderX，点击菜单栏文件 > 新建 > 项目
- 选择uni-app项目类型，模板选择hello-uniapp
- 填写项目名称和存储路径，点击创建
-
运行项目
- 选中项目，点击工具栏的运行按钮
- 选择目标平台（如浏览器、微信开发者工具、Android模拟器等）
1.2 CLI命令行创建
适合习惯命令行操作的开发者：
# 安装Vue CLI
npm install -g @vue/cli
# 创建hello-uniapp项目
vue create -p dcloudio/uni-preset-vue hello-uniapp
# 进入项目目录
cd hello-uniapp
# 运行H5端
npm run dev:h5
提示：CLI方式需要提前配置Node.js环境（v12+）和相应的平台开发工具（如微信开发者工具）。
2. 项目结构深度解析
hello-uniapp项目结构遵循UniApp的标准规范，主要包含以下目录和文件：
hello-uniapp/
├── App.vue # 应用入口组件
├── main.js # 应用入口文件
├── pages.json # 页面路由配置
├── manifest.json # 应用配置文件
├── common/ # 公共工具类
├── components/ # 自定义组件
├── pages/ # 页面目录
│ ├── component/ # 内置组件示例
│ ├── API/ # API接口示例
│ ├── extUI/ # 扩展UI组件示例
│ └── template/ # 页面模板示例
├── static/ # 静态资源
└── uni_modules/ # UniApp模块市场组件
核心配置文件详解
pages.json：页面路由与窗口配置
该文件定义了应用的页面路由、窗口样式和底部选项卡（tabBar）：
{
"pages": [
{
"path": "pages/tabBar/component/component",
"style": {
"navigationBarTitleText": "内置组件"
}
}
],
"tabBar": {
"color": "#7A7E83",
"selectedColor": "#007AFF",
"list": [
{
"pagePath": "pages/tabBar/component/component",
"iconPath": "static/component.png",
"selectedIconPath": "static/componentHL.png",
"text": "内置组件"
}
]
}
}
manifest.json：应用配置
包含应用名称、appid、权限等关键信息，不同平台的配置在此区分：
{
"name": "hello uni-app",
"appid": "__UNI__HelloUniApp",
"versionName": "1.0.0",
"app-plus": {
"permissions": ["<uses-permission android:name=\"android.permission.INTERNET\"/>"]
},
"mp-weixin": {
"appid": "",
"usingComponents": true
}
}
3. 核心功能实战：从组件到API
3.1 内置组件使用示例
UniApp提供了丰富的内置组件，以下是几个常用组件的使用示例：
view组件：基础容器
<view class="container">
<view class="box">Hello UniApp</view>
</view>
<style>
.container {
padding: 20rpx;
}
.box {
width: 100%;
height: 200rpx;
background-color: #007AFF;
color: white;
text-align: center;
line-height: 200rpx;
}
</style>
button组件：交互按钮
<button type="default" @click="handleClick">默认按钮</button>
<button type="primary" loading>加载中按钮</button>
<button type="warn" disabled>禁用按钮</button>
<script>
export default {
methods: {
handleClick() {
uni.showToast({ title: '按钮点击' })
}
}
}
</script>
3.2 页面导航与路由
UniApp提供了灵活的页面导航方式：
navigator组件导航
<navigator url="/pages/detail/detail" open-type="navigate">
跳转到详情页
</navigator>
API方式导航
// 保留当前页面，跳转到新页面
uni.navigateTo({
url: '/pages/detail/detail?id=1'
})
// 关闭当前页面，返回上一页面
uni.navigateBack()
3.3 数据请求与本地存储
网络请求
uni.request({
url: 'https://api.example.com/data',
method: 'GET',
success: (res) => {
console.log(res.data)
},
fail: (err) => {
console.error(err)
}
})
本地存储
// 存储数据
uni.setStorageSync('userInfo', { name: 'UniApp', age: 3 })
// 获取数据
const userInfo = uni.getStorageSync('userInfo')
// 删除数据
uni.removeStorageSync('userInfo')
4. 跨平台特性与适配技巧
4.1 条件编译：针对不同平台编写差异化代码
UniApp支持通过条件编译语法，为不同平台编写特定代码：
<!-- #ifdef H5 -->
<view>这段代码只在H5平台显示</view>
<!-- #endif -->
<!-- #ifdef MP-WEIXIN -->
<view>这段代码只在微信小程序显示</view>
<!-- #endif -->
<script>
// #ifdef APP-PLUS
console.log('这段代码只在App平台执行')
// #endif
</script>
常用平台标识：
H5：网页平台MP-WEIXIN：微信小程序MP-ALIPAY：支付宝小程序APP-PLUS：App平台MP-BAIDU：百度小程序
4.2 窗口配置与样式适配
rpx单位：自动适配不同屏幕
UniApp引入了rpx（responsive pixel）响应式像素单位，自动适配不同屏幕宽度：
.box {
width: 200rpx; /* 在任何屏幕宽度下，200rpx约等于屏幕宽度的1/10 */
height: 100rpx;
font-size: 32rpx;
}
导航栏配置
在pages.json中配置全局或页面级导航栏：
{
"globalStyle": {
"navigationBarTitleText": "hello-uniapp",
"navigationBarBackgroundColor": "#007AFF",
"navigationBarTextStyle": "white"
},
"pages": [
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "首页"
}
}
]
}
也可通过API动态修改：
// 修改导航栏标题
uni.setNavigationBarTitle({
title: '新标题'
})
// 修改导航栏颜色
uni.setNavigationBarColor({
frontColor: '#ffffff',
backgroundColor: '#ff0000'
})
5. 项目实战：构建一个简单的列表-详情页
5.1 页面结构设计
我们将创建一个商品列表页和详情页，展示完整的页面跳转和数据传递流程。
列表页（pages/goods/list.vue）
<template>
<view class="goods-list">
<view class="goods-item" v-for="item in goodsList" :key="item.id" @click="toDetail(item)">
<image :src="item.image" class="goods-img"></image>
<view class="goods-info">
<view class="goods-title">{{ item.title }}</view>
<view class="goods-price">￥{{ item.price }}</view>
</view>
</view>
</view>
</template>
<script>
export default {
data() {
return {
goodsList: [
{ id: 1, title: 'UniApp入门教程', price: 59, image: '/static/goods1.jpg' },
{ id: 2, title: 'HBuilderX实战指南', price: 69, image: '/static/goods2.jpg' }
]
}
},
methods: {
toDetail(item) {
uni.navigateTo({
url: `/pages/goods/detail?id=${item.id}&title=${item.title}`
})
}
}
}
</script>
<style>
.goods-list {
padding: 10rpx;
}
.goods-item {
display: flex;
padding: 15rpx;
border-bottom: 1rpx solid #eee;
}
.goods-img {
width: 120rpx;
height: 120rpx;
margin-right: 20rpx;
}
.goods-title {
font-size: 32rpx;
margin-bottom: 10rpx;
}
.goods-price {
color: #f04864;
font-size: 36rpx;
}
</style>
详情页（pages/goods/detail.vue）
<template>
<view class="goods-detail">
<view class="goods-title">{{ title }}</view>
<image :src="image" class="goods-img"></image>
<view class="goods-price">￥{{ price }}</view>
<button class="buy-btn" type="primary">立即购买</button>
</view>
</template>
<script>
export default {
data() {
return {
title: '',
price: 0,
image: ''
}
},
onLoad(options) {
// 获取页面参数
this.title = options.title
this.id = options.id
// 根据ID请求商品详情数据
this.loadGoodsDetail()
},
methods: {
loadGoodsDetail() {
// 模拟API请求
setTimeout(() => {
this.price = 59
this.image = '/static/goods1.jpg'
}, 500)
}
}
}
</script>
<style>
.goods-detail {
padding: 20rpx;
}
.goods-title {
font-size: 36rpx;
text-align: center;
margin-bottom: 20rpx;
}
.goods-img {
width: 100%;
height: 400rpx;
margin-bottom: 20rpx;
}
.goods-price {
color: #f04864;
font-size: 40rpx;
text-align: center;
margin-bottom: 30rpx;
}
.buy-btn {
width: 90%;
margin: 0 auto;
}
</style>
5.2 配置路由
在pages.json中添加页面路由配置：
{
"pages": [
{
"path": "pages/goods/list",
"style": {
"navigationBarTitleText": "商品列表"
}
},
{
"path": "pages/goods/detail",
"style": {
"navigationBarTitleText": "商品详情"
}
}
]
}
6. 项目调试与多端运行
6.1 调试工具与技巧
-
HBuilderX内置调试器
运行项目后，HBuilderX会自动打开调试器，可查看控制台输出、网络请求和页面元素。 -
微信小程序调试
- 在HBuilderX中运行到微信小程序，会自动打开微信开发者工具
- 利用微信开发者工具的调试面板进行代码调试和性能分析
-
真机调试
- 连接Android或iOS设备，开启USB调试
- 在HBuilderX中选择运行 > 运行到手机或模拟器
6.2 多端运行命令
# 运行到H5
npm run dev:h5
# 运行到微信小程序
npm run dev:mp-weixin
# 运行到支付宝小程序
npm run dev:mp-alipay
# 运行到App平台
npm run dev:app-plus
7. 项目打包与发布
7.1 HBuilderX可视化打包
-
H5打包
- 点击菜单栏发行 > 网站-H5手机版
- 配置打包参数，点击发行，生成静态文件
-
小程序打包
- 点击菜单栏发行 > 小程序-微信（或其他平台）
- 在弹出的对话框中填写小程序AppID
- 点击发行，生成小程序代码包
- 在对应平台的开发者工具中上传代码
-
App打包
- 点击菜单栏发行 > 原生App-云打包
- 选择打包平台（Android/iOS）和证书配置
- 点击打包，等待打包完成后下载安装包
7.2 CLI命令打包
# 打包H5
npm run build:h5
# 打包微信小程序
npm run build:mp-weixin
# 打包App
npm run build:app-plus
8. 项目扩展：集成UI组件库
hello-uniapp已经集成了部分常用组件，你还可以通过UniApp插件市场扩展更多功能：
8.1 使用uni-ui组件库
-
安装uni-ui
在HBuilderX中，右键点击项目uni_modules > 安装uni-ui插件 -
使用组件
在页面中引入并使用组件：
<template>
<view>
<uni-card title="卡片标题" thumbnail="/static/logo.png">
<view>卡片内容</view>
</uni-card>
<uni-list>
<uni-list-item title="列表项1" rightText="箭头" showArrow></uni-list-item>
<uni-list-item title="列表项2" rightText="箭头" showArrow></uni-list-item>
</uni-list>
</view>
</template>
<script>
import uniCard from '@/uni_modules/uni-card/components/uni-card/uni-card.vue'
import uniList from '@/uni_modules/uni-list/components/uni-list/uni-list.vue'
import uniListItem from '@/uni_modules/uni-list/components/uni-list-item/uni-list-item.vue'
export default {
components: {
uniCard,
uniList,
uniListItem
}
}
</script>
9. 常见问题与解决方案
9.1 跨域问题
H5开发时可能遇到跨域问题，可通过以下方式解决：
- 本地开发代理
在manifest.json中配置：
"h5": {
"devServer": {
"proxy": {
"/api": {
"target": "https://api.example.com",
"changeOrigin": true,
"pathRewrite": {
"^/api": ""
}
}
}
}
}
- 服务端设置CORS
在服务器端配置响应头：
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type
9.2 小程序分包加载
当项目体积较大时，可使用分包加载优化性能：
"subPackages": [
{
"root": "pages/goods",
"pages": [
{
"path": "list/list",
"style": { "navigationBarTitleText": "商品列表" }
},
{
"path": "detail/detail",
"style": { "navigationBarTitleText": "商品详情" }
}
]
}
]
10. 学习资源与社区支持
官方资源
社区论坛
总结与展望
通过hello-uniapp项目，我们学习了UniApp开发的核心流程和最佳实践。从环境搭建到项目发布，UniApp提供了一套完整的跨平台解决方案，极大地提高了开发效率。
随着移动应用开发需求的不断增长，掌握UniApp这样的跨平台框架将为你的职业发展带来巨大优势。建议继续深入学习以下内容：
- UniApp的性能优化技巧
- 原生插件开发与集成
- 大型项目的架构设计
- 小程序云开发能力
现在就动手修改hello-uniapp项目，添加自己的功能，开始你的UniApp开发之旅吧！
如果你觉得本文对你有帮助，请点赞、收藏并关注，后续将带来更多UniApp高级开发技巧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
