uni-app使用总结

简述

uni-app 是一个基于 Vue 的前端开发框架。同时它整合了 H5+、各大主流厂商小程序、Weex 等规范及特性，致力于用户通过最低成本(一套代码)开发出兼容 Web、IOS、Android 以及各种小程序的跨平台前端应用。
从 DCloud 官网我们可以了解到，官方不只提供了 uni-app 这个框架，还提供了详尽的开发文档、配套 IDE、组件库、各种 SaaS 化服务等一整套完整的跨平台应用开发解决方案。

为了充分发挥社区的力量，官方还提供了插件市场及社区论坛。用户可以在插件市场通过付费或免费的方式搜索获得开发过程中所需的各种插件，同样，我们也可以将自己开发的插件有偿或无偿地发布到插件市场供他人使用。我们可以在社区论坛中发布各种技术问题进行求助，也可以进行技术分享。当然，我们也可以通过付费的方式求助官方解决开发过程中遇到的问题。

uni-app 官方文档在使用教程、常见开发问题解答等方面已经有十分详尽的叙述。下面将结合自己的理解对文档中的一些要点做出汇总。

学习要点

在刚开始接触 uni-app 官方文档教程时，可能会因为“丰富”的文档内容和大量的技术点，一时不知道从何学起。以下是我在使用和学习 uni-app 框架过程要总结出来的一些学习要点，希望能帮助大家高效学习 uni-app 框架。当然，官方也提供了丰富的视频教程帮助大家更全面更高效地学习 uni-app 框架。

由于 uni-app 框架是基于 Vue 且遵循其 SFC 开发规范，所以我们在使用 uni-app 框架进行开发前必须要先对 Vue 进行学习。在熟悉 Vue 后，我们就可以高效地进行 uni-app 框架的学习及开发了。建议对微信小程序开发也有所了解。因为在学习 uni-app 框架的过程中，我们会发现文档中的很多概念内容都是和微信小程序开发相同或类似的。

开发环境

在开发 uni-app 时，我们必须要使用配套 IDE——HBuilderX。官方对该 IDE 的发版还是挺频繁的，建议尽量使用最新稳定版。通过该 IDE 我们可以对 uni-app 进行多端调试及发行，具体使用教程可查看这里。

插件和组件

现代前端开发遵循模块化、组件化的开发方式。为了实现 uni-app 的跨平台及提高应用性能，官方定义了多种类别的组件、插件及开发规范。了解清楚它们的作用、适用场景是高效开发 uni-app 的关键点之一。

• 插件分类

  在这里，插件是指通过 uni-app 规范对 js 接口、自定义组件、页面等功能或服务的封装。它无法独立运行，必须要嵌入到 uni-app 中使用。通过封装插件，可以提供功能或服务给第三方使用。插件市场中包含了前端组件、JS SDK、原生 SDK 等插件。

  在 uni-app 文档中主要包含了前端组件、App 原生插件、小程序插件三种插件的开发说明，下面对它们进行简单总结：

  插件类型	适用平台	备注
  前端组件	web、小程序、App	可以理解成视图层相关的插件，基本都是多端兼容的。
  App 原生插件	App	使用 App 离线 SDK 开发原生插件来扩展原生能力，基于 Weex。
  小程序插件	对应厂商的小程序	通过 uni-app 框架可以开发或使用不同小程序厂商的小程序插件

• 组件分类

  在这里，组件主要是指通过 uni-app 规范定义的一系列视图层组件(前端组件)。这些组件基本都是多端兼容的，具体使用及限制以官方文档为准。以下 uni-app 中的组件类型做出简单总结：

  类型	适用平台	所用规范	备注
  基础组件	App、小程序、web	-	可直接使用的内置组件，基本等同于微信小程序中的组件。
  扩展组件	App、小程序、web	-	除基础组件外的组件
  小程序组件	web、App、对应厂商小程序	对应厂商小程序规范	微信小程序组件是多端兼容的、其他小程序组件只兼容自身小程序
  nvue 组件	App、小程序、web	nvue 组件规范	使 vue 组件具备原生渲染能力,App 端基于 Weex 的高性能渲染器进行渲染
  原生组件	App、小程序、web	vue 组件规范或 nvue 组件规范	又分为内置原生组件和 App 端的原生组件，开发时需要注意层级覆盖问题
  uniCloud 组件	App、小程序、web	vue 组件规范、uniCloud 组件规范	配合 uniCloud 服务的组件
  datacom 组件	App、小程序、web	vue 组件规范、datacom 组件规范	对所绑定的数据格式进行规范的组件

vue 页面主体在小程序端和 App 端是用 webview 渲染的，但是部分 ui 元素比如导航栏、tabbar、video、map 等是使用原生控件渲染的，所以这种方式称为混合渲染。混合渲染会存在层级覆盖的问题，具体问题描述及解决方案可查看这里。

插件分类所说的 App 原生插件其实分为原生组件 component 和原生模块 module，都是基于 Weex 规范。App 端原生组件只能在 nvue 页面中使用。

nvue 组件和 vue 组件不能相互引用，在 nvue 页面中只能使用 nvue 组件和 App 端原生组件。nvue 页面要不完全用 webview 渲染，要不完全用原生渲染，所以不存在层级覆盖问题。由于使用 nvue 技术时有较大的开发限制，所以不建议在开发非 App 应用时使用 nvue。适用在 App 端某些 vue 页面表现不佳的场景下使用 nvue 作为强化补充，如：App 端首页快速渲染、深度使用原生组件的页面、高性能的区域长列表或瀑布流滚动等。

技术规范

由于 uni-app 框架是基于 Vue、Weex、微信小程序等技术的，所以框架中也用到了这些技术的开发规范。对技术规范进行整合，统一 js API 的同时，为了提高开发者效率和应用性能，官方也自定义了一些开发规范。
虽然 uni-app 框架是基于上述技术，但是不代表官方对上述技术做出 100%的实现，所以在原技术的实现或文档上会有所差异，在开发过程中要以 uni-app 官方文档为准。

• Vue 技术规范——页面文件遵循 SFC 规范，框架已整合 Vue2 和 Vue3。

• 微信小程序技术规范——uni-app 基础组件、 JS API、生命周期等就是靠近微信小程序规范。

• Weex 技术规范——uni-app 原生插件开发规范就是基于 Weex 技术规范。

• HTML5+规范——uni-app App 端内置 HTML5+引擎，让 js 可以直接调用丰富的原生能力。

• easycom 组件规范——uni-app 定义的组件开发规范，符合规范的组件具备自动注册、引用、按需打包的功能。

• datacom 组件规范——uni-app 定义的组件开发规范，用于开发统一输入输出数据格式的组件。

• nvue 技术规范——符合规范的组件在 App 端使用 Weex 渲染器进行原生渲染，可以使 App 性能得到一定提高，是 Vue 页面在 App 端的性能强化补充技术。

• uni_module 规范——uni-app 定义的插件开发规范，符合 uni_module 规范的插件可很方便地更新已上传到插件市场的插件。

跨端兼容

uni-app 官方尽最大限度保证了常用组件、JS API 等方面的跨平台兼容，但是每个平台都会有自己的一些特性，因此会存在无法跨平台的情况。因此 uni-app 框架通过条件编译技术，高效地解决了不同平台的个性化差异。

其他

• 使用 HTML5+注意事项
• 跨端开发注意事项
• 高效开发技巧
• 性能优化建议
• 宽屏适配指南
• 选型评估指南
• 常见问题解决
• vue 页面层级覆盖解决方案
• 其他项目转 uni-app
• Native.js 示例汇总

混合开发

• uni 小程序 SDK
• 原生插件开发

通过对 uni-app 框架的使用，使我对混合开发及选型有了更清晰的了解。

问题及解决方法

在使用 uni-app 框架开发的过程中，可能会遇到各种问题，大家可以优先通过官方渠道搜索解决方案，如：常见问题解决、gitHub/Issues、社区论坛，同时值得一提的是官方文档的站内搜索挺友好的。以下是对我在开发过程中遇到的问题及解决方法的总结。

1. nvue 页面和 vue 页面在应用中可以混搭、互相跳转，但是在 nvue 组件和 vue 组件不能互相混搭是引用。虽然 nvue 组件在结构和 vue 组件很相似，但实际上在很多方面是有局限性和区别的，必须要严格按照 nvue 技术规范进行开发。

2. 在开发 uni-app 时需求可能不需要兼容 web 端，但我认为能最起码做到对 web 端视图层的样式兼容是很有必要的，有助于我们在开发过程中的调试。

3. 通过 HbuilderX 新建 uni-app 项目时，我们可选择 vue 版本。如果原有 uni-app 项目想从 vue2.x 升级到 vue3.x，可查看这里和这里。不同 vue 版本的项目工程模板所使用的 web 端编译打包技术是不一样的。

   vue 版本	打包技术	脚手架参考	备注
   2.x	webpack	vue-cli3	配置说明、环境变量设置
   3.x	rollup	vite	rollup 本身是不支持 commonJS 模块化规范的，可以安装插件提供支持。环境变量设置

4. vue.config.js(vue2.x)和 vite.config.js(vue3.x) 是项目工程中的可选配置文件，但并不是所有配置项更改后都能生效，以官方说明为准。且这两个配置文件只对 web 端打包有效，如 3 中所提及的环境变量在小程序端和 App 端是不能正常使用的。

5. uni-app 全局变量实现可看这里。

6. 当使用 HbuilderX 开启或重启调试时，可能会出现打包失败的情况(如下图)，则可以删除生成的 unpackage 里的 dist 文件夹后再启动调试。不建议直接删除 unpackage 文件夹，因为如果正在通过自定义基座进行 App 真机调试，那么自定义基座就会被删除，需要重新制作自定义基座。
   

7. 当使用自定义基座进行 App 端真机调试时，如果 manifest.json 中 App 相关的配置项发生了更改都需要重新制作自定义基座。

8. 安卓原生插件开发时，通过 globalEvent 事件对象对原生事件进行监听，可能会出现失效的情况。通过查看源码，可通过如下方式解决。

   Map<String,Object> params=new HashMap<>();
   params.put("key","value");
   mUniSDKInstance.fireModuleEvent("myEvent", params);
   

9. 安卓设备连接 PC（windows 系统）进行真机调试时，可能会出现由于未正确安装 ADB Interface 导致 Hbuilder 找不到运行设备的情况，可参考这里进行解决。

10. 通过 App 本地离线工程制作自定义调试基座进行真机调试，如出现 Hbuilder 控制台无法打印调试信息，需检查 App 本地离线工程中的 dcloud_control.xml 文件并确保如下配置。

      <hbuilder debug="true" syncDebug="true">
    

项目工程模板

HBuilderX 创建的工程模板结构是比较简单，为了满足自身项目开发需要，我基于官方的基础模板配合 HBuilderX 插件搭建了一个(git 仓库地址)。

• 配合安装的 HBuilderX 插件：Vue/Vuex/Vue Router 代码块、typescript 语言服务、typescript 编译、stylelint、prettier、eslint-plugin-vue、dart-sass 编译

• 工程模板能力：vue3、typeScript、prettier、eslint、husky、babel