微信小程序学习 常用组件

微信小程序的组件用于WXML模板文件，将小程序页面划分成多个部分，每个组件内可以嵌套其他组件。

所有组件名和属性都是小写，多个单词会以英文横杠 "-" 进行连接，实例如下：

<!-- page.wxml -->
<image mode="scaleToFill" src="img.png"></image>

一、所有组件共有属性

所有组件拥有通用属性，如表1.1所示，主要设计组件标识、样式、触发时间等。

表1.1 常见属性

属性名	类型	描述	其他说明
id	String	组件的唯一标示	保持整个页面唯一
class	String	组件的样式类	在对应的WXSS中定义的样式类
style	String	组件的内联样式	可以通过数据绑定进行动态设置的内联样式
hidden	Boolean	组件是否显示	所有组件默认显示
data-*	Any	自定义属性	组件上触发的事件时，会发送给事件处理函数
bind / catch	EventHandler	事件	详情见表1.2

表1.2 常见的事件类型

类型	触发条件
touchstart	手指触摸动作开始
touchmove	手指触摸后移动
touchcancel	手指触摸动作被打断，如来电提醒，弹窗
touchend	手指触摸动作结束
tap	手指触摸后马上离开
longpress	手指触摸后，超过350ms再离开，如果指定了事件回调函数并触发了这个事件，tap事件将不被触发
longtap	手指触摸后，超过350ms再离开（推荐使用longpress事件代替）
transitionend	会在 WXSS transition 或 wx.createAnimation 动画结束后触发
animationstart	会在一个 WXSS animation 动画开始时触发
animationiteration	会在一个 WXSS animation 一次迭代结束时触发
animationend	会在一个 WXSS animation 动画完成时触发

二、常用组件说明

2.1 view

view组件主要功能为视图容器，是一个固定视图（如果需要滚动视图，则需要使用scroll-view

），小程序的页面布局常用组件，划分页面各个区域，进行简单渲染，属性如下：

属性	类型	默认值	必填	说明	最低版本
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

代码示例

<view class="flex-wrp" style="flex-direction:column;">    </view>

2.2 text

text组件用来显示文本，是一个文本组件，属性如下：

通用属性

属性	类型	默认值	必填	说明	最低版本
user-select	boolean	false	否	文本是否可选，该属性会使文本节点显示为 inline-block	2.12.1

skyline特有属性

属性	类型	默认值	必填	说明
overflow	string	visible	是	文本溢出处理
合法值 说明 clip 修剪文本 fade 淡出 ellipsis 显示省略号 visible 文本不截断
max-lines	number		是	限制文本最大行数

webview特有属性

属性	类型	默认值	必填	说明	最低版本
space	string		否	显示连续空格	1.4.0
合法值 说明 ensp 中文字符空格一半大小 emsp 中文字符空格大小 nbsp 根据字体设置的空格大小
decode	boolean	false	否	是否解码	1.4.0

代码示例

显示变量
<text class="text1">{{text}}</text>
直接显示文字
<text class="text2">测试使用</text>

2.3 image

image组件用于图片显示，支持 JPG、PNG、SVG、WEBP、GIF 等格式，其中svg格式不支持百分比单位，不支持 <style> element，如果 mode=scaleToFill 时，WebView 会居中（除非 svg 里加上 preserveAspectRatio="none"），Skyline 则会撑满。

通用属性

	属性	类型	默认值	必填	说明	最低版本
	src	string		否	图片资源地址	1.0.0
	mode	string	scaleToFill	否	图片裁剪、缩放的模式	1.0.0
	合法值 说明 最低版本 scaleToFill 缩放模式，不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素 aspectFit 缩放模式，保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。 aspectFill 缩放模式，保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。 widthFix 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变 heightFix 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变 2.10.3 top 裁剪模式，不缩放图片，只显示图片的顶部区域。仅 Webview 支持。 bottom 裁剪模式，不缩放图片，只显示图片的底部区域。仅 Webview 支持。 center 裁剪模式，不缩放图片，只显示图片的中间区域。仅 Webview 支持。 left 裁剪模式，不缩放图片，只显示图片的左边区域。仅 Webview 支持。 right 裁剪模式，不缩放图片，只显示图片的右边区域。仅 Webview 支持。 top left 裁剪模式，不缩放图片，只显示图片的左上边区域。仅 Webview 支持。 top right 裁剪模式，不缩放图片，只显示图片的右上边区域。仅 Webview 支持。 bottom left 裁剪模式，不缩放图片，只显示图片的左下边区域。仅 Webview 支持。 bottom right 裁剪模式，不缩放图片，只显示图片的右下边区域。仅 Webview 支持。
	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

Skyline 特有属性

	属性	类型	默认值	必填	说明
	fade-in	boolean	false	否	是否渐显

WebView 特有属性

	属性	类型	默认值	必填	说明	最低版本
	webp	boolean	false	否	默认不解析 webP 格式，只支持网络资源	2.9.0
	lazy-load	boolean	false	否	图片懒加载，在即将进入一定范围（上下三屏）时才开始加载。Skyline 默认懒加载。	1.5.0

支持长按识别的码

类型	说明	最低版本
小程序码
微信个人码		2.18.0
企业微信个人码		2.18.0
普通群码	指仅包含微信用户的群	2.18.0
互通群码	指既有微信用户也有企业微信用户的群	2.18.0
公众号二维码		2.18.0

注意：image组件默认宽度320px，高度240px。

代码示例：

 <image style="width: 200px; height: 200px; background-color: #eeeeee;" src="https://res.wx.qq.com/wxdoc/dist/assets/img/0.4cb08bb4.jpg"></image>

2.4 button

按钮组件，可以通过wxss中改写按钮样式

通用属性

属性	类型	默认值	必填	说明	最低版本
size	string	default	否	按钮的大小	1.0.0
合法值 说明 default 默认大小 mini 小尺寸
type	string	default	否	按钮的样式类型	1.0.0
合法值 说明 primary 绿色 default 白色 warn 红色
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
合法值 说明 submit 提交表单 reset 重置表单
open-type	string		否	微信开放能力	1.1.0
合法值 说明 最低版本 contact 打开客服会话，如果用户在会话中点击消息卡片后返回小程序，可以从 bindcontact 回调中获得具体信息，具体说明 1.1.0 liveActivity 通过前端获取新的一次性订阅消息下发机制使用的 code 2.26.2 share 触发用户转发，使用前建议先阅读使用指引 1.2.0 getPhoneNumber 手机号快速验证，向用户申请，并在用户同意后，快速填写和验证手机，具体说明 （*小程序插件中不能使用*） 1.2.0 getRealtimePhoneNumber 手机号实时验证，向用户申请，并在用户同意后，快速填写和实时验证手机号。具体说明 （*小程序插件中不能使用*） 2.24.4 getUserInfo 获取用户信息，可以从bindgetuserinfo回调中获取到用户信息 （*小程序插件中不能使用*） 1.3.0 launchApp 打开APP，可以通过app-parameter属性设定向APP传的参数具体说明 1.9.5 openSetting 打开授权设置页 2.0.7 feedback 打开“意见反馈”页面，用户可提交反馈内容并上传日志，开发者可以登录小程序管理后台后进入左侧菜单“客服反馈”页面获取到反馈内容 2.1.0 chooseAvatar 获取用户头像，可以从bindchooseavatar回调中获取到头像信息 2.21.2 agreePrivacyAuthorization 用户同意隐私协议按钮。用户点击一次此按钮后，所有已声明过的隐私接口可以正常调用。可通过 bindagreeprivacyauthorization 监听用户同意隐私协议事件。隐私合规开发指南详情可见《小程序隐私协议开发指南》 2.32.3
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
合法值 说明 en 英文 zh_CN 简体中文 zh_TW 繁体中文
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
phone-number-no-quota-toast	boolean	true	否	当手机号快速验证或手机号实时验证额度用尽时，是否对用户展示“申请获取你的手机号，但该功能使用次数已达当前小程序上限，暂时无法使用”的提示，默认展示，open-type="getPhoneNumber" 或 open-type="getRealtimePhoneNumber" 时有效	3.0.1
bindgetuserinfo	eventhandle		否	用户点击该按钮时，会返回获取到的用户信息，回调的detail数据与wx.getUserInfo返回的一致，open-type="getUserInfo"时有效	1.3.0
bindcontact	eventhandle		否	客服消息回调，open-type="contact"时有效。	1.5.0
createliveactivity	eventhandle		否	新的一次性订阅消息下发机制回调，open-type=liveActivity时有效	2.26.2
bindgetphonenumber	eventhandle		否	手机号快速验证回调，open-type=getPhoneNumber时有效。Tips：在触发 bindgetphonenumber 回调后应立即隐藏手机号按钮组件，或置为 disabled 状态，避免用户重复授权手机号产生额外费用。	1.2.0
bindgetrealtimephonenumber	eventhandle		否	手机号实时验证回调，open-type=getRealtimePhoneNumber 时有效。Tips：在触发 bindgetrealtimephonenumber 回调后应立即隐藏手机号按钮组件，或置为 disabled 状态，避免用户重复授权手机号产生额外费用。	2.24.4
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
bindchooseavatar	eventhandle		否	获取用户头像回调，open-type=chooseAvatar时有效	2.21.2
bindagreeprivacyauthorization	eventhandle		否	用户同意隐私协议事件回调，open-type=agreePrivacyAuthorization时有效 （Tips: 如果使用 onNeedPrivacyAuthorization 接口，需要在 bindagreeprivacyauthorization 触发后再调用 resolve({ event: "agree", buttonId })）	2.32.3

代码示例

 <button type="default">页面次要操作 Normal</button>

2.5 input

输入框组件，用于接受输入文字。

通用属性

属性	类型	默认值	必填	说明	最低版本
value	string		是	输入框的初始内容	1.0.0
type	string	text	否	input 的类型	1.0.0
合法值 说明 最低版本 text 文本输入键盘 number 数字输入键盘 idcard 身份证输入键盘 digit 带小数点的数字键盘 safe-password 密码安全输入键盘 指引。仅 Webview 支持。 2.18.0 nickname 昵称输入键盘。 2.21.2
password	boolean	false	否	是否是密码类型	1.0.0
placeholder	string		是	输入框为空时占位符	1.0.0
placeholder-style	string		是	指定 placeholder 的样式	1.0.0
disabled	boolean	false	否	是否禁用	1.0.0
maxlength	number	140	否	最大输入长度，设置为 -1 的时候不限制最大长度	1.0.0
cursor-spacing	number	0	否	指定光标与键盘的距离，取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离	1.0.0
auto-focus	boolean	false	否	(即将废弃，请直接使用 focus )自动聚焦，拉起键盘	1.0.0
focus	boolean	false	否	获取焦点	1.0.0
confirm-type	string	done	否	设置键盘右下角按钮的文字，仅在type='text'时生效	1.1.0
合法值 说明 send 右下角按钮为“发送” search 右下角按钮为“搜索” next 右下角按钮为“下一个” go 右下角按钮为“前往” done 右下角按钮为“完成”
always-embed	boolean	false	否	强制 input 处于同层状态，默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效)	2.10.4
confirm-hold	boolean	false	否	点击键盘右下角按钮时是否保持键盘不收起	1.1.0
cursor	number		是	指定focus时的光标位置	1.5.0
cursor-color	string		是	光标颜色。iOS 下的格式为十六进制颜色值 #000000，安卓下的只支持 default 和 green，Skyline 下无限制	3.1.0
selection-start	number	-1	否	光标起始位置，自动聚集时有效，需与selection-end搭配使用	1.9.0
selection-end	number	-1	否	光标结束位置，自动聚集时有效，需与selection-start搭配使用	1.9.0
adjust-position	boolean	true	否	键盘弹起时，是否自动上推页面	1.9.90
hold-keyboard	boolean	false	否	focus时，点击页面的时候不收起键盘	2.8.2
safe-password-cert-path	string		否	安全键盘加密公钥的路径，只支持包内路径	2.18.0
safe-password-length	number		否	安全键盘输入密码长度	2.18.0
safe-password-time-stamp	number		否	安全键盘加密时间戳	2.18.0
safe-password-nonce	string		否	安全键盘加密盐值	2.18.0
safe-password-salt	string		否	安全键盘计算hash盐值，若指定custom-hash 则无效	2.18.0
safe-password-custom-hash	string		否	安全键盘计算hash的算法表达式，如 md5(sha1('foo' + sha256(sm3(password + 'bar'))))	2.18.0
bindinput	eventhandle		是	键盘输入时触发，event.detail = {value, cursor, keyCode}，keyCode 为键值，2.1.0 起支持，处理函数可以直接 return 一个字符串，将替换输入框的内容。	1.0.0
bindfocus	eventhandle		是	输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度，在基础库 1.9.90 起支持	1.0.0
bindblur	eventhandle		是	输入框失去焦点时触发，event.detail = { value, encryptedValue, encryptError }	1.0.0
bindconfirm	eventhandle		是	点击完成按钮时触发，event.detail = { value }	1.0.0
bindkeyboardheightchange	eventhandle		是	键盘高度发生变化的时候触发此事件，event.detail = {height: height, duration: duration}	2.7.0
bindnicknamereview	eventhandle		是	用户昵称审核完毕后触发，仅在 type 为 "nickname" 时有效，event.detail = { pass, timeout }

skyline特有属性

属性	类型	默认值	必填	说明	最低版本
bind:selectionchange	eventhandle		否	选区改变事件, {selectionStart, selectionEnd}	3.2.0
bind:keyboardcompositionstart	eventhandle		否	输入法开始新的输入时触发 （仅当输入法支持时触发）	3.2.0
bind:keyboardcompositionupdate	eventhandle		否	输入法输入字符时触发（仅当输入法支持时触发）	3.2.0
bind:keyboardcompositionend	eventhandle		否	输入法输入结束时触发（仅当输入法支持时触发）	3.2.0
worklet:onkeyboardheightchange	worklet		否	键盘高度变化时触发。event.detail = {height: height, pageBottomPadding: pageBottomPadding}； height: 键盘高度，pageBottomPadding: 页面上推高度	3.2.4

webview特有属性

属性	类型	默认值	必填	说明	最低版本
placeholder-class	string	input-placeholder	否	指定 placeholder 的样式类	1.0.0

微信小程序官方文档：视图容器 | 微信开放文档 (qq.com)