快速上手uni-app，真的只需要几分钟

鱼樱前端
598 阅读11分钟

话不投机半句多，搞快点效率办事~有一定 Vue.js 和微信小程序开发经验的开发者可快速上手 uni-app

uni-app 是什么 （Uni-app 是一个基于 Vue.js 的前端开发框架，它允许开发者使用一套代码来编写跨平台的应用程序）

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、Web（响应式）、以及各种小程序（微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝）、快应用等多个平台。

DCloud公司拥有900万开发者、数百万应用、12亿手机端月活用户、数千款uni-app插件、70+微信/qq群。阿里小程序工具官方内置uni-app（详见），腾讯课堂官方为uni-app录制培训课程（详见），开发者可以放心选择。

uni-app在手，做啥都不愁。即使不跨端，uni-app也是更好的小程序开发框架（详见）、更好的App跨平台框架、更方便的H5开发框架。不管领导安排什么样的项目，你都可以快速交付，不需要转换开发思维、不需要更改开发习惯。

快速体验

uni-app的由来

uni，读 you ni，是统一的意思。

很多人以为小程序是微信先推出的，其实，DCloud才是这个行业的开创者。

DCloud于2012年开始研发小程序技术，优化webview的功能和性能，并加入W3C和HTML5中国产业联盟，推出了HBuilder开发工具，为后续产业化做准备。

2015年，DCloud正式商用了自己的小程序，产品名为“流应用”，它不是B/S模式的轻应用，而是能接近原生功能、性能的App，并且即点即用，第一次使用时可以做到边下载边使用。

为将该技术发扬光大，DCloud将技术标准捐献给工信部旗下的HTML5中国产业联盟，并推进各家流量巨头接入该标准，开展小程序业务。

新建项目

选择一个空的项目或者依据你的喜好倒腾倒腾你想要的模板即可。。。

项目结构（以下介绍以空模版为例）

image.png

启动项目

支持运行的平台有这么多。。。h5的到浏览器预览即可

image.png

小程序的以微信小程序的为例需要额外的配置两个东西 你的微信小程序的appid （manifest.json中配置） 微信开发者工具配置 image.png 这样便可以开心的玩耍了，HBuilderX编辑器中编写代码即可实时看到效果如果是小程序代码还能自动打开开发者工具。。这点还是比较智能！！没有那么傻。。 当然还有一种是脚手架命令行创建的项目参考官方链接一个样的能简单就简单吧。

跨端开发注意 & 常见问题 & 插件市场

小程序地图选点功能（腾讯地图）接入指南

image.png chooseLocation:fail the api need to be declared in the requiredPrivateInfos field in app.json/ext.json 错误的解决办法 打开manifest.json选择源码视图

"mp-weixin" : {
    "requiredPrivateInfos" : [ "chooseLocation", "getLocation" ]
}

image.png 效果如上，配置如下

配置appid 和 勾选位置权限

image.png image.png

配置地图key [腾讯位置服务后台]

image.png

配置源码地图

在 mp-weixin （小程序特有相关）下面 (manifest.json文件)

"requiredPrivateInfos": [
    "getLocation",
    "onLocationChange",
    "startLocationUpdateBackground",
    "chooseAddress",
    "chooseLocation"
],
"permission" : {
    "scope.userLocation" : {
        "desc" : "门店位置"
    }
},
// 这个不需要！！！但是有这么一个插件可以用第二种
"plugins": {
    "chooseLocation": {
        "version": "1.1.1",
        "provider": "wx76a9a06e5b4e693e"
    }
}

小程序后台设置 （第三方平台授权管理）微信服务市场

image.png 插件配置 在manifest.json中的各平台对应的字段内声明使用的插件

// 微信小程序
"mp-weixin": {
  "plugins": {
    "myPlugin": {
      "version": "1.0.0",
      "provider": "wxidxxxxxxxxxxxxxxxx",
      "export": "index.js"
    }
  }
}

// 支付宝小程序
"mp-alipay": {
  "plugins": {
    "myPlugin": {
      "version": "*",
      "provider": "2019235609092837",
      "export": "index.js"
    }
  }
}

// 百度小程序
"mp-baidu": {
  "dynamicLib": {
    "myPlugin": {
      "provider": "TheUniqueNameOwnedByThisDynamicLib"
    }
  }
}
  • HBuilder X 3.2.13+ 支持 export 字段，即小程序导出到插件。目前仅 微信小程序 和 支付宝小程序 支持

#在页面中使用插件

使用插件提供的自定义组件，和使用普通自定义组件的方式相仿。在 json 文件定义需要引入的自定义组件时，使用 plugin:// 协议指明插件的引用名和自定义组件名

在页面内使用插件内包含的组件需要在pages.json内对应页面的style节点下配置对应平台的usingComponents或usingSwanComponents，示例如下：

以"hello-component": "plugin://myPlugin/hello-component"为例，key（冒号前的hello-component）为在页面内使用的组件名称。

value分为三段，plugin为协议（在百度小程序内为dynamicLib），myPlugin为插件名称即引入插件时的名称，hello-component为插件暴露的组件名称。

// 微信小程序
{
  "path": "pages/index/index",
  "style": {
    "mp-weixin": {
      "usingComponents": {
        "hello-component": "plugin://myPlugin/hello-component"
      }
    }
  }
}

// 支付宝小程序
{
  "path": "pages/index/index",
  "style": {
    "mp-alipay": {
      "usingComponents": {
        "hello-component": "plugin://myPlugin/hello-component"
      }
    }
  }
}

// 百度小程序 注意 HBuilder 3.1.0 以下部分插件需使用 usingSwanComponents
{
  "path": "pages/index/index",
  "style": {
    "mp-baidu": {
      "usingComponents": {
        "my-special-list": "dynamicLib://myDynamicLib/special-list"
      }
    }
  }
}

页面唤起地图选点功能

<template>
	<view class="content">
		<image class="logo" src="/static/logo.png"></image>
		<view class="text-area">
			<text class="title">{{title}}</text>
		</view>
		<view class="map" @click="getMapLocation">
			唤起地图选点功能1
		</view>
	</view>
</template>

<script setup>
import {ref} from 'vue'
const title = ref('Hello uni-app')

// 配置好上面的就这么一个api接口即可实现	
const getMapLocation = () => {
	uni.chooseLocation({
	  success: function (res) {
	    console.log('位置名称：' + res.name);
	    console.log('详细地址：' + res.address);
	    console.log('纬度：' + res.latitude);
	    console.log('经度：' + res.longitude);
	  },
	  fail: function (err) {
	    console.error('选择位置失败：', err);
	  }
	});
}
</script>

pages.json 页面路由

pages.json 文件用来对 uni-app 进行全局配置，决定页面文件的路径、窗口样式、原生的导航栏、底部的原生tabbar 等。

导航栏高度为 44px (不含状态栏)，tabBar 高度为 50px (不含安全区)。

它类似微信小程序中app.json的页面管理部分。注意定位权限申请等原属于app.json的内容，在uni-app中是在manifest中配置。

  • uni.navigateTo：保留当前页面，跳转到应用内的某个页面，使用uni.navigateBack可以返回到原页面。（非 tabBar 的页面的路径）
// 跳转 + 携带参数
const goNext = () => {
    uni.navigateTo({
        url: '/pages/test/test?id=1'
    });
};

// 目标页面获取
import { onLoad } from '@dcloudio/uni-app';

onLoad((option) => {
    console.log(option, 'test页面加载获取参数option.xxx即可获取参数');
});
  • uni.redirectTo：关闭当前页面，跳转到应用内的某个页面。（非 tabBar 的页面的路径）
uni.redirectTo({
    url: '/pages/test/test?id=1'
});

uni.navigateTo && uni.redirectTo 对比

  1. uni.navigateTo:

    • 该方法用于在当前页面打开新页面，并且将新页面压入页面栈。用户可以通过左上角的返回按钮或调用 uni.navigateBack 方法返回到上一页面。
    • 页面栈会保存跳转前的页面状态，所以当用户返回时，可以恢复之前的状态。
    • 适用于从一个页面导航到另一个页面并保留返回路径的场景。

  2. uni.redirectTo:

    • 该方法用于关闭当前页面，重定向到应用内的某个页面。即它会用新的页面替换当前页面，并不会增加页面栈的深度。
    • 用户无法通过返回按钮回到之前的页面，因为之前的页面已经被移除出了页面栈。
    • 适用于需要直接跳转至另一页面而不保留当前页面的场景，比如登录后跳转至首页，不需要用户再回到登录页

  • uni.reLaunch：关闭所有页面，打开到应用内的某个页面。

    • uni.reLaunch:
      • 使用 uni.reLaunch 可以关闭所有页面，打开到应用内的某个页面。这意味着它会清空当前的页面栈，然后打开指定的页面。
      • 用户无法通过返回按钮回到之前的任何页面，因为所有的历史页面记录都被清除了。
      • 这个方法适合用于一些特定场景，例如用户完成某些操作后（如登录、支付等），需要重新定向到首页或者其他主要页面，并且不希望用户能够通过返回按钮回到之前的操作页面。

    简而言之，当你想要完全刷新页面栈并打开一个新的页面时，可以使用 uni.reLaunch。这通常用于应用程序的关键节点，比如启动页之后进入主界面，或者在某些流程结束之后将用户导向到一个全新的起点。

  • uni.switchTab：跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。路径后不能带参数

uni.reLaunch({
    url: '/pages/my/my'
});
  • uni.navigateBack：关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层，如果 delta 大于现有页面数，则返回到首页

页面跳转总结

  • navigateTo, redirectTo 只能打开非 tabBar 页面。
  • switchTab 只能打开 tabBar 页面。
  • reLaunch 可以打开任意页面。
  • 页面底部的 tabBar 由页面决定，即只要是定义为 tabBar 的页面，底部都有 tabBar。
  • 不能在首页 onReady 之前进行页面跳转。
  • H5端页面刷新之后页面栈会消失，此时navigateBack不能返回，如果一定要返回可以使用history.back()导航到浏览器的其他历史记录。

生命周期

从 @dcloudio/uni-app 包内导入 uni-app 应用生命周期及页面的生命周期 image.png

image.png

image.png

image.png

跨端条件编译

在 C 语言中，通过 #ifdef、#ifndef 的方式，为 Windows、Mac 等不同 OS 编译不同的代码。

uni-app 团队参考这个思路，为 uni-app 提供了条件编译手段，在一个工程里优雅的完成了平台个性化实现。

使用方法

image.png 以 #ifdef 或 #ifndef 加 %PLATFORM% 开头，以 #endif 结尾。

  • #ifdef：if defined 仅在某平台存在
  • #ifndef：if not defined 除了某平台均存在
  • %PLATFORM%：平台名称

image.png

image.png

image.png

uni-app引用npm第三方库

从HBuilderX版本0.1.51或以上开始，uni-app支持使用npm安装第三方包。使用方式参考NPM支持

开发注意事项

  • 应用生命周期仅可在App.vue中监听，在其它页面监听无效。
  • App.vue 不能写模板
  • 应用启动参数，可以在API uni.getLaunchOptionsSync获取
  • onPageNotFound 页面实际上已经打开了（比如通过分享卡片、小程序码）且发现页面不存在，才会触发，api 跳转不存在的页面不会触发（如 uni.navigateTo）
  • 小程序有globalData，这是一种简单的全局变量机制。这套机制在uni-app里也可以使用，并且全端通用。当然vue框架的全局变量，另有其他方式定义。
<script>  
    export default {  
        globalData: {  
            text: 'text'  
        }
    }  
</script>

js中操作globalData的方式如下： getApp().globalData.text = 'test' 如果需要把globalData的数据绑定到页面上，可在页面的onShow页面生命周期里进行变量重赋值

  • 在App.vue中，可以定义一些全局通用样式

  • 无法使用vue-router，路由须在pages.json中进行配置。如果开发者坚持使用vue-router，可以在插件市场找到转换插件。

  • 使用Vue.use引用插件，使用Vue.prototype添加全局变量，使用Vue.component注册全局组件

  • nvue 暂不支持在 main.js 注册全局组件

  • uni-app x 暂不支持 i18n、vuex、pinia等插件

  • 需要在 HBuilderX 里面安装 scss 插件；使用时需要在 style 节点上加上 lang="scss"，pages.json不支持scss，原生导航栏和tabbar的动态修改只能使用js api

  • vue.config.js 是一个可选的配置文件，如果项目的根目录中存在这个文件，那么它会被自动加载，一般用于配置 webpack 等编译选项，具体规范参考：vue.config.js【仅vue页面生效/部分配置项会被编译配置覆盖】

    • publicPath 不支持，如果需要配置，请在 manifest.json->h5->router->base 中配置，参考文档：h5-router
    • outputDir 不支持
    • assetsDir 固定 static
    • pages 不支持
    • runtimeCompiler 固定 false
    • productionSourceMap 固定 false
    • css.extract H5 平台固定 false，其他平台固定 true
    • parallel 固定 false
    • 使用cli项目时，默认情况下 babel-loader 会忽略所有 node_modules 中的文件。如果你想要通过 Babel 显式转译一个依赖，可以在transpileDependencies中列出来。详情参考

  • vite.config.js 是一个可选的配置文件，如果项目的根目录中存在这个文件，那么它会被自动加载，一般用于配置 vite 的编译选项，具体规范参考：vite.config.js

    • 仅vue 3项目生效 部分配置项会被编译配置覆盖
    • base：web 平台支持
    • root：不支持
    • mode：不支持
    • publicDir: 不支持，固定为 static
    • build.outDir：不支持
    • build.assetsInlineLimit：仅 h5 支持
    • build.cssCodeSplit：不支持，固定为 true
    • build.lib：不支持
    • build.manifest：不支持
    • build.ssrManifest：不支持
    • build.ssr：不支持

  • uni-app 内置了 Pinia 。Vue 2 项目暂不支持（无需手动安装）

  • 使用 CLI安装

    4.14 之前：执行 yarn add pinia@2.0.36 或 npm install pinia@2.0.36 安装，要固定版本

    4.14 之后：执行 yarn add pinia 或 npm install pinia 安装，可不指定版本

  • uni-app 内置了 Vuex

  • vue2：uni-app编译器基于wepback实现

  • vue3：uni-app编译器基于Vite实现，编译速度更快

  • uni-app x不支持自定义环境变量。

avatar
文章
阅读
粉丝