uni-app学习笔记（二）

---

五、常用组件

视图容器

view

它类似于传统html中的div，用于包裹各种元素内容。

属性说明

属性名	类型	默认值	说明
hover-class	String	none	指定按下去的样式类。当 hover-class=“none” 时，没有点击态效果
hover-stop-propagation	Boolean	false	指定是否阻止本节点的祖先节点出现点击态（是否阻止冒泡）
hover-start-time	Number	50	按住后多久出现点击态，单位毫秒
hover-stay-time	Number	400	手指松开后点击态保留时间，单位毫秒

scroll-view

可滚动视图区域，用于区域滚动。

使用竖向滚动时，需要给 <scroll-view> 一个固定高度，通过 css 设置 height；使用横向滚动时，需要给<scroll-view>添加white-space: nowrap;样式。

属性说明

属性名	类型	默认值	说明	平台差异说明
scroll-x	Boolean	false	允许横向滚动
scroll-y	Boolean	false	允许纵向滚动
upper-threshold	Number/String	50	距顶部/左边多远时（单位px），触发 scrolltoupper 事件
lower-threshold	Number/String	50	距底部/右边多远时（单位px），触发 scrolltolower 事件
scroll-top	Number/String		设置竖向滚动条位置
scroll-left	Number/String		设置横向滚动条位置
scroll-into-view	String		值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素
scroll-with-animation	Boolean	false	在设置滚动条位置时使用动画过渡
enable-back-to-top	Boolean	false	iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向	app-nvue，微信小程序
show-scrollbar	Boolean	true	控制是否出现滚动条	App-nvue 2.1.5+
refresher-enabled	Boolean	false	开启自定义下拉刷新	H5、app-vue 2.5.12+,微信小程序基础库2.10.1+、小红书小程序
refresher-threshold	Number	45	设置自定义下拉刷新阈值	H5、app-vue 2.5.12+,微信小程序基础库2.10.1+、小红书小程序
refresher-default-style	String	“black”	设置自定义下拉刷新默认样式，支持设置 black，white，none，none 表示不使用默认样式	H5、app-vue 2.5.12+,微信小程序基础库2.10.1+、小红书小程序
refresher-background	String	“#FFF”	设置自定义下拉刷新区域背景颜色	H5、app-vue 2.5.12+,微信小程序基础库2.10.1+、小红书小程序

swiper

滑块视图容器，一般用于左右滑动或上下滑动，比如banner轮播图。

注意滑动切换和滚动的区别，滑动切换是一屏一屏的切换。swiper下的每个swiper-item是一个滑动切换区域，不能停留在2个滑动区域之间。

属性说明

属性名	类型	默认值	说明	平台差异说明
indicator-dots	Boolean	false	是否显示面板指示点
indicator-color	Color	rgba(0, 0, 0, .3)	指示点颜色
indicator-active-color	Color	#000000	当前选中的指示点颜色
active-class	String		swiper-item 可见时的 class	支付宝小程序
changing-class	String		acceleration 设置为 true 时且处于滑动过程中，中间若干屏处于可见时的class	支付宝小程序
autoplay	Boolean	false	是否自动切换
current	Number	0	当前所在滑块的 index
current-item-id	String		当前所在滑块的 item-id ，不能与 current 被同时指定	支付宝小程序不支持、小红书小程序不支持
interval	Number	5000	自动切换时间间隔
duration	Number	500	滑动动画时长	app-nvue不支持
circular	Boolean	false	是否采用衔接滑动，即播放到末尾后重新回到开头
vertical	Boolean	false	滑动方向是否为纵向
previous-margin	String	0px	前边距，可用于露出前一项的一小部分，接受 px 和 rpx 值	app-nvue、抖音小程序、飞书小程序不支持
next-margin	String	0px	后边距，可用于露出后一项的一小部分，接受 px 和 rpx 值	app-nvue、抖音小程序、飞书小程序不支持
acceleration	Boolean	false	当开启时，会根据滑动速度，连续滑动多屏	支付宝小程序
disable-programmatic-animation	Boolean	false	是否禁用代码变动触发 swiper 切换时使用动画。	支付宝小程序
display-multiple-items	Number	1	同时显示的滑块数量	app-nvue、支付宝小程序不支持、小红书小程序不支持
skip-hidden-item-layout	Boolean	false	是否跳过未显示的滑块布局，设为 true 可优化复杂情况下的滑动性能，但会丢失隐藏状态滑块的布局信息	App、微信小程序、京东小程序
disable-touch	Boolean	false	是否禁止用户 touch 操作	App 2.5.5+、H5 2.5.5+、支付宝小程序
easing-function	String	default	指定 swiper 切换缓动动画类型，有效值：default、linear、easeInCubic、easeOutCubic、easeInOutCubic	微信小程序、快手小程序、京东小程序
@change	EventHandle		current 改变时会触发 change 事件，event.detail = {current: current, source: source}
@transition	EventHandle		swiper-item 的位置发生改变时会触发 transition 事件，event.detail = {dx: dx, dy: dy}，支付宝小程序暂不支持dx, dy	App、H5、微信小程序、支付宝小程序、抖音小程序、飞书小程序、QQ小程序、快手小程序
@animationfinish	EventHandle		动画结束时会触发 animationfinish 事件，event.detail = {current: current, source: source}	抖音小程序、飞书小程序与小红书小程序不支持

基础内容

text

文本组件，用于包裹文本内容。

属性说明

属性名	类型	默认值	说明	平台差异说明
selectable	Boolean	false	文本是否可选
user-select	Boolean	false	文本是否可选	仅微信小程序支持
space	String		显示连续空格
decode	Boolean	false	是否解码

space 值说明

值	说明
ensp	中文字符空格一半大小
emsp	中文字符空格大小
nbsp	根据字体设置的空格大小

表单组件

button

按钮。

input

单行输入框。

路由与页面跳转

navigator

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

除了组件方式，API方式也可以实现页面跳转

属性说明

属性名	类型	默认值	说明	平台差异说明
url	String		应用内的跳转链接，值为相对路径或绝对路径，如：“…/first/first”，“/pages/first/first”，注意不能加 .vue 后缀
open-type	String	navigate	跳转方式
delta	Number		当 open-type 为 ‘navigateBack’ 时有效，表示回退的层数	支付宝小程序不支持
animation-type	String	pop-in/out	当 open-type 为 navigate、navigateBack 时有效，窗口的显示/关闭动画效果，详见：窗口动画	App
animation-duration	Number	300	当 open-type 为 navigate、navigateBack 时有效，窗口显示/关闭动画的持续时间。	App
render-link	boolean	true	是否给 navigator 组件加一层 a 标签控制 ssr 渲染	web3.7.6+、App-vue3.7.6+
hover-class	String	navigator-hover	指定点击时的样式类，当hover-class="none"时，没有点击态效果
hover-stop-propagation	Boolean	false	指定是否阻止本节点的祖先节点出现点击态	微信小程序、小红书小程序
hover-start-time	Number	50	按住后多久出现点击态，单位毫秒
hover-stay-time	Number	600	手指松开后点击态保留时间，单位毫秒
target	String	self	在哪个小程序目标上发生跳转，默认当前小程序，值域self/miniProgram	微信2.0.7+、百度2.5.2+、QQ

open-type 有效值

值	说明	平台差异说明
navigate	对应 uni.navigateTo 的功能，保留当前页面，跳转到应用内的某个页面
redirect	对应 uni.redirectTo 的功能，关闭当前页面，跳转到应用内的某个页面
switchTab	对应 uni.switchTab 的功能，跳转到 tabBar 页面，并关闭其他所有非 tabBar 页面
reLaunch	对应 uni.reLaunch 的功能，关闭所有页面，打开到应用内的某个页面	抖音小程序与飞书小程序不支持
navigateBack	对应 uni.navigateBack 的功能，关闭当前页面，返回上一页面或多级页面
exit	退出小程序，target="miniProgram"时生效	微信2.1.0+、百度2.5.2+、QQ1.4.7+、小红书小程序

媒体组件

image

图片组件。

<image> 组件未设置宽高时，默认宽度320px、高度240px。尤其注意当图片加载失败时，widthFix模式指定宽度的图片，虽然图片空白，但其高度会变成240px；

属性说明

属性名	类型	默认值	说明	平台差异说明
src	String		图片资源地址
mode	String	‘scaleToFill’	图片裁剪、缩放的模式
lazy-load	Boolean	false	图片懒加载。只针对page与scroll-view下的image有效	微信小程序、百度小程序、抖音小程序、飞书小程序、小红书小程序
fade-show	Boolean	true	图片显示动画效果	仅App-nvue 2.3.4+ Android有效
webp	boolean	false	在系统不支持webp的情况下是否单独启用webp。默认false，只支持网络资源。webp支持详见下面说明	微信小程序2.9.0、抖音小程序2.90.0
show-menu-by-longpress	boolean	false	开启长按图片显示识别小程序码菜单	微信小程序2.7.0
draggable	boolean	false	是否能拖动图片	H5 3.1.1+、App（iOS15+）
@error	HandleEvent		当错误发生时，发布到 AppService 的事件名，事件对象event.detail = {errMsg: ‘something wrong’}
@load	HandleEvent		当图片载入完毕时，发布到 AppService 的事件名，事件对象event.detail = {height:‘图片高度px’, width:‘图片宽度px’}

mode 有效值

mode 有 14 种模式，其中 5 种是缩放模式，9 种是裁剪模式。

模式	值	说明
缩放	scaleToFill	不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素
缩放	aspectFit	保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。
缩放	aspectFill	保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。
缩放	widthFix	宽度不变，高度自动变化，保持原图宽高比不变
缩放	heightFix	高度不变，宽度自动变化，保持原图宽高比不变 App 和 H5 平台 HBuilderX 2.9.3+ 支持、微信小程序需要基础库 2.10.3
裁剪	top	不缩放图片，只显示图片的顶部区域
裁剪	bottom	不缩放图片，只显示图片的底部区域
裁剪	center	不缩放图片，只显示图片的中间区域
裁剪	left	不缩放图片，只显示图片的左边区域
裁剪	right	不缩放图片，只显示图片的右边区域
裁剪	top left	不缩放图片，只显示图片的左上边区域
裁剪	top right	不缩放图片，只显示图片的右上边区域
裁剪	bottom left	不缩放图片，只显示图片的左下边区域
裁剪	bottom right	不缩放图片，只显示图片的右下边区域

更多组件

https://uniapp.dcloud.net.cn/component/

六、页面生命周期

官方文档 Vue3 页面及组件生命周期流程图（未更新）：

uni-app页面生命周期

Vue3组合式API中需要先从“@dcloudio/uni-app”模块中导入才可以使用

常用生命周期：

• onLoad：页面加载时触发，可以在此生命周期函数中进行页面初始化操作。（可以接收上页的参数）
• onShow：页面显示时触发，可以在此生命周期函数中进行页面展示相关的操作。
• onReady：页面初次渲染完成时触发，可以在此生命周期函数中进行页面渲染完成后的操作。（在onMounted前，但作用类似）
• onHide：页面隐藏时触发，可以在此生命周期函数中进行页面隐藏相关的操作。
• onUnload：页面卸载时触发，可以在此生命周期函数中进行页面卸载相关的操作。

执行顺序：

应用生命周期（onLaunch > onShow） > onLoad > onShow > onBeforeMount > 组件生命周期 > onReady > onMounted

应用的onShow、onHide > 页面的onShow、onHide

七、全局文件

page.json 页面路由

用来对 uni-app 进行全局配置，决定页面文件的路径、窗口样式、原生的导航栏、底部的原生 tabbar 等。导航栏高度为 44px (不含状态栏)，tabBar 高度为 50px (不含安全区)。

pages（必填）：设置页面路径及窗口表现（优先级大于全局样式）

"pages": [{"path": "pages/index/index","style": { ... }}, {"path": "pages/login/login","style": { ... }}
]

easycom：组件自动引入规则，默认开启，可以自定义细节

globalStyle：设置应用状态栏、导航条、标题、窗口背景色等全局样式

tabBar：设置底部 tab 的表现

Tips：

• 当设置 position 为 top 时，将不会显示 icon
• tabBar 中的 list 是一个数组，只能配置最少 2 个、最多 5 个 tab，tab 按数组的顺序排序。
• tabbar 切换第一次加载时可能渲染不及时，可以在每个 tabbar 页面的 onLoad 生命周期里先弹出一个等待雪花（hello uni-app 使用了此方式）
• tabbar 的页面展现过一次后就保留在内存中，再次切换 tabbar 页面，只会触发每个页面的 onShow，不会再触发 onLoad。
• 顶部的 tabbar 目前仅微信小程序上支持。需要用到顶部选项卡的话，建议不使用 tabbar 的顶部设置，而是自己做顶部选项卡，可参考 hello uni-app->模板->顶部选项卡。

"tabBar": {...// 样式"list": [{// 页面路径，必须在 pages 中先定义"pagePath": "pages/component/index",// 图片路径，icon大小限制为40kb，建议尺寸为81px*81px，当position为top时，此参数无效，不支持网络图片和字体图标"iconPath": "static/image/icon_component.png",// 选中时的图片路径，icon大小限制为40kb，建议尺寸为81px*81px，当position为top时，此参数无效"selectedIconPath": "static/image/icon_component_HL.png",// tab 上按钮文字"text": "组件",// 字体图标，优先级高于 iconPath"iconfont": {"text": "\ue642", // 已实际字体编码为准"selectedText": "\ue776","fontSize": "17px","color": "#000000","selectedColor": "#0000ff"}},{"pagePath": "pages/API/index","iconPath": "static/image/icon_API.png","selectedIconPath": "static/image/icon_API_HL.png","text": "接口"}]
}

manifest.json 应用配置

用于指定应用的名称、图标、权限等。

vite.config.js

Vue3项目配置文件。

八、常用API

界面

交互反馈

uni.showToast(OBJECT)：显示消息提示框。

uni.showLoading(OBJECT)：显示 loading 提示框, 需主动调用 uni.hideLoading 才能关闭提示框。

uni.showModal(OBJECT)：显示模态弹窗，可以只有一个确定按钮，也可以同时有确定和取消按钮。类似于一个API整合了 html 中的alert、confirm。

uni.showActionSheet(OBJECT)：从底部向上弹出操作菜单

动态设置导航条

uni.setNavigationBarTitle(OBJECT)

uni.setNavigationBarColor(OBJECT)

uni.showNavigationBarLoading(OBJECT)

uni.hideNavigationBarLoading(OBJECT)

uni.hideHomeButton(OBJECT)

动态设置tabBar

部分在app.vue的onLaunch中设置

页面和路由

编程式跳转api效果同navigator组件

uni.navigateBack(OBJECT)：关闭当前页面，返回上一页面或多级页面。可通过 getCurrentPages() 获取当前的页面栈，决定需要返回几层。

数据缓存

同步或异步实现本地存储。

网络

发起请求

uni.request(OBJECT)

媒体

图片

uni.previewImage(OBJECT)：预览图片。

更多API

https://uniapp.dcloud.net.cn/api/

---

总结

uniapp一套代码，多端 报错 部署，大幅减少跨端开发工作量。