自学uni-app （3）uni-app的常用组件

组件列表

基础组件分为以下八大类：

视图容器（View Container）：

组件名	说明
view	视图容器，类似于HTML中的div
scroll-view	可滚动视图容器
swiper	滑块视图容器

基础内容（Basic Content）：

组件名	说明
icon	图标
text	文字
rich-text	富文本
progress	进度条

表单组件（Form）：

标签名	说明
button	按钮
form	表单
input	输入框
checkbox	多项选择器
radio	单项选择器
picker	弹出式列表选择器
picker-view	窗体内嵌式列表选择器
slider	滑动选择器
switch	开关选择器
label	标签

导航（Navigation）：

组件名	说明
navigator	页面链接。类似于HTML中的a标签

媒体组件（Media）：

组件名	说明
audio	音频
camera	相机
image	图片
video	视频
live-player	直播播放
live-pusher	实时音视频录制，也称直播推流

地图（Map）：

组件名	说明
map	地图

画布（Canvas）：

组件名	说明
canvas	画布

webview（Web-view）：

组件名	说明
web-view	web浏览器组件

各平台专有组件

在小程序平台和weex平台，还有一些专有组件，比如open-data

常用组件

1. 文本类

text

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

属性说明

属性名	类型	默认值	说明
selectable	Boolean	false	文本是否可选
space	String		显示连续空格
decode	Boolean	false	是否解码

space 值说明

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

注：

• <text> 组件内只能嵌套 <text>
• 各个操作系统的space标准并不一致。
• 如果使用 <span> 组件编译时会被转换为 <text>。

textarea

多行输入框。

属性说明

属性名	类型	默认值	说明	平台差异说明
value	String		输入框的内容
placeholder	String		输入框为空时占位符
placeholder-style	String		指定 placeholder 的样式
placeholder-class	String	textarea-placeholder	指定 placeholder 的样式类	字节跳动小程序不支持
disabled	Boolean	false	是否禁用
maxlength	Number	140	最大输入长度，设置为 -1 的时候不限制最大长度
focus	Boolean	false	获取焦点	在 H5 平台能否聚焦以及软键盘是否跟随弹出，取决于当前浏览器本身的实现。
auto-height	Boolean	false	是否自动增高，设置auto-height时，style.height不生效
fixed	Boolean	false	如果 textarea 是在一个 position:fixed 的区域，需要显示指定属性 fixed 为 true	微信小程序、百度小程序、字节跳动小程序、QQ小程序
cursor-spacing	Number	0	指定光标与键盘的距离，单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离	App、微信小程序、百度小程序、字节跳动小程序、QQ小程序
cursor	Number		指定focus时的光标位置	微信小程序、App、H5、百度小程序、字节跳动小程序、QQ小程序
show-confirm-bar	Boolean	true	是否显示键盘上方带有”完成“按钮那一栏	微信小程序、百度小程序、QQ小程序
selection-start	Number	-1	光标起始位置，自动聚焦时有效，需与selection-end搭配使用	微信小程序、App、H5、百度小程序、字节跳动小程序、QQ小程序
selection-end	Number	-1	光标结束位置，自动聚焦时有效，需与selection-start搭配使用	微信小程序、App、H5、百度小程序、字节跳动小程序、QQ小程序
adjust-position	Boolean	true	键盘弹起时，是否自动上推页面	App-Android（softinputMode 为 adjustResize 时无效）、微信小程序、百度小程序、QQ小程序
disable-default-padding	boolean	false	是否去掉 iOS 下的默认内边距	微信小程序2.10.0
hold-keyboard	boolean	false	focus时，点击页面的时候不收起键盘	微信小程序2.8.2
@focus	EventHandle		输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度	仅微信小程序、App（HBuilderX 2.0+ nvue uni-app模式） 、QQ小程序支持 height
@blur	EventHandle		输入框失去焦点时触发，event.detail = {value, cursor}
@linechange	EventHandle		输入框行数变化时调用，event.detail = {height: 0, heightRpx: 0, lineCount: 0}	字节跳动小程序不支持,nvue ios暂不支持
@input	EventHandle		当键盘输入时，触发 input 事件，event.detail = {value, cursor}， @input 处理函数的返回值并不会反映到 textarea 上
@confirm	EventHandle		点击完成时， 触发 confirm 事件，event.detail = {value: value}	微信小程序、百度小程序、QQ小程序
@keyboardheightchange	eventhandle		键盘高度发生变化的时候触发此事件，event.detail = {height: height, duration: duration}	微信小程序2.7.0

2.按钮、选择器类

button

按钮组件。

属性说明

属性名	类型	默认值	说明
size	String	default	按钮的大小
type	String	default	按钮的样式类型
plain	Boolean	false	按钮是否镂空，背景色透明
disabled	Boolean	false	是否禁用
loading	Boolean	false	是否带加载图标
form-type	String		用于 <form> 组件，点击分别会触发 <form> 组件的 submit/reset 事件
hover-class	String	button-hover	指定按钮按下去的样式类。当 hover-class=“none” 时，没有点击态效果
hover-start-time	Number	20	按住后多久出现点击态，单位毫秒
hover-stay-time	Number	70	手指松开后点击态保留时间，单位毫秒
hover-stop-propagation	boolean	false	指定是否阻止本节点的祖先节点出现点击态
open-type	String		开放交互
lang	string	‘en’	指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。
session-from	string		会话来源，open-type="contact"时有效
send-message-title	string	当前标题	会话内消息卡片标题，open-type="contact"时有效
send-message-path	string	当前分享路径	会话内消息卡片点击跳转小程序路径，open-type="contact"时有效
send-message-img	string	截图	会话内消息卡片图片，open-type="contact"时有效
show-message-card	boolean	false	是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，open-type="contact"时有效
@getphonenumber	Handler		获取用户手机号回调
@getuserinfo	Handler		用户点击该按钮时，会返回获取到的用户信息，从返回参数的detail中获取到的值同uni.getUserInfo
@error	Handler		当使用开放能力时，发生错误的回调
@opensetting	Handler		在打开授权设置页并关闭后回调
@launchapp	Handler		打开 APP 成功的回调

size 有效值

值	说明
default	默认大小
mini	小尺寸

type 有效值

值	说明
primary	微信小程序、360小程序为绿色，App、H5、百度小程序、支付宝小程序、快应用为蓝色，字节跳动小程序为红色，QQ小程序为浅蓝色。如想在多端统一颜色，请改用default，然后自行写样式
default	白色
warn	红色

form-type 有效值

值	说明
submit	提交表单
reset	重置表单

open-type 有效值

值	说明
feedback	打开“意见反馈”页面，用户可提交反馈内容并上传日志
share	触发用户转发
getUserInfo	获取用户信息，可以从@getuserinfo回调中获取到用户信息，包括头像、昵称等信息
contact	打开客服会话，如果用户在会话中点击消息卡片后返回应用，可以从 @contact 回调中获得具体信息
getPhoneNumber	获取用户手机号，可以从@getphonenumber回调中获取到用户信息
launchApp	打开APP，可以通过app-parameter属性设定向APP传的参数
openSetting	打开授权设置页
getAuthorize	支持小程序授权
contactShare	分享到通讯录好友
lifestyle	关注生活号

radio-group

单项选择器，内部由多个 <radio> 组成。通过把多个radio包裹在一个radio-group下，实现这些radio的单选。

属性说明

属性名	类型	默认值	说明
@change	EventHandle		<radio-group> 中的选中项发生变化时触发 change 事件，event.detail = {value: 选中项radio的value}

radio

单选项目。

属性说明

属性名	类型	默认值	说明
value	String		<radio> 附带的值，用于事件传值
checked	Boolean	false	当前是否选中
disabled	Boolean	false	是否禁用
color	Color		radio的颜色，同css的color

checkbox-group

多项选择器，内部由多个 checkbox 组成。

属性说明

属性名	类型	默认值	说明
@change	EventHandle		<checkbox-group>中选中项发生改变是触发 change 事件，detail = {value:[选中的checkbox的value的数组]}

checkbox

多选项目。

属性说明

属性名	类型	默认值	说明
value	String		<checkbox> 附带的值，用于事件传值
disabled	Boolean	false	是否禁用
checked	Boolean	false	当前是否选中，可用来设置默认选中
color	Color		checkbox的颜色，同css的color

switch

开关选择器。

属性说明

属性名	类型	默认值	说明
checked	Boolean	false	是否选中
disabled	Boolean	false	是否禁用
type	String	switch	样式，有效值：switch, checkbox
@change	EventHandle		checked 改变时触发 change 事件
color	Color		switch 的颜色，同 css 的 color

slider

滑动选择器。

属性说明

属性名	类型	默认值	说明
min	Number	0	最小值
max	Number	100	最大值
step	Number	1	步长，取值必须大于 0，并且可被(max - min)整除
disabled	Boolean	false	是否禁用
value	Number	0	当前取值
activeColor	Color	各个平台不同，详见下	滑块左侧已选择部分的线条颜色
backgroundColor	Color	#e9e9e9	滑块右侧背景条的颜色
block-size	Number	28	滑块的大小，取值范围为 12 - 28
block-color	Color	#ffffff	滑块的颜色
show-value	Boolean	false	是否显示当前 value
@change	EventHandle		完成一次拖动后触发的事件
@changing	EventHandle		拖动过程中触发的事件

3. 进度条类

progress

进度条组件。

属性说明

属性名	类型	默认值	说明
percent	Float	无	百分比0~100
show-info	Boolean	false	在进度条右侧显示百分比
border-radius	number/string	0	圆角大小
font-size	number/string	16	右侧百分比字体大小
stroke-width	Number	6	进度条线的宽度
activeColor	Color	#09BB07	已选择的进度条的颜色
backgroundColor	Color	#EBEBEB	未选择的进度条的颜色
active	Boolean	false	进度条从左往右的动画
active-mode	String	backwards	backwards: 动画从头播；forwards：动画从上次结束点接着播
duration	number	30	进度增加1%所需毫秒数
@activeend	EventHandle		动画完成事件

4. 表单提交类

form

表单，将组件内的用户输入的<switch> <input> <checkbox> <slider> <radio> <picker> 提交。

当点击 <form> 表单中 formType 为 submit 的 <button> 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。

属性说明

属性名	类型	说明
report-submit	Boolean	是否返回 formId 用于发送模板消息
report-submit-timeout	number	等待一段时间（毫秒数）以确认 formId 是否生效。如果未指定这个参数，formId 有很小的概率是无效的（如遇到网络失败的情况）。指定这个参数将可以检测 formId 是否有效，以这个参数的时间作为这项检测的超时时间。如果失败，将返回 requestFormId:fail 开头的 formId
@submit	EventHandle	携带 form 中的数据触发 submit 事件，event.detail = {value : {‘name’: ‘value’} , formId: ‘’}，report-submit 为 true 时才会返回 formId
@reset	EventHandle	表单重置时会触发 reset 事件

input

输入框。

属性说明

属性名	类型	默认值	平台差异说明
value	String
type	String	text
password	Boolean	false
placeholder	String
placeholder-style	String
placeholder-class	String	“input-placeholder”
disabled	Boolean	false
maxlength	Number	140
focus	Boolean	false	在 H5 平台能否聚焦以及软键盘是否跟随弹出，取决于当前浏览器本身的实现。
confirm-type	String	done
@input	EventHandle		差异见下方 Tips
@focus	EventHandle		仅微信小程序、App（2.2.3+） 、QQ小程序支持 height
@blur	EventHandle
@confirm	EventHandle
@keyboardheightchange	eventhandle		微信小程序2.7.0

type 有效值

值	说明
text	文本输入键盘
number	数字输入键盘
idcard	身份证输入键盘
digit	带小数点的数字键盘

confirm-type 有效值

值	说明
send	右下角按钮为“发送”
search	右下角按钮为“搜索”
next	右下角按钮为“下一个”
go	右下角按钮为“前往”
done	右下角按钮为“完成”

• App平台的nvue页面，如果是uni-app编译模式，直接使用此属性设置即可生效。如果是weex编译模式，需通过weex的api设置
• App平台的vue页面不支持控制键盘右下角为“发送”，涉及聊天的建议使用nvue。

5. 视图类

view

视图容器。

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

如果使用nvue，则需注意，包裹文字应该使用组件。

属性说明

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

scroll-view

区域滚动容器。

注：在webview渲染的页面中，区域滚动的性能不及页面滚动。

属性说明

属性名	类型	默认值	说明
scroll-x	Boolean	false	允许横向滚动
scroll-y	Boolean	false	允许纵向滚动
upper-threshold	Number	50	距顶部/左边多远时（单位px），触发scrolltoupper事件
lower-threshold	Number	50	距底部/右边多远时（单位px），触发scrolltolower事件
@scrolltoupper	EventHandle		滚动到顶部/左边，会触发 scrolltoupper 事件
@scrolltolower	EventHandle		滚动到底部/右边，会触发 scrolltolower 事件
@scroll	EventHandle		滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}
scroll-top	Number		设置竖向滚动条位置
scroll-left	Number		设置横向滚动条位置
scroll-into-view	String		滚动到指定id 的元素（id不能以数字开头）。
show-scrollbar	Boolean	false	控制是否出现滚动条
refresher-enabled	Boolean	false	开启自定义下拉刷新
refresher-threshold	number	45	设置自定义下拉刷新阈值
refresher-default-style	string	“black”	设置自定义下拉刷新默认样式，支持设置 black、white、none，none 表示不使用默认样式
refresher-background	string	“#FFF”	设置自定义下拉刷新区域背景颜色
refresher-triggered	boolean	false	设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发
enable-flex	boolean	false	启用 flexbox 布局。开启后，当前节点声明了 display: flex 就会成为 flex container，并作用于其孩子节点。

注：

• 使用竖向滚动时，需要通过css的height 属性来给 <scroll-view> 设置一个固定高度。

• scroll-view 放长列表会有性能问题。长列表滚动和下拉刷新，应该使用原生导航栏搭配页面级的滚动和下拉刷新实现。包括在app-nvue页面，长列表应该使用list而不是scroll-view。
• scroll-into-view 的优先级高于 scroll-top。
• scroll-view是区域滚动，不会触发页面滚动，无法触发pages.json配置的下拉刷新（onPullDownRefresh）、页面触底（onReachBottomDistance）、titleNView的透明（transparent）属性。
• scroll-view的滚动条设置，可通过css的-webkit-scrollbar自定义，包括隐藏滚动条。（app-nvue没有该css样式）

swiper

滑块视图容器。

一般用于左右滑动或上下滑动，多用于轮播图。

注意滑动切换和滚动的区别，滑动切换是一屏一屏的切换。

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

<swiper>容器中只能放<swiper-item>组件，否则可能会导致未定义行为，<swiper-item>也只能放置在 <swiper> 容器中，宽高自动设置为100%。

注意：宽高100%是相对于其父组件，不是相对于子组件，不能被子组件自动撑开。

属性说明

属性名	类型	默认值	说明
indicator-dots	Boolean	false	是否显示面板指示点
indicator-color	Color	rgba(0, 0, 0, .3)	指示点颜色
indicator-active-color	Color	#000000	当前选中的指示点颜色
autoplay	Boolean	false	是否自动切换
current	Number	0	当前所在滑块的 index
circular	Boolean	false	是否采用衔接滑动，即播放到末尾后重新回到开头
vertical	Boolean	false	滑动方向是否为纵向
touchable	Boolean	true	是否监听用户的触摸事件，只在初始化时有效，不能动态变更
@change	EventHandle		current 改变时会触发 change 事件，event.detail = {current: current, source: source}

navigator

导航组件

属性说明

属性名	类型	默认值	说明
url	String		应用内的跳转链接，值为相对路径或绝对路径
open-type	String	navigate	跳转方式
delta	Number		当 open-type 为 ‘navigateBack’ 时有效，表示回退的层数
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

注意事项：

• label组件是基于表单组件的，用来改进表单组件的可用性，使用for属性找到对应的id，或者将控件放在该标签下，当点击时，就会触发对应的控件。目前可以绑定的控件有：<button>, <checkbox>, <radio>, <switch>。
• navigator组件的url 属性值 不能加 .vue 后缀。
• 开启竖向滚动时，需要通过css的height 属性来给 <scroll-view> 设置一个固定高度。
• 组件的使用有平台差异，要仔细查看官方文档来区分，不能使用指定平台属性时，可以自定义修改样式。