uni-app框架介绍

介绍

uni-app 是一个跨端开发框架，一套代码运行多个平台，并可以使用条件编译实现不同平台的特性编码

img

快速入门

uni-app支持通过可视化界面，HBuilderX内置相关环境，开箱即用

HBuilderX是通用的前端开发工具，但为uni-app做了特别强化。

uni-app 使用vue的语法+小程序的标签和API。

目录结构

一个uni-app工程，默认包含如下目录及文件：

│─components            符合vue组件规范的uni-app组件目录
│  └─comp-a.vue         可复用的a组件
├─hybrid                App端存放本地html文件的目录，详见
├─platforms             存放各平台专用页面的目录，详见
├─pages                 业务页面文件存放的目录
│  ├─index
│  │  └─index.vue       index页面
│  └─list
│     └─list.vue        list页面
├─static                存放应用引用的本地静态资源（如图片、视频等）的目录，注意：静态资源只能存放于此
├─common                自建的通用目录，可以存放一些公用css\less\scss、js等文件
├─store                 数据state共享store目录，通常我们引入vuex使用的目录
│  ├─index.js
├─api                   自建的api目录，可以存放封装服务端API接口、通用网络请求的js等文件
├─uni_modules           存放[uni_module](/uni_modules)规范的插件。
├─node_modules          存放npm导入的第三方包
├─wxcomponents          存放小程序组件的目录，详见
├─main.js               Vue初始化入口文件
├─App.vue               应用配置，用来配置App全局样式以及监听 应用生命周期
├─manifest.json         配置应用名称、appid、logo、版本等打包信息，详见
└─pages.json            配置页面路由、导航条、选项卡等页面类信息，详见
    

Tips

• 编译到任意平台时，static 目录下的文件均会被完整打包进去，且不会编译。非 static 目录下的文件（vue、js、css 等）只有被引用到才会被打包编译进去。
• static 目录下的 js 文件不会被编译，如果里面有 es6 的代码，不经过转换直接运行，在手机设备上会报错。

配置说明

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

manifest.json 文件是应用的配置文件，用于指定应用的名称、图标、权限等。HBuilderX 创建的工程此文件在根目录，CLI 创建的工程此文件在 src 目录。

uni.scss文件的用途是为了方便整体控制应用的风格。比如按钮颜色、边框风格，uni.scss文件里预置了一批scss变量预置。

App.vue是uni-app的主组件，所有页面都是在App.vue下进行切换的，是页面入口文件。但App.vue本身不是页面，这里不能编写视图元素。

这个文件的作用包括：调用应用生命周期函数、配置全局样式、配置全局的存储globalData

应用生命周期仅可在App.vue中监听

main.js是uni-app的入口文件，主要作用是初始化vue实例、定义全局组件、使用需要的插件如vuex。

详细参考：https://uniapp.dcloud.io/collocation/pages

资源路径说明

模板内引入静态资源

template内引入静态资源，如image、video等标签的src属性时，可以使用相对路径或者绝对路径，形式如下

<!-- 绝对路径，/static指根目录下的static目录，在cli项目中/static指src目录下的static目录 -->
<image class="logo" src="/static/logo.png"></image>
<image class="logo" src="@/static/logo.png"></image>
<!-- 相对路径 -->
<image class="logo" src="../../static/logo.png"></image>

注意

• @开头的绝对路径以及相对路径会经过base64转换规则校验
• 引入的静态资源在非h5平台，均不转为base64。
• H5平台，小于4kb的资源会被转换成base64，其余不转。
• 自HBuilderX 2.6.6起template内支持@开头路径引入静态资源，旧版本不支持此方式
• App平台自HBuilderX 2.6.9起template节点中引用静态资源文件时（如：图片），调整查找策略为【基于当前文件的路径搜索】，与其他平台保持一致
• 支付宝小程序组件内 image 标签不可使用相对路径

js文件引入

js文件或script标签内（包括renderjs等）引入js文件时，可以使用相对路径和绝对路径，形式如下

// 绝对路径，@指向项目根目录，在cli项目中@指向src目录
import add from '@/common/add.js'
// 相对路径
import add from '../../common/add.js'

注意

• js文件不支持使用/开头的方式引入

css引入静态资源

css文件或style标签内引入css文件时（scss、less文件同理），可以使用相对路径或绝对路径（HBuilderX 2.6.6）

/* 绝对路径 */
@import url('/common/uni.css');
@import url('@/common/uni.css');
/* 相对路径 */
@import url('../../common/uni.css');

注意

• 自HBuilderX 2.6.6起支持绝对路径引入静态资源，旧版本不支持此方式

css文件或style标签内引用的图片路径可以使用相对路径也可以使用绝对路径，需要注意的是，有些小程序端css文件不允许引用本地文件（请看注意事项）。

/* 绝对路径 */
background-image: url(/static/logo.png);
background-image: url(@/static/logo.png);
/* 相对路径 */
background-image: url(../../static/logo.png);

Tips

• 引入字体图标请参考，字体图标

• @开头的绝对路径以及相对路径会经过base64转换规则校验

• 不支持本地图片的平台，小于40kb，一定会转base64。（共四个平台mp-weixin, mp-qq, mp-toutiao, app v2）

• h5平台，小于4kb会转base64，超出4kb时不转。

• 其余平台不会转base64

npm 是 JavaScript 世界的包管理工具。通过 npm 可以安装、共享、分发代码,管理项目依赖关系。

路由

uni-app页面路由为框架统一管理，开发者需要在pages.json里配置每个路由页面的路径及页面样式，pages 节点接收一个数组，数组每个项都是一个对象，其属性值如下：

Tips：

• pages节点的第一项为应用入口页（即首页）

style：

用于设置每个页面的状态栏、导航条、标题、窗口背景色等。

页面中配置项会覆盖 globalStyle 中相同的配置项

路由跳转

uni-app 有两种页面路由跳转方式：使用navigator组件跳转、调用API跳转。

navigator:

页面跳转组件类似HTML中的<a>组件，只能跳转本地页面。目标页面必须在pages.json中注册。

示例

<template>
    <view>
        <view class="page-body">
            <view class="btn-area">
                <navigator url="navigate/navigate?title=navigate" hover-class="navigator-hover">
                    <button type="default">跳转到新页面</button>
                </navigator>
                <navigator url="redirect/redirect?title=redirect" open-type="redirect" hover-class="other-navigator-hover">
                    <button type="default">在当前页打开</button>
                </navigator>
                <navigator url="/pages/tabBar/extUI/extUI" open-type="switchTab" hover-class="other-navigator-hover">
                    <button type="default">跳转tab页面</button>
                </navigator>
            </view>
        </view>
    </view>

API：

uni.navigateTo(OBJECT) 保留当前页面，跳转到应用内的某个页面，使用uni.navigateBack可以返回到原页面。

uni.redirectTo(OBJECT) 关闭当前页面，跳转到应用内的某个页面。

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

uni.switchTab(OBJECT) 跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面。

uni.navigateBack(OBJECT) 关闭当前页面，返回上一页面或多级页面。

页面栈

框架以栈的形式管理当前所有页面， 当发生路由切换的时候，页面栈的表现如下：

运行环境判断

开发环境和生产环境

if(process.env.NODE_ENV === 'development'){
    console.log('开发环境')
}else{
    console.log('生产环境')
}

注意：

• 在HBuilderX 中，点击“运行”编译出来的代码是开发环境，点击“发行”编译出来的代码是生产环境
• cli模式下，是通行的编译环境处理方式。
• 如果你需要自定义更多环境，比如测试环境：
  • 假设只需要对单一平台配置，可以 package.json 中配置，在HBuilderX的运行和发行菜单里会多一个出来。https://uniapp.dcloud.io/collocation/package
  • 如果是针对所有平台配置，可以在 vue-config.js 中配置。https://uniapp.dcloud.io/collocation/vue-config
• HBuilderX 中敲入代码块 uEnvDev、uEnvProd 可以快速生成对应 development、production 的运行环境判定代码。

判断平台

平台判断有2种场景，一种是在编译期判断，一种是在运行期判断。

• 编译期判断，即条件编译，不同平台在编译出包后已经是不同的代码。

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

  值	平台
  APP-PLUS	App
  APP-PLUS-NVUE或APP-NVUE	App nvue
  H5	H5
  MP-WEIXIN	微信小程序
  MP-ALIPAY	支付宝小程序
  MP-BAIDU	百度小程序
  MP-TOUTIAO	字节跳动小程序
  MP-QQ	QQ小程序
  MP-360	360小程序
  MP	微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ小程序/360小程序
  QUICKAPP-WEBVIEW	快应用通用(包含联盟、华为)
  QUICKAPP-WEBVIEW-UNION	快应用联盟
  QUICKAPP-WEBVIEW-HUAWEI	快应用华为

// #ifdef H5
    alert("只有h5平台才有alert方法")
// #endif

如上代码只会编译到H5的发行包里，其他平台的包不会包含如上代码。

• 运行期判断 运行期判断是指代码已经打入包中，仍然需要在运行期判断平台，此时可使用 uni.getSystemInfoSync().platform 判断客户端环境是 Android、iOS 还是小程序开发工具（在百度小程序开发工具、微信小程序开发工具、支付宝小程序开发工具中使用 uni.getSystemInfoSync().platform 返回值均为 devtools）。

switch(uni.getSystemInfoSync().platform){
    case 'android':
       console.log('运行Android上')
       break;
    case 'ios':
       console.log('运行iOS上')
       break;
    default:
       console.log('运行在开发者工具上')
       break;
}

如有必要，也可以在条件编译里自己定义一个变量，赋不同值。在后续运行代码中动态判断环境。