常用组件
view
基础库 1.0.0 开始支持,低版本需做兼容处理 。
属性 类型 默认值 必填 说明 最低版本 hover-class string none 否 指定按下去的样式类。当 hover-class="none"
时,没有点击态效果 1.0.0 hover-stop-propagation boolean false 否 指定是否阻止本节点的祖先节点出现点击态 1.5.0 hover-start-time number 50 否 按住后多久出现点击态,单位毫秒 1.0.0 hover-stay-time number 400 否 手指松开后点击态保留时间,单位毫秒 1.0.0
Bug & Tip
tip
: 如果需要使用滚动视图,请使用 scroll-view
text
基础库 1.0.0 开始支持,低版本需做兼容处理 。
属性 类型 默认值 必填 说明 最低版本 selectable boolean false 否 文本是否可选 (已废弃) 1.1.0 user-select boolean false 否 文本是否可选,该属性会使文本节点显示为 inline-block 2.12.1 space string 否 显示连续空格 1.4.0 decode boolean false 否 是否解码 1.4.0
space 的合法值
值 说明 最低版本 ensp 中文字符空格一半大小 emsp 中文字符空格大小 nbsp 根据字体设置的空格大小
Bug & Tip
tip
: decode可以解析的有
、<
、>
、&
、'
、 
、 
tip
: 各个操作系统的空格标准并不一致。tip
:text 组件内只支持 text 嵌套。tip
: 除了文本节点以外的其他节点都无法长按选中。bug
: 基础库版本低于 2.1.0
时, text 组件内嵌的 text style 设置可能不会生效。
image
图片 。支持 JPG、PNG、SVG、WEBP、GIF 等格式,2.3.0 起支持云文件ID。
属性 类型 默认值 必填 说明 最低版本 src string 否 图片资源地址 1.0.0 mode string scaleToFill 否 图片裁剪、缩放的模式 1.0.0 webp boolean false 否 默认不解析 webP 格式,只支持网络资源 2.9.0 lazy-load boolean false 否 图片懒加载,在即将进入一定范围(上下三屏)时才开始加载 1.5.0 show-menu-by-longpress boolean false 否 开启长按图片显示识别小程序码菜单 2.7.0 binderror eventhandle 否 当错误发生时触发,event.detail = {errMsg} 1.0.0 bindload eventhandle 否 当图片载入完毕时触发,event.detail = {height, width} 1.0.0
mode 的合法值
值 说明 最低版本 scaleToFill 缩放模式,不保持纵横比缩放图片,使图片的宽高完全拉伸至填满 image 元素 aspectFit 缩放模式,保持纵横比缩放图片,使图片的长边能完全显示出来。也就是说,可以完整地将图片显示出来。 aspectFill 缩放模式,保持纵横比缩放图片,只保证图片的短边能完全显示出来。也就是说,图片通常只在水平或垂直方向是完整的,另一个方向将会发生截取。 widthFix 缩放模式,宽度不变,高度自动变化,保持原图宽高比不变 heightFix 缩放模式,高度不变,宽度自动变化,保持原图宽高比不变 2.10.3 top 裁剪模式,不缩放图片,只显示图片的顶部区域 bottom 裁剪模式,不缩放图片,只显示图片的底部区域 center 裁剪模式,不缩放图片,只显示图片的中间区域 left 裁剪模式,不缩放图片,只显示图片的左边区域 right 裁剪模式,不缩放图片,只显示图片的右边区域 top left 裁剪模式,不缩放图片,只显示图片的左上边区域 top right 裁剪模式,不缩放图片,只显示图片的右上边区域 bottom left 裁剪模式,不缩放图片,只显示图片的左下边区域 bottom right 裁剪模式,不缩放图片,只显示图片的右下边区域
Bug & Tip
tip
:image组件默认宽度320px、高度240pxtip
:image组件中二维码/小程序码图片不支持长按识别 。仅在wx.previewImage中支持长按识别
swiper与swiper-item
swiper
基础库 1.0.0 开始支持,低版本需做兼容处理 。
属性 类型 默认值 必填 说明 最低版本 indicator-dots boolean false 否 是否显示面板指示点 1.0.0 indicator-color color rgba(0, 0, 0, .3) 否 指示点颜色 1.1.0 indicator-active-color color #000000 否 当前选中的指示点颜色 1.1.0 autoplay boolean false 否 是否自动切换 1.0.0 current number 0 否 当前所在滑块的 index 1.0.0 interval number 5000 否 自动切换时间间隔 1.0.0 duration number 500 否 滑动动画时长 1.0.0 circular boolean false 否 是否采用衔接滑动 1.0.0 vertical boolean false 否 滑动方向是否为纵向 1.0.0 previous-margin string “0px” 否 前边距,可用于露出前一项的一小部分,接受 px 和 rpx 值 1.9.0 next-margin string “0px” 否 后边距,可用于露出后一项的一小部分,接受 px 和 rpx 值 1.9.0 snap-to-edge boolean “false” 否 当 swiper-item 的个数大于等于 2,关闭 circular 并且开启 previous-margin 或 next-margin 的时候,可以指定这个边距是否应用到第一个、最后一个元素 2.12.1 display-multiple-items number 1 否 同时显示的滑块数量 1.9.0 easing-function string “default” 否 指定 swiper 切换缓动动画类型 2.6.5 bindchange eventhandle 否 current 改变时会触发 change 事件,event.detail = {current, source} 1.0.0 bindtransition eventhandle 否 swiper-item 的位置发生改变时会触发 transition 事件,event.detail = {dx: dx, dy: dy} 2.4.3 bindanimationfinish eventhandle 否 动画结束时会触发 animationfinish 事件,event.detail 同上 1.9.0
easing-function 的合法值
值 说明 最低版本 default 默认缓动函数 linear 线性动画 easeInCubic 缓入动画 easeOutCubic 缓出动画 easeInOutCubic 缓入缓出动画
change事件 source 返回值
从 1.4.0 开始,change
事件增加 source
字段,表示导致变更的原因,可能值如下:
autoplay
自动播放导致swiper变化;touch
用户划动引起swiper变化;其它原因将用空字符串表示。
Bug & Tip
tip
: 如果在 bindchange
的事件回调函数中使用 setData
改变 current
值,则有可能导致 setData
被不停地调用,因而通常情况下请在改变 current
值前检测 source
字段来判断是否是由于用户触摸引起。
swiper-item
基础库 1.0.0 开始支持,低版本需做兼容处理 。
属性 类型 默认值 必填 说明 最低版本 item-id string 否 该 swiper-item 的标识符 1.9.0 skip-hidden-item-layout boolean false 否 是否跳过未显示的滑块布局,设为 true 可优化复杂情况下的滑动性能,但会丢失隐藏状态滑块的布局信息 1.9.0
navigator
基础库 1.0.0 开始支持,低版本需做兼容处理 。
在小程序插件中使用需要基础库版本 2.1.0 起。
属性 类型 默认值 必填 说明 最低版本 target string self 否 在哪个目标上发生跳转,默认当前小程序 2.0.7 url string 否 当前小程序内的跳转链接 1.0.0 open-type string navigate 否 跳转方式 1.0.0 delta number 1 否 当 open-type 为 ‘navigateBack’ 时有效,表示回退的层数 1.0.0 app-id string 否 当target="miniProgram"
时有效,要打开的小程序 appId 2.0.7 path string 否 当target="miniProgram"
时有效,打开的页面路径,如果为空则打开首页 2.0.7 extra-data object 否 当target="miniProgram"
时有效,需要传递给目标小程序的数据,目标小程序可在 App.onLaunch()
,App.onShow()
中获取到这份数据。详情 2.0.7 version string release 否 当target="miniProgram"
时有效,要打开的小程序版本 2.0.7 hover-class string navigator-hover 否 指定点击时的样式类,当hover-class="none"
时,没有点击态效果 1.0.0 hover-stop-propagation boolean false 否 指定是否阻止本节点的祖先节点出现点击态 1.5.0 hover-start-time number 50 否 按住后多久出现点击态,单位毫秒 1.0.0 hover-stay-time number 600 否 手指松开后点击态保留时间,单位毫秒 1.0.0 bindsuccess string 否 当target="miniProgram"
时有效,跳转小程序成功 2.0.7 bindfail string 否 当target="miniProgram"
时有效,跳转小程序失败 2.0.7 bindcomplete string 否 当target="miniProgram"
时有效,跳转小程序完成 2.0.7
target 的合法值
值 说明 最低版本 self 当前小程序 miniProgram 其它小程序
open-type 的合法值
version 的合法值
值 说明 最低版本 develop 开发版 trial 体验版 release 正式版,仅在当前小程序为开发版或体验版时此参数有效;如果当前小程序是正式版,则打开的小程序必定是正式版。
使用限制
需要用户确认跳转 从 2.3.0
版本开始,在跳转至其他小程序前,将统一增加弹窗,询问是否跳转,用户确认后才可以跳转其他小程序。如果用户点击取消,则回调 fail cancel
。 每个小程序可跳转的其他小程序数量限制为不超过 10 个 从 2.4.0 版本以及指定日期(具体待定)开始,开发者提交新版小程序代码时,如使用了跳转其他小程序功能,则需要在代码配置中声明将要跳转的小程序名单,限定不超过 10 个,否则将无法通过审核。该名单可在发布新版时更新,不支持动态修改。配置方法详见 配置 。调用此接口时,所跳转的 appId 必须在配置列表中,否则回调 fail appId "${appId}" is not in navigateToMiniProgramAppIdList
。
关于调试
在开发者工具上调用此 API 并不会真实的跳转到另外的小程序,但是开发者工具会校验本次调用跳转是否成功。详情 开发者工具上支持被跳转的小程序处理接收参数的调试。详情
Bug & Tip
tip
:navigator-hover
默认为 {background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}
, navigator 的子节点背景色应为透明色
rich-text
基础库 1.4.0 开始支持,低版本需做兼容处理 。
属性 类型 默认值 必填 说明 最低版本 nodes array/string [] 否 节点列表/HTML String 1.4.0 space string 否 显示连续空格 2.4.1
space 的合法值
值 说明 最低版本 ensp 中文字符空格一半大小 emsp 中文字符空格大小 nbsp 根据字体设置的空格大小
nodes
现支持两种节点,通过type来区分,分别是元素节点和文本节点,默认是元素节点,在富文本区域里显示的HTML节点 元素节点:type = node
属性 说明 类型 必填 备注 name 标签名 string 是 支持部分受信任的 HTML 节点 attrs 属性 object 否 支持部分受信任的属性,遵循 Pascal 命名法 children 子节点列表 array 否 结构和 nodes 一致
文本节点:type = text
属性 说明 类型 必填 备注 text 文本 string 是 支持entities
受信任的HTML节点及属性
全局支持class和style属性,不支持id属性 。
节点 属性 a abbr address article aside b bdi bdo dir big blockquote br caption center cite code col span,width colgroup span,width dd del div dl dt em fieldset font footer h1 h2 h3 h4 h5 h6 header hr i img alt,src,height,width ins label legend li mark nav ol start,type p pre q rt ruby s section small span strong sub sup table width tbody td colspan,height,rowspan,width tfoot th colspan,height,rowspan,width thead tr colspan,height,rowspan,width tt u ul
Bug & Tip
tip
: nodes 不推荐使用 String 类型,性能会有所下降。tip
: rich-text
组件内屏蔽所有节点的事件。tip
: attrs 属性不支持 id ,支持 class 。tip
: name 属性大小写不敏感。tip
: 如果使用了不受信任的HTML节点,该节点及其所有子节点将会被移除。tip
: img 标签仅支持网络图片。tip
: 如果在自定义组件中使用 rich-text
组件,那么仅自定义组件的 wxss 样式对 rich-text
中的 class 生效。
button
基础库 1.0.0 开始支持,低版本需做兼容处理 。
样式
属性 类型 默认值 必填 说明 最低版本 size string default 否 按钮的大小 1.0.0 type string default 否 按钮的样式类型 1.0.0 plain boolean false 否 按钮是否镂空,背景色透明 1.0.0 disabled boolean false 否 是否禁用 1.0.0 loading boolean false 否 名称前是否带 loading 图标 1.0.0 form-type string 否 用于 form 组件,点击分别会触发 form 组件的 submit/reset 事件 1.0.0 open-type string 否 微信开放能力 1.1.0 hover-class string button-hover 否 指定按钮按下去的样式类。当 hover-class="none"
时,没有点击态效果 1.0.0 hover-stop-propagation boolean false 否 指定是否阻止本节点的祖先节点出现点击态 1.5.0 hover-start-time number 20 否 按住后多久出现点击态,单位毫秒 1.0.0 hover-stay-time number 70 否 手指松开后点击态保留时间,单位毫秒 1.0.0 lang string en 否 指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文。 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 app-parameter string 否 打开 APP 时,向 APP 传递的参数,open-type=launchApp时有效 1.9.5 show-message-card boolean false 否 是否显示会话内消息卡片,设置此参数为 true,用户进入客服会话会在右下角显示"可能要发送的小程序"提示,用户点击后可以快速发送小程序消息,open-type="contact"时有效 1.5.0 bindgetuserinfo eventhandle 否 用户点击该按钮时,会返回获取到的用户信息,回调的detail数据与wx.getUserInfo 返回的一致,open-type="getUserInfo"时有效 1.3.0 bindcontact eventhandle 否 客服消息回调,open-type="contact"时有效 1.5.0 bindgetphonenumber eventhandle 否 获取用户手机号回调,open-type=getPhoneNumber时有效 1.2.0 binderror eventhandle 否 当使用开放能力时,发生错误的回调,open-type=launchApp时有效 1.9.5 bindopensetting eventhandle 否 在打开授权设置页后回调,open-type=openSetting时有效 2.0.7 bindlaunchapp eventhandle 否 打开 APP 成功的回调,open-type=launchApp时有效 2.4.4
size 的合法值
值 说明 最低版本 default 默认大小 mini 小尺寸
type 的合法值
值 说明 最低版本 primary 绿色 default 白色 warn 红色
form-type 的合法值
值 说明 最低版本 submit 提交表单 reset 重置表单
开发能力
值 说明 最低版本 contact 打开客服会话,如果用户在会话中点击消息卡片后返回小程序,可以从 bindcontact 回调中获得具体信息,具体说明 (小程序插件中不能使用 ) 1.1.0 share 触发用户转发,使用前建议先阅读使用指引 1.2.0 getPhoneNumber 获取用户手机号,可以从bindgetphonenumber回调中获取到用户信息,具体说明 (小程序插件中不能使用 ) 1.2.0 getUserInfo 获取用户信息,可以从bindgetuserinfo回调中获取到用户信息 (小程序插件中不能使用 ) 1.3.0 launchApp 打开APP,可以通过app-parameter属性设定向APP传的参数具体说明 1.9.5 openSetting 打开授权设置页 2.0.7 feedback 打开“意见反馈”页面,用户可提交反馈内容并上传日志 ,开发者可以登录小程序管理后台 后进入左侧菜单“客服反馈”页面获取到反馈内容 2.1.0
lang 的合法值
值 说明 最低版本 en 英文 zh_CN 简体中文 zh_TW 繁体中文
Bug & Tip
tip
: button-hover
默认为{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}
tip
: bindgetphonenumber
从1.2.0 开始支持,但是在1.5.3以下版本中无法使用wx.canIUse 进行检测,建议使用基础库版本进行判断。tip
: 在bindgetphonenumber
等返回加密信息的回调中调用 wx.login 登录,可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey,导致解密失败。建议开发者提前进行 login
;或者在回调中先使用 checkSession
进行登录态检查,避免 login
刷新登录态。tip
: 从 2.1.0 起,button 可作为原生组件的子节点嵌入,以便在原生组件上使用 open-type
的能力。tip
: 目前设置了 form-type
的 button
只会对当前组件中的 form
有效。因而,将 button
封装在自定义组件中,而 form
在自定义组件外,将会使这个 button
的 form-type
失效。
icon
基础库 1.0.0 开始支持,低版本需做兼容处理 。
图标 。组件属性的长度单位默认为px,2.4.0 起支持传入单位(rpx/px)。
属性 类型 默认值 必填 说明 最低版本 type string 是 icon的类型,有效值:success, success_no_circle, info, warn, waiting, cancel, download, search, clear 1.0.0 size number/string 23 否 icon的大小 1.0.0 color string 否 icon的颜色,同css的color 1.0.0
radio与radio-group
radio
基础库 1.0.0 开始支持,低版本需做兼容处理 。
radio-group
基础库 1.0.0 开始支持,低版本需做兼容处理 。
属性 类型 默认值 必填 说明 最低版本 bindchange EventHandle 否 radio-group 中选中项发生改变时触发 change 事件,detail = {value:[选中的radio的value的数组]}1.0.0
checkbox与checkbox-group
checkbox
基础库 1.0.0 开始支持,低版本需做兼容处理 。
checkbox-group
基础库 1.0.0 开始支持,低版本需做兼容处理 。
属性 类型 默认值 必填 说明 最低版本 bindchange EventHandle 否 checkbox-group 中选中项发生改变时触发 change 事件,detail = {value:[选中的checkbox的value的数组]}1.0.0
官网链接