uni-app的基本使用

---

uni-app简介

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、Web（响应式）、以及各种小程序（微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝）、快应用等多个平台。
即使不跨端，uni-app也是更好的小程序开发框架、更好的App跨平台框架、更方便的H5开发框架。不管领导安排什么样的项目，都可以快速交付，不需要转换开发思维、不需要更改开发习惯
具有vue和微信小程序的开发经验，可快速上手uni-app

1. 环境搭建

• 安装编辑器HbuilderX ​(应用商城下载即可）
  HBuilderX是通用的前端开发工具，但为​​uni-app​​做了特别强化。
  HBuilder 官方IDE下载地址
  下载App开发版，可开箱即用
  终打包成微信小程序就必须在微信开发者工具去预览，那么需要下载微信开发者工具了。
  安装微信开发者工具 微信开发者工具下载地址与更新日志 | 微信开放文档
• 利用HbuilderX初始化项目
  在点击工具栏里的文件 -> 新建 -> 项目（快捷键Ctrl+N）：
  
  新建一个uniapp项目，选择uni-app类型，输入工程名，选择模板，点击创建，即可成功创建。
  uni-app自带的模板有 默认的空项目模板、Hello uni-app 官方组件和API示例，还有一个重要模板是 uni ui项目模板，日常开发推荐使用该模板，已内置大量常用组件。
  会默认生成项目的基本结构。
  

2. 运行uni-app

浏览器运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到浏览器 -> 选择浏览器，即可体验 uni-app 的 web 版。

运行App到手机或模拟器：使用电压足够的usb端口连接手机，设置中开启USB调试，手机上允许电脑设备调试手机，进入hello-uniapp项目，点击工具栏的运行 -> 运行App到手机或模拟器，即可在该设备里面体验uni-app。

在微信开发者工具里运行：进入hello-uniapp项目，点击工具栏的运行 -> 运行到小程序模拟器 -> 微信开发者工具，即可在微信开发者工具里面体验uni-app。

注意：如果是第一次使用，需要先配置小程序ide的相关路径，才能运行成功。如下图，需在输入框输入微信开发者工具的安装路径。

注意：微信开发者工具需要开启服务端口 在微信工具的设置->安全中。
其他的方式的运行暂不进行介绍 可以
uni-app官网

3.介绍项目目录和文件作用

4.开发规范概述

为了实现多端兼容，综合考虑编译速度、运行性能等因素，uni-app约定了如下开发规范：
1. 页面文件遵循Vue单文件组件规范
2. 组件标签靠近小程序规范，详细见uni-app组件规范
3. 接口能力（js api）靠近微信小程序规范，但需将前缀wx替换为uni，详见uni-app接口规范
4. 数据绑定及事件处理同Vue.js规范，同时补充了App以及页面的生命周期
5. 为兼容多端运行，建议使用flex布局进行开发

全局配置和页面配置

1. 通过globalStyle进行全局配置

用于设置应用的状态栏、导航条、标题、窗口背景色等。​

属性	类型	默认值	秒速	平台差异说明
navigationBarBackgroundColor	HexColor	#F8F8F8	导航栏背景颜色（同状态栏背景色）	APP与H5为#F8F8F8，小程序平台请参考相应小程序文档
navigationBarTextStyle	String	black	导航栏标题颜色及状态栏前景颜色，仅支持 black/white	支付宝小程序不支持，请使用 my.setNavigationBar
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持 default/custom。custom即取消默认的原生导航栏，需看使用注意	微信小程序 7.0+、百度小程序、H5、App（2.0.3+）
backgroundColor	HexColor	#ffffff	下拉显示出来的窗口的背景色	微信小程序
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark / light	微信小程序
enablePullDownRefresh	Boolean	false	是否开启下拉刷新
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位只支持px，
backgroundColorTop	HexColor	#ffffff	顶部窗口的背景色（bounce回弹区域）	仅 iOS 平台
backgroundColorBottom	HexColor	#ffffff	底部窗口的背景色（bounce回弹区域）	仅 iOS 平台
titleImage	String		导航栏图片地址（替换当前文字标题），支付宝小程序内必须使用https的图片链接地址	支付宝小程序、H5、APP
transparentTitle	String	none	导航栏整体（前景、背景）透明设置。支持 always 一直透明 / auto 滑动自适应 / none 不透明	支付宝小程序、H5、APP
titlePenetrate	String	NO	导航栏点击穿透	支付宝小程序、H5
pageOrientation	String	portrait	横屏配置，屏幕旋转设置，仅支持 auto / portrait / landscape	App 2.4.7+、微信小程序、QQ小程序
animationType	String	pop-in	窗口显示的动画效果，	App
animationDuration	Number	300	窗口显示动画的持续时间，单位为 ms	App
app-plus	Object		设置编译到 App 平台的特定样式	App
h5	Object		设置编译到 H5 平台的特定样式	H5
mp-alipay	Object		设置编译到 mp-alipay 平台的特定样式	支付宝小程序
mp-weixin	Object		设置编译到 mp-weixin 平台的特定样式，	微信小程序
mp-baidu	Object		设置编译到 mp-baidu 平台的特定样式，	百度小程序
mp-toutiao	Object		设置编译到 mp-toutiao 平台的特定样式	抖音小程序
mp-lark	Object		设置编译到 mp-lark 平台的特定样式	抖音小程序
mp-qq	Object		设置编译到 mp-qq 平台的特定样式	飞书小程序
mp-kuaishou	Object		设置编译到 mp-kuaishou 平台的特定样式	快手小程序
mp-jd	Object		设置编译到 mp-jd 平台的特定样式	京东小程序
usingComponents	Object		引用小程序组件	抖音小程序
renderingMode	String		同层渲染，webrtc(实时音视频) 无法正常时尝试配置 seperated 强制关掉同层	微信小程序
leftWindow	Boolean	true	当存在 leftWindow 时，默认是否显示 leftWindow	H5
topWindow	Boolean	true	当存在 topWindow 时，默认是否显示 topWindow	H5
rightWindow	Boolean	true	当存在 rightWindow 时，默认是否显示 rightWindow	H5
rpxCalcMaxDeviceWidth	Number	960	rpx 计算所支持的最大设备宽度，单位 px	App（vue2 且不含 nvue）、H5（2.8.12+）
rpxCalcBaseDeviceWidth	Number	375	rpx 计算使用的基准设备宽度，设备实际宽度超出 rpx 计算所支持的最大设备宽度时将按基准宽度计算，单位 px	App（vue2 且不含 nvue）、H5（2.8.12+）
rpxCalcIncludeWidth	Number	750	rpx 计算特殊处理的值，始终按实际的设备宽度计算，单位 rpx	App（vue2 且不含 nvue）、H5（2.8.12+）
dynamicRpx	Boolean	false	动态 rpx，屏幕大小变化会重新渲染 rpx	App-nvue（vue3 固定值为 true） 3.2.13+
maxWidth	Number		单位px，当浏览器可见区域宽度大于maxWidth时，两侧留白，当小于等于maxWidth时，页面铺满；不同页面支持配置不同的maxWidth；maxWidth = leftWindow(可选)+page(页面主体)+rightWindow(可选)	H5（2.9.9+）

注意：
支付宝小程序使用titleImage时必须使用https的图片链接地址，需要真机调试才能看到效果，支付宝开发者工具内无效果
globalStyle中设置的titleImage也会覆盖掉pages->style内的设置文字标题
使用 maxWidth 时，页面内fixed元素需要使用–window-left,–window-right来保证布局位置正确
dynamicRpx vue3 nvue页面已移除此配置，升级为横竖屏切换自动rpx，如果不需要可以使用 px

"globalStyle": {
	"navigationBarTextStyle": "#fff",
	"navigationBarTitleText": "琅琊榜",
	"navigationBarBackgroundColor": "#f0a1a8",
	"backgroundColor": "#f0a1a8"
},

注： ：如果你没有修改完全成功，或者都不生效，可能是设置了页面的配置样式导致的，它会覆盖掉全局样式配置中相同属性的样式。这是因为页面配置优先级高于全局配置。我们删除掉页面配置样式即可。

"pages": [ //pages数组中第一项表示应用启动页，参考：https://uniapp.dcloud.io/collocation/pages
		{
			"path": "pages/index/index",
			"style": {
				// "navigationBarTitleText": "uni-app" 注释掉
			}
		}
	],

下拉刷新设置

"globalStyle": {
		"navigationBarTextStyle": "white",
		"navigationBarTitleText": "琅琊榜",
		"navigationBarBackgroundColor": "#f0a1a8",
		"backgroundColor": "#d0d3da",
		"enablePullDownRefresh": true,
		"backgroundTextStyle": "dark"
	},

2. page.json （页面路由配置）

uni-app 通过 pages 节点配置应用由哪些页面组成，pages 节点接收一个数组，数组每个项都是一个对象，其属性值如下：

属性	类型	默认值	描述
path	String		配置页面路径
style	Object		配置页面窗口表现

• pages节点的第一项为应用入口页（即首页）
• 应用中新增/减少页面，都需要对 pages 数组进行修改
• 文件名不需要写后缀，框架会自动寻找路径下的页面资源
  通过style修改页面的标题和导航栏背景色，并且设置h5下拉刷新的特有样式

{
	"path": "pages/index/index",
		"style": {
			"navigationBarBackgroundColor": "#007AFF",
			"navigationBarTextStyle": "black",
			"enablePullDownRefresh": true, // 开启下拉刷新
			"disableScroll": true, // 不允许滚动
			"h5": {
				// h5下拉刷新是蓝色，
				"pullToRefresh": {
					"color": "#007AFF"
				}
			}
			// "navigationBarTitleText": "uni-app"
		}
	}

3. tabbar

如果应用是一个多 tab 应用，可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页。

注意：

• 当设置 position 为 top 时，将不会显示 icon
• tabBar 中的 list 是一个数组，只能配置最少2个、最多5个 tab，tab 按数组的顺序排序。

属性	类型	必填	默认值	描述	平台差异说明
color	HexColor	是		tab上的文字默认颜色
selectColor	HexColor	是		tab上的文字选中时的颜色
backgroundColor	HexColor	是		tab的背景颜色
borderStyle	String	否	black	tabbar 上边框的颜色，仅支持 black/white	App 2.3.4+ 支持其他颜色值
list	Array	是		tab 的列表，详见 list 属性说明，最少2个、最多5个 tab
position	String	否	bottom	可选值 bottom、top	top 值仅微信小程序支持
midButton	Object	否	bottom	中间按钮 仅在 list 项为偶数时有效	App 2.3.4+、H5 3.0.0+
list属性

属性	类型	必填	说明	平台差异
pagePath	String	是	页面路径，必须在 pages 中先定义
text	String	是	tab 上按钮文字，在 App 和 H5 平台为非必填。例如中间可放一个没有文字的+号图标
iconPath	String	否	图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px，当 position 为 top 时，此参数无效，不支持网络图片，不支持字体图标
selectedIconPath	String	否	选中时的图片路径，icon 大小限制为40kb，建议尺寸为 81px * 81px ，当 position 为 top 时，此参数无效
visible	Boolean	否	该项是否显示，默认显示	App (3.2.10+)、H5 (3.2.10+)
iconfont	Object	否	字体图标，优先级高于 iconPath	App（3.4.4+）、H5 (3.5.3+)

"tabBar": {
	// "iconfontSrc": "./css/font/iconfont.ttf",
	"list": [
		{
			"text": "首页",
			"pagePath": "pages/index/index",
			"iconPath": "static/du.png",
			"selectedIconPath": "static/du.png"
			// "iconfont": {
			// 	"text": "\ue64e",
			// 	"color": "#515151"
			// }
		},
		{
			"text": "商品",
			"pagePath": "pages/goods/index",
			"iconPath": "static/jie.png"
		}
	]
},

注意：

1. 在tabbar中运用iconfont图标，在小程序中不生效，在h5页面生效
   原因是：iconfont属性支持App（3.4.4+）和H5 (3.5.3+)
2. iconfont的图标运行
   text属性是 \u 进行拼接

   "iconfontSrc": "./css/font/iconfont.ttf",
   "iconfont": {
   	"text": "\ue64e",
   	"color": "#515151"
   }
   

3. position 设置为top时图标消失
   

3. condition启动模式配置

启动模式配置，仅开发期间生效，用于模拟直达页面的场景，如：小程序转发后，用户点击所打开的页面。
属性说明

属性	类型	是否必填	描述
current	Number	是	当前激活的模式，List 节点的索引值
list	Array	是	启动模式列表

list属性说明

属性	类型	是否必填	描述
name	String	是	启动模式名称
path	String	是	启动页面路径
query	String	是	启动参数，可在也页面的onLoad函数里获得