【uni-app教程】二、UniAPP 初始化相关配置

二、UniAPP 初始化相关配置

---

(1)工程目录结构

https://uniapp.dcloud.net.cn/tutorial/project.html#目录结构)

工程简介

一个工程，就是一个 Vue 项目，你可以通过 HBuilderX 或 cli 方式快速创建 uni-app 工程，详见：快速上手。

目录结构

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

┌─uniCloud              云空间目录，阿里云为uniCloud-aliyun,腾讯云为uniCloud-tcb（详见uniCloud）
│─components            符合vue组件规范的uni-app组件目录
│  └─comp-a.vue         可复用的a组件
├─utssdk                存放uts文件
├─pages                 业务页面文件存放的目录
│  ├─index
│  │  └─index.vue       index页面
│  └─list
│     └─list.vue        list页面
├─static                存放应用引用的本地静态资源（如图片、视频等）的目录，注意：静态资源只能存放于此
├─uni_modules           存放[uni_module](/uni_modules)。
├─platforms             存放各平台专用页面的目录，详见
├─nativeplugins         App原生语言插件 详见
├─nativeResources       App端原生资源目录
│  └─android            Android原生资源目录 详见
├─hybrid                App端存放本地html文件的目录，详见
├─wxcomponents          存放小程序组件的目录，详见
├─unpackage             非工程代码，一般存放运行或发行的编译结果
├─AndroidManifest.xml   Android原生应用清单文件 详见
├─main.js               Vue初始化入口文件
├─App.vue               应用配置，用来配置App全局样式以及监听 应用生命周期
├─manifest.json         配置应用名称、appid、logo、版本等打包信息，详见
├─pages.json            配置页面路由、导航条、选项卡等页面类信息，详见
└─uni.scss              这里是uni-app内置的常用样式变量
	

static目录 使用注意

• 编译到任意平台时，static 目录下除不满足条件编译的文件，会直接复制到最终的打包目录，不会打包编译。非 static 目录下的文件（vue、js、css 等）只有被引用时，才会被打包编译。（static 下目录的 js 文件不会被 webpag编译，里面如果有 es6的代码，不经过转换直接运行，在手机设备上会报错。）
• css、less/scss 等资源不要放在 static 目录下，建议这些公用的资源放在自建的 common 目录下。

Tips

• HbuilderX 1.9.0+ 支持在根目录创建 ext.json、sitemap.json 等小程序需要的文件。

(2) 应用配置 manifest.json

manifest.json 文件是应用的配置文件，用于指定应用的名称、图标、权限等，我们也可以在这里为Vue 为
H5设置跨域拦截处理器

(3)编译配置 vue.config.js

vue.config.js是一个可选的配置文件，如果项目的根目录中存在这个文件，那么它会被自动加载，一般用
于配置 webpack 等编译选项。官方文档

(4)全局配置 page.json

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

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

配置项列表

属性	类型	必填	描述	平台兼容
globalStyle	Object	否	设置默认页面的窗口表现
pages	Object Array	是	设置页面路径及窗口表现
easycom	Object	否	组件自动引入规则	2.5.5+
tabBar	Object	否	设置底部 tab 的表现
condition	Object	否	启动模式配置
subPackages	Object Array	否	分包加载配置
preloadRule	Object	否	分包预下载规则	微信小程序
workers	String	否	Worker 代码放置的目录	微信小程序
leftWindow	Object	否	大屏左侧窗口	H5
topWindow	Object	否	大屏顶部窗口	H5
rightWindow	Object	否	大屏右侧窗口	H5
uniIdRouter	Object	否	自动跳转相关配置，新增于HBuilderX 3.5.0
entryPagePath	String	否	默认启动首页，新增于HBuilderX 3.7.0

以下是一个包含了所有配置选项的 pages.json ：

{
	"pages": [{
		"path": "pages/component/index",
		"style": {
			"navigationBarTitleText": "组件"
		}
	}, {
		"path": "pages/API/index",
		"style": {
			"navigationBarTitleText": "接口"
		}
	}, {
		"path": "pages/component/view/index",
		"style": {
			"navigationBarTitleText": "view"
		}
	}],
	"condition": { //模式配置，仅开发期间生效
		"current": 0, //当前激活的模式（list 的索引项）
		"list": [{
			"name": "test", //模式名称
			"path": "pages/component/view/index" //启动页面，必选
		}]
	},
	"globalStyle": {
		"navigationBarTextStyle": "black",
		"navigationBarTitleText": "演示",
		"navigationBarBackgroundColor": "#F8F8F8",
		"backgroundColor": "#F8F8F8",
		"usingComponents":{
			"collapse-tree-item":"/components/collapse-tree-item"
		},
		"renderingMode": "seperated", // 仅微信小程序，webrtc 无法正常时尝试强制关闭同层渲染
		"pageOrientation": "portrait", //横屏配置，全局屏幕旋转设置(仅 APP/微信/QQ小程序)，支持 auto / portrait / landscape
		"rpxCalcMaxDeviceWidth": 960,
		"rpxCalcBaseDeviceWidth": 375,
		"rpxCalcIncludeWidth": 750
	},
	"tabBar": {
		"color": "#7A7E83",
		"selectedColor": "#3cc51f",
		"borderStyle": "black",
		"backgroundColor": "#ffffff",
		"height": "50px",
		"fontSize": "10px",
		"iconWidth": "24px",
		"spacing": "3px",
    	"iconfontSrc":"static/iconfont.ttf", // app tabbar 字体.ttf文件路径 app 3.4.4+
		"list": [{
			"pagePath": "pages/component/index",
			"iconPath": "static/image/icon_component.png",
			"selectedIconPath": "static/image/icon_component_HL.png",
			"text": "组件",
      		"iconfont": { // 优先级高于 iconPath，该属性依赖 tabbar 根节点的 iconfontSrc
       			"text": "\ue102",
        		"selectedText": "\ue103",
        		"fontSize": "17px",
        		"color": "#000000",
        		"selectedColor": "#0000ff"
      		}
		}, {
			"pagePath": "pages/API/index",
			"iconPath": "static/image/icon_API.png",
			"selectedIconPath": "static/image/icon_API_HL.png",
			"text": "接口"
		}],
		"midButton": {
			"width": "80px",
			"height": "50px",
			"text": "文字",
			"iconPath": "static/image/midButton_iconPath.png",
			"iconWidth": "24px",
			"backgroundImage": "static/image/midButton_backgroundImage.png"
		}
	},
  "easycom": {
    "autoscan": true, //是否自动扫描组件
    "custom": {//自定义扫描规则
      "^uni-(.*)": "@/components/uni-$1.vue"
    }
  },
  "topWindow": {
    "path": "responsive/top-window.vue",
    "style": {
      "height": "44px"
    }
  },
  "leftWindow": {
    "path": "responsive/left-window.vue",
    "style": {
      "width": "300px"
    }
  },
  "rightWindow": {
    "path": "responsive/right-window.vue",
    "style": {
      "width": "300px"
    },
    "matchMedia": {
      "minWidth": 768
    }
  }
}

(5) 全局样式 uni.scss

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

uni-app 官方扩展插件（uni ui）及 插件市场 上很多三方插件均使用了这些样式变量，如果你是插件开发者，建议你使用 scss 预处理，并在插件代码中直接使用这些变量（无需 import 这个文件），方便用户通过搭积木的方式开发整体风格一致的App。

uni.scss是一个特殊文件，在代码中无需 import 这个文件即可在scss代码中使用这里的样式变量。uni-app的编译器在webpack配置中特殊处理了这个uni.scss，使得每个scss文件都被注入这个uni.scss，达到全局可用的效果。如果开发者想要less、stylus的全局使用，需要在vue.config.js中自行配置webpack策略。

注意：

1. 如要使用这些常用变量，需要在 HBuilderX 里面安装 scss 插件；
2. 使用时需要在 style 节点上加上 lang="scss"。

<style lang="scss">
</style>

1. pages.json不支持scss，原生导航栏和tabbar的动态修改只能使用js api

以下是 uni.scss 的相关变量：

/* 颜色变量 */

/* 行为相关颜色 */
$uni-color-primary: #007aff;
$uni-color-success: #4cd964;
$uni-color-warning: #f0ad4e;
$uni-color-error: #dd524d;

/* 文字基本颜色 */
$uni-text-color:#333;//基本色
$uni-text-color-inverse:#fff;//反色
$uni-text-color-grey:#999;//辅助灰色，如加载更多的提示信息
$uni-text-color-placeholder: #808080;
$uni-text-color-disable:#c0c0c0;

/* 背景颜色 */
$uni-bg-color:#ffffff;
$uni-bg-color-grey:#f8f8f8;
$uni-bg-color-hover:#f1f1f1;//点击状态颜色
$uni-bg-color-mask:rgba(0, 0, 0, 0.4);//遮罩颜色

/* 边框颜色 */
$uni-border-color:#c8c7cc;

/* 尺寸变量 */

/* 文字尺寸 */
$uni-font-size-sm:24rpx;
$uni-font-size-base:28rpx;
$uni-font-size-lg:32rpx;

/* 图片尺寸 */
$uni-img-size-sm:40rpx;
$uni-img-size-base:52rpx;
$uni-img-size-lg:80rpx;

/* Border Radius */
$uni-border-radius-sm: 4rpx;
$uni-border-radius-base: 6rpx;
$uni-border-radius-lg: 12rpx;
$uni-border-radius-circle: 50%;

/* 水平间距 */
$uni-spacing-row-sm: 10px;
$uni-spacing-row-base: 20rpx;
$uni-spacing-row-lg: 30rpx;

/* 垂直间距 */
$uni-spacing-col-sm: 8rpx;
$uni-spacing-col-base: 16rpx;
$uni-spacing-col-lg: 24rpx;

/* 透明度 */
$uni-opacity-disabled: 0.3; // 组件禁用态的透明度

/* 文章场景相关 */
$uni-color-title: #2C405A; // 文章标题颜色
$uni-font-size-title:40rpx;
$uni-color-subtitle: #555555; // 二级标题颜色
$uni-font-size-subtitle:36rpx;
$uni-color-paragraph: #3F536E; // 文章段落颜色
$uni-font-size-paragraph:30rpx;

(6)App.vue

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

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

应用生命周期仅可在App.vue中监听，在页面监听无效。

应用生命周期

uni-app 支持如下应用生命周期函数：

函数名	说明
onLaunch	当uni-app 初始化完成时触发（全局只触发一次）
onShow	当 uni-app 启动，或从后台进入前台显示
onHide	当 uni-app 从前台进入后台
onError	当 uni-app 报错时触发
onUniNViewMessage	对 nvue 页面发送的数据进行监听，可参考 nvue 向 vue 通讯
onUnhandledRejection	对未处理的 Promise 拒绝事件监听函数（2.8.1+）
onPageNotFound	页面不存在监听函数
onThemeChange	监听系统主题变化

示例代码

<script>
	// 只能在App.vue里监听应用的生命周期
	export default {
		onLaunch: function() {
			console.log('App Launch')
		},
		onShow: function() {
			console.log('App Show')
		},
		onHide: function() {
			console.log('App Hide')
		}
	}
</script>

注意

• 应用生命周期仅可在App.vue中监听，在其它页面监听无效。
• 应用启动参数，可以在API uni.getLaunchOptionsSync获取，详见
• onlaunch里进行页面跳转，如遇白屏报错，请参考https://ask.dcloud.net.cn/article/35942
• App.vue 不能写模板
• onPageNotFound 页面实际上已经打开了（比如通过分享卡片、小程序码）且发现页面不存在，才会触发，api 跳转不存在的页面不会触发（如 uni.navigateTo）

(7) 入口文件 main.js

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

首先引入了Vue库和App.vue，创建了一个vue实例，并且挂载vue实例。

import Vue from 'vue'
import App from './App'
import pageHead from './components/page-head.vue' //全局引用 page-head 组件

Vue.config.productionTip = false
Vue.component('page-head', pageHead) //全局注册 page-head 组件，每个页面将可以直接使用该组件
App.mpType = 'app'

const app = new Vue({
...App
})
app.$mount() //挂载 Vue 实例

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

可以引用vuex，因涉及多个文件，此处没有提供示例，详见hello uni-app示例工程。

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

注意

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

(8) UniAPP 开发规范及资源路径

1.基本语言和开发规范

uni-app代码编写，基本语言包括js、vue、css。以及ts、scss等css预编译器。

在app端，还支持原生渲染的nvue，以及可以编译为kotlin和swift的uts。

DCloud还提供了使用js编写服务器代码的uniCloud云引擎。所以只需掌握js，你可以开发web、Android、iOS、各家小程序以及服务器等全栈应用。

开发规范约定

为了实现多端兼容，综合考虑编译速度、运行性能等因素，uni-app 约定了如下开发规范：

• 页面文件遵循 Vue 单文件组件 (SFC) 规范，即每个页面是一个.vue文件
• 组件标签靠近小程序规范，详见uni-app 组件规范
• 接口能力（JS API）靠近小程序规范，但需将前缀 wx、my 等替换为 uni，详见uni-app接口规范
• 数据绑定及事件处理同 Vue.js 规范，同时补充了App及页面的生命周期
• 如需兼容app-nvue平台，建议使用flex布局进行开发

uni-app分编译器和运行时（runtime）。uni-app能实现一套代码、多端运行，是通过这2部分配合完成的。

编译器将开发者的代码进行编译，编译的输出物由各个终端的runtime进行解析，每个平台（Web、Android App、iOS App、各家小程序）都有各自的runtime。

2.资源路径说明

模板内引入静态资源

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 标签不可使用相对路径

#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