更新记录
2018.3.13:微信小程序组件说明表完成上线
  1. 首页
  2. 常用参考表对照表
  3. 微信小程序组件说明表

微信小程序组件说明表

这里搜集整理了微信小程序开发中各种常用组件的概念、功能、相关属性及使用方法，方便需要的朋友进行快速查询。提供给需要的朋友查询使用。

为了方便大家理解与查询微信小程序组件，这里整理了微信小程序的常用组件分类与功能描述。内容整理自官网。内容不断整理补充中。。。

官网原链接https://mp.weixin.qq.com/debug/wxadoc/dev/component/

基础组件

框架为开发者提供了一系列基础组件，开发者可以通过组合这些基础组件进行快速开发。

什么是组件：

  • 组件是视图层的基本组成单元。
  • 组件自带一些功能与微信风格的样式。
  • 一个组件通常包括开始标签和结束标签，属性用来修饰这个组件，内容在两个标签之内。
<tagname property="value">
  Content goes here ...
</tagename>

属性类型

类型 描述 注解
Boolean 布尔值 组件写上该属性，不管该属性等于什么，其值都为true，只有组件上没有写该属性时，属性值才为false。如果属性值为变量，变量的值会被转换为Boolean类型
Number 数字 1, 2.5
String 字符串 “string”
Array 数组 [ 1, “string” ]
Object 对象 { key: value }
EventHandler 事件处理函数名 “handlerName” 是 Page中定义的事件处理函数名
Any 任意属性
共同属性类型
属性 类型 描述 注解
id String 组件的唯一标示 保持整个页面唯一
class String 组件的样式类 在对应的 WXSS 中定义的样式类
style String 组件的内联样式 可以动态设置的内联样式
hidden String 组件是否显示 所有组件默认显示
data-* Any 自定义属性 组件上触发的事件时，会发送给事件处理函数
bind* / catch* EventHandler 组件的事件

基本组件列表

基础组件分为以下几类：

视图容器(View Container) 基础内容(Basic Content) 表单(Form) 导航(Navigation) 多媒体(Media) 地图(Map) 画布(Canvas)

视图容器(View Container)：

组件名 注释 组件属性
属性名 类型 默认值 说明 最低版本
view 视图容器 hover-class String none 指定按下去的样式类。当 hover-class="none" 时，没有点击态效果  
hover-stop-propagation Boolean false 指定是否阻止本节点的祖先节点出现点击态 1.5.0
hover-start-time Number 50 按住后多久出现点击态，单位毫秒  
hover-stay-time Number 400 手指松开后点击态保留时间，单位毫秒  
scroll-view 可滚动视图容器 scroll-x Boolean false 允许横向滚动  
scroll-y Boolean false 允许纵向滚动  
upper-threshold Number 50 距顶部/左边多远时（单位px），触发 scrolltoupper 事件  
lower-threshold Number 50 距底部/右边多远时（单位px），触发 scrolltolower 事件  
scroll-top Number   设置竖向滚动条位置  
scroll-left Number   设置横向滚动条位置  
scroll-into-view String   值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素  
scroll-with-animation Boolean false 在设置滚动条位置时使用动画过渡  
enable-back-to-top Boolean false iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向  
bindscrolltoupper EventHandle   滚动到顶部/左边，会触发 scrolltoupper 事件  
bindscrolltolower EventHandle   滚动到底部/右边，会触发 scrolltolower 事件  
bindscroll EventHandle   滚动时触发，event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY}  
swiper 滑块视图容器 indicator-dots Boolean false 是否显示面板指示点  
indicator-color Color rgba(0, 0, 0, .3) 指示点颜色 1.1.0
indicator-active-color Color #000000 当前选中的指示点颜色 1.1.0
autoplay Boolean false 是否自动切换  
current Number 0 当前所在页面的 index  
interval Number 5000 自动切换时间间隔  
duration Number 500 滑动动画时长  
circular Boolean false 是否采用衔接滑动  
vertical Boolean false 滑动方向是否为纵向  
bindchange EventHandle   current 改变时会触发 change 事件，event.detail = {current: current, source: source}  

基础内容(Basic Content)：

组件名 注释 组件属性
属性名 类型 默认值 说明 最低版本
icon 图标 type String   icon的类型，有效值：success, success_no_circle, info, warn, waiting, cancel, download, search, clear  
size Number 23 icon的大小，单位px  
color Color   icon的颜色，同css的color  
text 文字 selectable Boolean false 文本是否可选 1.1.0
space String false 显示连续空格
有效值 ensp:中文字符空格一半大小 emsp:中文字符空格大小 nbsp:根据字体设置的空格大小		 1.4.0
decode Boolean false 是否解码 1.4.0
progress 进度条 percent Float 无 百分比0~100  
show-info Boolean false 在进度条右侧显示百分比  
stroke-width Number 6 进度条线的宽度，单位px  
color Color #09BB07 进度条颜色 （请使用 activeColor）  
activeColor Color   已选择的进度条的颜色  
backgroundColor Color   未选择的进度条的颜色  
active Boolean false 进度条从左往右的动画  
active-mode String backwards backwards: 动画从头播；forwards：动画从上次结束点接着播 1.7.0

表单(Form)：

组件名 注释 组件属性
属性名 类型 默认值 说明 生效时机 最低版本
button 按钮 size String default 按钮的大小    
type String default 按钮的样式类型    
plain Boolean false 按钮是否镂空，背景色透明    
disabled Boolean false 是否禁用    
loading Boolean false 名称前是否带 loading 图标    
form-type String   用于 <form/> 组件，点击分别会触发 <form/> 组件的 submit/reset 事件    
open-type String   微信开放能力   1.1.0
hover-class String button-hover 指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果    
hover-stop-propagation Boolean false 指定是否阻止本节点的祖先节点出现点击态   1.5.0
hover-start-time Number 20 按住后多久出现点击态，单位毫秒    
hover-stay-time Number 70 手指松开后点击态保留时间，单位毫秒    
bindgetuserinfo Handler   用户点击该按钮时，会返回获取到的用户信息，从返回参数的detail中获取到的值同wx.getUserInfo open-type="getUserInfo' 1.3.0
lang String en 指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。 open-type="getUserInfo" 1.3.0
session-from String   会话来源 open-type="contact" 1.4.0
send-message-title String 当前标题 会话内消息卡片标题 open-type="contact" 1.5.0
send-message-path String 当前分享路径 会话内消息卡片点击跳转小程序路径 open-type="contact" 1.5.0
send-message-img String 截图 会话内消息卡片图片 open-type="contact" 1.5.0
show-message-card Boolean false 显示会话内消息卡片 open-type="contact" 1.5.0
bindcontact Handler   客服消息回调 open-type="contact" 1.5.0
bindgetphonenumber Handler   获取用户手机号回调 open-type="getphonenumber" 1.2.0
form 表单 report-submit Boolean   是否返回 formId 用于发送模板消息  
bindsubmit EventHandle   携带 form 中的数据触发 submit 事件，event.detail = {value : {'name': 'value'} , formId: ''}  
bindreset EventHandle   表单重置时会触发 reset 事件  
input 输入框 value String   输入框的初始内容  
type String "text" input 的类型  
password Boolean false 是否是密码类型  
placeholder String   输入框为空时占位符  
placeholder-style String   指定 placeholder 的样式  
placeholder-class String "input-placeholder" 指定 placeholder 的样式类  
disabled Boolean false 是否禁用  
maxlength Number 140 最大输入长度，设置为 -1 的时候不限制最大长度  
cursor-spacing Number 0 指定光标与键盘的距离，单位 px 。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离  
auto-focus Boolean false (即将废弃，请直接使用 focus )自动聚焦，拉起键盘  
focus Boolean false 获取焦点  
confirm-type String "done" 设置键盘右下角按钮的文字 1.1.0
confirm-hold Boolean false 点击键盘右下角按钮时是否保持键盘不收起 1.1.0
cursor Number   指定focus时的光标位置 1.5.0
bindinput EventHandle   当键盘输入时，触发input事件，event.detail = {value, cursor}，处理函数可以直接 return 一个字符串，将替换输入框的内容。  
bindfocus EventHandle   输入框聚焦时触发，event.detail = {value: value}  
bindblur EventHandle   输入框失去焦点时触发，event.detail = {value: value}  
bindconfirm EventHandle   点击完成按钮时触发，event.detail = {value: value}  
checkbox 多项选择器 value String   <checkbox/>标识，选中时触发<checkbox-group/>的 change 事件，并携带 <checkbox/> 的 value  
disabled Boolean false 是否禁用  
checked Boolean false 当前是否选中，可用来设置默认选中  
color Color   checkbox的颜色，同css的color  
radio 单项选择器 value String   <radio/> 标识。当该<radio/> 选中时，<radio-group/> 的 change 事件会携带<radio/>的value  
disabled Boolean false 是否禁用  
checked Boolean false 当前是否选中，可用来设置默认选中  
color Color   radio的颜色，同css的color  
picker
(mode = selector)		 (普通)列表选择器 range Array / Object Array [] mode为 selector 或 multiSelector 时，range 有效  
range-key String   当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容  
value Number 0 value 的值表示选择了 range 中的第几个（下标从 0 开始）  
bindchange EventHandle   value 改变时触发 change 事件，event.detail = {value: value}  
disabled Boolean false 是否禁用  
picker
(mode = multiSelector)		 (多列)列表选择器 range 二维Array / 二维Object Array [] mode为 selector 或 multiSelector 时，range 有效。二维数组，长度表示多少列，数组的每项表示每列的数据，如[["a","b"], ["c","d"]]  
range-key String   当 range 是一个 二维Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容  
value Array 0 value 每一项的值表示选择了 range 对应项中的第几个（下标从 0 开始）  
bindchange EventHandle   value 改变时触发 change 事件，event.detail = {value: value}  
bindcolumnchange EventHandle   某一列的值改变时触发 columnchange 事件，event.detail = {column: column, value: value}，column 的值表示改变了第几列（下标从0开始），value 的值表示变更值的下标  
disabled Boolean false 是否禁用  
picker
(mode = time)		 (时间)列表选择器 value String   表示选中的时间，格式为"hh:mm"  
start String   表示有效时间范围的开始，字符串格式为"hh:mm"  
end String   表示有效时间范围的结束，字符串格式为"hh:mm"  
bindchange EventHandle   value 改变时触发 change 事件，event.detail = {value: value}  
disabled Boolean false 是否禁用  
picker
(mode = date)		 (日期)列表选择器 value String 0 表示选中的日期，格式为"YYYY-MM-DD"  
start String   表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"  
end String   表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"  
fields String day 有效值 year,month,day，表示选择器的粒度  
bindchange EventHandle   value 改变时触发 change 事件，event.detail = {value: value}  
disabled Boolean false 是否禁用  
picker
(mode = region)		 (日期)列表选择器 value Array [] 表示选中的省市区，默认选中每一列的第一个值  
custom-item String   可为每一列的顶部添加一个自定义的项 1.5.0
bindchange EventHandle   value 改变时触发 change 事件，event.detail = {value: value}  
disabled Boolean false 是否禁用  
picker-view 内嵌列表选择器 value NumberArray   数组中的数字依次表示 picker-view 内的 picker-view-colume 选择的第几项（下标从 0 开始），数字大于 picker-view-column 可选项长度时，选择最后一项。  
indicator-style String   设置选择器中间选中框的样式  
indicator-class String   设置选择器中间选中框的类名 1.1.0
mask-style String   设置蒙层的样式 1.5.0
mask-class String   设置蒙层的类名 1.5.0
bindchange EventHandle   当滚动选择，value 改变时触发 change 事件，event.detail = {value: value}；value为数组，表示 picker-view 内的 picker-view-column 当前选择的是第几项（下标从 0 开始）  
slider 滚动选择器 min Number 0 最小值  
max Number 100 最大值  
step Number 0 步长，取值必须大于 0，并且可被(max - min)整除  
disabled Boolean false 是否禁用  
value Number 0 当前取值  
color Color #e9e9e9 背景条的颜色（请使用 backgroundColor）  
selected-color Color #1aad19 已选择的颜色（请使用 activeColor）  
activeColor Color #1aad19 已选择的颜色  
backgroundColor Color #e9e9e9 背景条的颜色  
show-value Boolean false 是否显示当前 value  
bindchange EventHandle   完成一次拖动后触发的事件，event.detail = {value: value}  
bindchanging EventHandle   拖动过程中触发的事件，event.detail = {value: value} 1.7.0
switch 开关选择器 checked Boolean false 是否选中  
type String switch 样式，有效值：switch, checkbox  
bindchange EventHandle   checked 改变时触发 change 事件，event.detail={ value:checked}  
color Color   switch 的颜色，同 css 的 color  
label 标签 for String   绑定控件的 id  

导航(Navigation)：

组件名 注释 组件属性
属性名 类型 默认值 说明 最低版本
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 指定是否阻止本节点的祖先节点出现点击态 1.5.0
hover-start-time Number 50 按住后多久出现点击态，单位毫秒  
hover-stay-time Number 600 手指松开后点击态保留时间，单位毫秒  
其中open-type 的有效值如下：
值说明最低版本
navigate对应 wx.navigateTo 的功能 
redirect对应 wx.redirectTo 的功能 
switchTab对应 wx.switchTab 的功能 
reLaunch对应 wx.reLaunch 的功能1.1.0
navigateBack对应 wx.navigateBack 的功能1.1.0

多媒体(Media)：

组件名 注释 组件属性
属性名 类型 默认值 说明 最低版本
audio 音频 id String   audio 组件的唯一标识符  
src String   要播放音频的资源地址  
loop Boolean false 是否循环播放  
controls Boolean false 是否显示默认控件  
poster String   默认控件上的音频封面的图片资源地址，如果 controls 属性值为 false 则设置 poster 无效  
name String 未知音频 默认控件上的音频名字，如果 controls 属性值为 false 则设置 name 无效  
author String 未知作者 默认控件上的作者名字，如果 controls 属性值为 false 则设置 author 无效  
binderror EventHandle   当发生错误时触发 error 事件，detail = {errMsg: MediaError.code}  
bindplay EventHandle   当开始/继续播放时触发play事件  
bindpause EventHandle   当暂停播放时触发 pause 事件  
bindtimeupdate EventHandle   当播放进度改变时触发 timeupdate 事件，detail = {currentTime, duration}  
bindended EventHandle   当播放到末尾时触发 ended 事件  
image 图片 src String   图片资源地址  
mode String 'scaleToFill' 图片裁剪、缩放的模式  
lazy-load Boolean false 图片懒加载。只针对page与scroll-view下的image有效 1.5.0
binderror HandleEvent   当错误发生时，发布到 AppService 的事件名，事件对象event.detail = {errMsg: 'something wrong'}  
bindload HandleEvent   当图片载入完毕时，发布到 AppService 的事件名，事件对象event.detail = {height:'图片高度px', width:'图片宽度px'}  
video 视频 src String   要播放视频的资源地址  
initial-time Number   指定视频初始播放位置 1.6.0
duration Number   指定视频时长 1.1.0
controls Boolean true 是否显示默认播放控件（播放/暂停按钮、播放进度、时间）  
danmu-list Object Array   弹幕列表  
danmu-btn Boolean false 是否显示弹幕按钮，只在初始化时有效，不能动态变更  
enable-danmu Boolean false 是否展示弹幕，只在初始化时有效，不能动态变更  
autoplay Boolean false 是否自动播放  
loop Boolean false 是否循环播放 1.4.0
muted Boolean false 是否静音播放 1.4.0
page-gesture Boolean false 在非全屏模式下，是否开启亮度与音量调节手势 1.6.0
direction Number   设置全屏时视频的方向，不指定则根据宽高比自动判断。有效值为 0（正常竖向）, 90（屏幕逆时针90度）, -90（屏幕顺时针90度） 1.7.0
bindplay EventHandle   当开始/继续播放时触发play事件  
bindpause EventHandle   当暂停播放时触发 pause 事件  
bindended EventHandle   当播放到末尾时触发 ended 事件  
bindtimeupdate EventHandle   播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次  
bindfullscreenchange EventHandle   当视频进入和退出全屏是触发，event.detail = {fullScreen, direction}，direction取为 vertical 或 horizontal 1.4.0
objectFit String contain 当视频大小与 video 容器大小不一致时，视频的表现形式。contain：包含，fill：填充，cover：覆盖  
poster String   视频封面的图片网络资源地址，如果 controls 属性值为 false 则设置 poster 无效  

地图(Map)：

组件名 注释 组件属性
属性名 类型 默认值 说明 最低版本
map 地图 longitude Number   中心经度  
latitude Number   中心纬度  
scale Number 16 缩放级别，取值范围为5-18  
markers Array   标记点  
covers Array   即将移除，请使用 markers  
polyline Array   路线  
circles Array   圆  
controls Array   控件  
include-points Array   缩放视野以包含所有给定的坐标点  
show-location Boolean   显示带有方向的当前定位点  
bindmarkertap EventHandle   点击标记点时触发  
bindcallouttap EventHandle   点击标记点对应的气泡时触发 1.2.0
bindcontroltap EventHandle   点击控件时触发  
bindregionchange EventHandle   视野发生变化时触发  
bindtap EventHandle   点击地图时触发  
bindupdated EventHandle   在地图渲染更新完成时触发 1.6.0

画布(Canvas)：

组件名 注释 组件属性
属性名 类型 默认值 说明 最低版本
canvas 画布 src String   要播放视频的资源地址  
initial-time Number   指定视频初始播放位置 1.6.0
duration Number   指定视频时长 1.1.0
controls Boolean true 是否显示默认播放控件（播放/暂停按钮、播放进度、时间）  
danmu-list Object Array   弹幕列表  
danmu-btn Boolean false 是否显示弹幕按钮，只在初始化时有效，不能动态变更  
enable-danmu Boolean false 是否展示弹幕，只在初始化时有效，不能动态变更  
autoplay Boolean false 是否自动播放  
loop Boolean false 是否循环播放 1.4.0
muted Boolean false 是否静音播放 1.4.0
page-gesture Boolean false 在非全屏模式下，是否开启亮度与音量调节手势 1.6.0
direction Number   设置全屏时视频的方向，不指定则根据宽高比自动判断。有效值为 0（正常竖向）, 90（屏幕逆时针90度）, -90（屏幕顺时针90度） 1.7.0
show-progress Boolean true 若不设置，宽度大于240时才会显示 1.9.0
show-fullscreen-btn Boolean true 是否显示全屏按钮 1.9.0
show-play-btn Boolean true 是否显示视频底部控制栏的播放按钮 1.9.0
show-center-play-btn Boolean true 是否显示视频中间的播放按钮 1.9.0
enable-progress-gesture Boolean true 是否开启控制进度的手势 1.9.0
bindplay EventHandle   当开始/继续播放时触发play事件  
bindpause EventHandle   当暂停播放时触发 pause 事件  
bindended EventHandle   当播放到末尾时触发 ended 事件  
bindtimeupdate EventHandle   播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次  
bindfullscreenchange EventHandle   当视频进入和退出全屏是触发，event.detail = {fullScreen, direction}，direction取为 vertical 或 horizontal 1.4.0
objectFit String contain 当视频大小与 video 容器大小不一致时，视频的表现形式。contain：包含，fill：填充，cover：覆盖  
poster String   视频封面的图片网络资源地址，如果 controls 属性值为 false 则设置 poster 无效