UniApp跨平台开发全攻略

FE_Jinger

于 2025-10-11 08:00:00 发布

阅读量346

点赞数 11

CC 4.0 BY-SA版权

文章标签： uni-app 前端 javascript

本文链接：https://blog.csdn.net/m0_55049655/article/details/152949774

UniappI
Uniapp II
Uniapp III
Uniapp IV
Uniapp大全
 Uniapp小程序开发
好的，请看这篇基于您提供的资料整理的，从浅入深的UniApp总结博客。

UniApp跨平台开发从入门到精通：一站式学习指南

前言

在当今多端应用开发的时代，开发者为适配iOS、Android、Web及各种小程序平台往往需要组建多个团队，编写多套代码，这不仅成本高昂，而且难以维护。DCloud公司推出的UniApp框架正是为了解决这一痛点而生。它基于Vue.js生态，允许开发者使用一套代码，通过条件编译等手段，发布到几乎所有主流平台。

本文将结合核心概念、项目结构、生命周期、常用API及开发实践，带你系统性地掌握UniApp开发。

一、UniApp核心概览：为什么选择它？

1.1 定义与核心特性

UniApp是一个使用Vue.js语法开发所有前端应用的框架。其核心特性可概括为以下几点：

跨平台开发 (Write Once, Run Anywhere)：一套代码可编译发布到iOS、Android、Web（H5）、以及各种小程序（微信/支付宝/百度/头条/QQ/钉钉/淘宝等）、快应用等多个平台，极大提高开发效率和代码复用率。
完整的Vue.js开发体验：开发者可以充分利用熟悉的Vue.js语法、生态系统（如Vuex、Vue Router的替代品）和工具链（Webpack、NPM等）。
丰富的组件与API：内置了大量跨平台组件（如view, text, scroll-view）和API（如网络请求、数据存储、支付、地图等），同时支持使用第三方Vue组件库。
高性能体验：App端支持原生渲染（nvue），性能体验接近原生；小程序端体验流畅。
强大的生态系统：拥有活跃的社区、丰富的插件市场，遇到问题容易找到解决方案。

1.2 跨端原理浅析

UniApp的跨端能力并非魔法，其核心在于编译时和运行时的协同工作。

编译时：UniApp编译器（HBuilderX或Vue CLI）将您编写的Vue组件、JS和CSS代码，根据不同平台的规则，编译成目标平台所能识别的代码包。
- 编译到小程序端：生成对应小程序的WXML、WXSS、JS文件。
- 编译到H5端：生成标准的HTML、CSS、JS文件。
- 编译到App端：通过集成Weex引擎，将Vue组件渲染为原生组件。
运行时：UniApp提供了一套统一的API（如uni.request, uni.navigateTo）。在运行时，这些API会根据当前运行的平台，调用对应的原生API或浏览器API执行。

二、项目结构与核心配置文件解析

一个标准的UniApp项目结构如下所示，与传统的Vue CLI项目相似，但有几个核心配置文件是其灵魂所在。

uni-app-project
  ├── pages
  │    └── index
  │         ├── index.vue    // 页面组件
  │         ├── index.js     // 页面逻辑（通常合并到.vue中）
  │         └── index.json   // 页面配置
  ├── static                 // 存放静态资源
  ├── components             // 可复用Vue组件
  ├── utils                  // 工具函数
  ├── main.js               // Vue初始化入口文件
  ├── App.vue               // 应用配置，全局样式、生命周期
  ├── manifest.json         // 应用配置文件
  ├── pages.json           // 页面路由与表现配置文件
  └── uni.scss             // 全局SCSS变量

2.1 `pages.json` - 路由与全局样式管理器

此文件专门用于管理页面路由和窗口表现，类似于小程序中的app.json，是UniApp路由系统的核心。

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页", // 页面标题
        "enablePullDownRefresh": true    // 是否开启下拉刷新
      }
    },
    {
      "path": "pages/detail/detail",
      "style": {
        "navigationBarTitleText": "详情页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "我的UniApp",
    "navigationBarBackgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      },
      {
        "pagePath": "pages/user/user",
        "text": "我的"
      }
    ]
  }
}

pages.json vs Vue Router：

特性	UniApp `pages.json`	Vue Router
设计目标	跨平台应用，管理多端页面路由和导航	单页面Web应用（SPA）
配置方式	静态的JSON配置文件	在JS中动态定义路由表
跳转方式	`uni.navigateTo`, `<navigator>`组件	`this.$router.push()`, `<router-link>`组件
适用场景	小程序、App、H5等多端统一管理	主要为Web SPA

2.2 `manifest.json` - 应用信息与SDK配置

此文件是应用的全局配置文件，用于指定应用的名称、图标、启动界面、引用的原生SDK模块（如支付、推送、统计）等打包信息。

{
  "name": "我的优秀应用",
  "appid": "__UNI__XXXXXX",
  "versionName": "1.0.0",
  "versionCode": "100",
  "app-plus": {
    "usingComponents": true,
    "modules": { /* 模块配置 */ },
    "distribute": {
      "android": { /* 安卓打包配置 */ },
      "ios": { /* iOS打包配置 */ }
    }
  },
  "mp-weixin": {
    "appid": "你的微信小程序AppID",
    "setting": {
      "urlCheck": false
    }
  }
  // ...其他平台配置
}

三、生命周期：掌控应用与页面的节奏

理解生命周期是正确编写业务逻辑的关键。UniApp的生命周期分为三部分：应用生命周期、页面生命周期和组件生命周期。

3.1 应用生命周期 (App.vue中定义)

应用生命周期函数需要在App.vue的script中定义。

// App.vue
<script>
export default {
  onLaunch: function(options) {
    // 初始化完成时触发（全局只触发一次）
    console.log('App Launch，场景值:', options.scene);
    // 常用于初始化云函数、获取用户信息、获取推送token等
  },
  onShow: function(options) {
    // 启动，或从后台进入前台显示时触发
    console.log('App Show');
  },
  onHide: function() {
    // 从前台进入后台时触发
    console.log('App Hide');
  },
  onError: function(err) {
    // 发生脚本错误或API调用失败时触发
    console.log('App Error:', err);
  }
}
</script>

3.2 页面生命周期 (.vue文件中定义)

页面生命周期函数在页面Vue组件的script中定义。

<script>
export default {
  data() {
    return {
      title: 'Hello'
    };
  },
  onLoad(options) {
    // 监听页面加载，接收上个页面传递的参数
    // 一个页面只会调用一次
    console.log('页面加载，参数：', options.id);
    this.loadData(options.id); // 常用于初始化页面数据
  },
  onShow() {
    // 监听页面显示，每次打开页面都会调用
    // 适用于刷新数据，如从B页面返回A页面时刷新A页面的列表
  },
  onReady() {
    // 监听页面初次渲染完成
  },
  onHide() {
    // 监听页面隐藏
  },
  onUnload() {
    // 监听页面卸载
    // 常用于清除定时器、取消订阅等
  },
  onPullDownRefresh() {
    // 监听用户下拉动作
    this.refreshData(); // 刷新数据
    uni.stopPullDownRefresh(); // 停止下拉刷新动画
  },
  onReachBottom() {
    // 页面上拉触底事件的处理函数
    this.loadMoreData(); // 加载更多数据
  },
  methods: {
    loadData(id) { /* ... */ },
    refreshData() { /* ... */ }
  }
};
</script>

3.3 组件生命周期 (与Vue标准生命周期一致)

UniApp完全支持Vue组件的生命周期，如created, mounted, updated, destroyed等。

export default {
  created() {
    // 组件实例被创建后调用，但尚未挂载DOM
  },
  mounted() {
    // 组件挂载到DOM后调用，可以操作DOM了
  }
}

生命周期执行顺序（示例）：
假设应用冷启动进入首页：
App.onLaunch -> App.onShow -> 首页onLoad -> 首页onShow -> 首页onReady -> (Vue组件created/mounted)

四、常用API分类精讲

UniApp将不同平台的API进行了统一封装，使开发更加简单高效。以下是一些最常用的API分类：

4.1 导航与路由 API

用于页面跳转和导航栏操作。

// 1. 保留当前页面，跳转到应用内的某个页面
uni.navigateTo({
  url: '/pages/detail/detail?id=1&name=uni-app'
});

// 2. 关闭当前页面，跳转到应用内的某个页面（重定向）
uni.redirectTo({
  url: '/pages/login/login'
});

// 3. 跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面
uni.switchTab({
  url: '/pages/user/user'
});

// 4. 关闭所有页面，打开到应用内的某个页面
uni.reLaunch({
  url: '/pages/home/index'
});

// 接收参数（在目标页面的onLoad中）
onLoad(options) {
  console.log(options.id); // 输出：1
  console.log(options.name); // 输出：uni-app
}

4.2 数据存储 API

用于本地数据的存储和读取，分为异步和同步两种方式。

// 异步存储（推荐）
uni.setStorage({
  key: 'user_info',
  data: { name: '张三', age: 25 },
  success: () => {
    console.log('存储成功');
  }
});

// 同步存储（代码更简洁，但可能阻塞渲染）
try {
  uni.setStorageSync('user_info', { name: '张三', age: 25 });
} catch (e) {
  console.error('存储失败：', e);
}

// 读取数据
try {
  const userInfo = uni.getStorageSync('user_info');
  console.log(userInfo); // { name: '张三', age: 25 }
} catch (e) {
  // 错误处理
}

4.3 网络请求 API

用于与服务器进行交互，是绝大多数应用的核心。

uni.request({
  url: 'https://www.example.com/api/user/login', // 仅为示例，并非真实接口地址
  method: 'POST',
  data: {
    username: 'admin',
    password: '123456'
  },
  header: {
    'content-type': 'application/json' // 默认值
  },
  success: (res) => {
    // 请求成功，res.data 为服务器返回的数据
    console.log(res.data);
  },
  fail: (err) => {
    // 请求失败
    console.error('请求失败：', err);
  },
  complete: () => {
    // 请求完成（无论成功失败都会执行）
  }
});

4.4 界面交互 API

提供丰富的反馈，提升用户体验。

// 显示提示框
uni.showToast({
  title: '操作成功！',
  icon: 'success',
  duration: 2000
});

// 显示加载提示
uni.showLoading({
  title: '加载中...',
  mask: true // 显示透明蒙层，防止触摸穿透
});

// 模拟耗时操作
setTimeout(() => {
  uni.hideLoading(); // 隐藏加载提示
}, 2000);

// 显示模态弹窗
uni.showModal({
  title: '提示',
  content: '确认要删除此项吗？',
  success: (res) => {
    if (res.confirm) {
      console.log('用户点击确定');
    } else if (res.cancel) {
      console.log('用户点击取消');
    }
  }
});

其他重要API类别：

媒体类：uni.chooseImage（选择图片）、uni.previewImage（预览图片）、uni.uploadFile（文件上传）。
设备相关：uni.getSystemInfo（获取系统信息）、uni.getLocation（获取地理位置）。
滚动置顶：uni.pageScrollTo（将页面滚动到目标位置）。

五、开发与发布流程

5.1 环境搭建与开发

安装开发工具：推荐使用官方IDE https://www.dcloud.io/hbuilderx.html，它针对UniApp有深度优化，开箱即用。
创建项目：在HBuilderX中选择 文件 -> 新建 -> 项目，选择uni-app类型模板。
运行调试：
- 浏览器：选择运行 -> 运行到浏览器。
- 小程序：需先安装对应平台的开发者工具（如微信开发者工具），然后在HBuilderX中配置工具路径，选择运行 -> 运行到小程序模拟器。
- 真机调试：使用HBuilderX的真机运行功能，扫码即可在手机端预览和调试。

5.2 跨端兼容与条件编译

虽然UniApp提倡一套代码，但不同平台仍有差异。条件编译是解决平台差异的终极武器。

// #ifdef MP-WEIXIN
console.log('这段代码只会在微信小程序平台上编译');
wx.chooseMessageFile({}); // 使用微信特有的API
// #endif

// #ifdef APP-PLUS
console.log('这段代码只会在App平台上编译');
plus.device.getInfo(); // 使用5+原生API
// #endif

// #ifdef H5
console.log('这段代码只会在H5平台上编译');
// 使用H5特有的API或做特殊处理
// #endif

在样式中也可以使用条件编译：

/* #ifndef H5 */
// 非H5平台应用的样式
.page {
  padding-top: 60rpx;
}
/* #endif */

5.3 打包发行

在HBuilderX的顶部菜单中，选择发行：

发行到小程序：选择小程序-微信，会自动编译生成代码包，并弹出微信开发者工具，然后可在开发者工具中上传审核。
发行为App：选择原生App-云打包，选择证书后，DCloud的服务器会帮你生成安装包。
发行为H5：选择网站-H5手机版，会生成静态资源文件，可部署到Web服务器。

总结与展望

UniApp通过其强大的跨端能力、与Vue.js完美融合的开发体验以及丰富的生态系统，已经成为跨平台应用开发的首选框架之一。它尤其适合：

初创公司和小团队：快速验证想法，以最低成本覆盖最多用户。
需要同时开发小程序和App的项目：最大化代码复用。
Vue.js开发者：无需学习新技术栈，即可切入移动端开发。

学习建议：

巩固Vue.js基础：这是学好UniApp的基石。
熟读官方文档：遇到问题首先查阅文档，文档非常详细。
动手实践：从一个小项目（如TodoList）开始，逐步尝试使用路由、状态管理、各种API。
善用插件市场：在https://ext.dcloud.net.cn/寻找轮子，能极大提升开发效率。

UniApp仍在不断迭代和发展中，未来会进一步弥合不同平台间的差异，提供更极致的开发体验和性能表现。现在开始学习并投入UniApp开发，无疑是一个非常有价值的选择。