微信小程序学习总结(五)
一. 表单组件(重点)
1.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 微信开放能力
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 手指松开后点击态保留时间,单位毫秒
lang String en 指定返回用户信息的语言,zh_CN 简体中文,zh_TW 繁体中文,en 英文。 open-type="getUserInfo"
bindgetuserinfo Handler 用户点击该按钮时,会返回获取到的用户信息,回调的detail数据与wx.getUserInfo返回的一致 open-type="getUserInfo" 1.3.0
session-from String 会话来源 open-type="contact"
send-message-title String 当前标题 会话内消息卡片标题 open-type="contact"
send-message-path String 当前分享路径 会话内消息卡片点击跳转小程序路径 o
send-message-img String 截图 会话内消息卡片图片 open-type="contact"
show-message-card Boolean false 显示会话内消息卡片 open-type="contact"
bindcontact Handler 客服消息回调 open-type="contact"
bindgetphonenumber Handler 获取用户手机号回调 open-type="getPhoneNumber"
app-parameter String 打开 APP 时,向 APP 传递的参数 open-type="launchApp"
binderror Handler 当使用开放能力时,发生错误的回调 open-type="launchApp"
bindopensetting Handler 在打开授权设置页后回调 open-type="openSetting"
注意:
1:button-hover 默认为{background-color: rgba(0, 0, 0, 0.1); opacity:0.7;}
2:在bindgetphonenumber 等返回加密信息的回调中调用 wx.login 登录,可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的sessionKey,导致解密失败。建议开发者提前进行 login;或者在回调中先使用 checkSession 进行登录态检查,避免login 刷新登录态。
3:从 2.1.0 起,button 可作为原生组件的子节点嵌入,以便在原生组件上使用 open-type 的能力
4. 目前,设置了 form-type 的 button 只会对当前组件中的 form 有效。因而,将 button 封装在自定义组件中,而 from 在自定义组件外,将会使这个 button 的 form-type 失效
size 有效值:
default 默认大小; mini 小尺寸
type 有效值:
primary 绿色; default 白色; warn 红色
form-type 有效值:
submit 提交表单; reset 重置表单
open-type有效值 说明
contact 打开客服会话
share 触发用户转发,使用前建议先阅读使用指引
getUserInfo 获取用户信息,可以从bindgetuserinfo回调中获取到用户信息
getPhoneNumber 获取用户手机号,可以从bindgetphonenumber回调中获取到用户信息,具体说明
launchApp 打开APP,可以通过app-parameter属性设定向APP传的参数具体说明
openSetting 打开授权设置页
feedback 打开“意见反馈”页面,用户可提交反馈内容并上传日志,开发者可以登录小程序管理后台后进入左侧菜单“客服反馈”页面获取到反馈内容
2. checkbox-group 多项选择器,内部由多个checkbox组成
属性名 类型 说明
bindchange EventHandle <checkbox-group/>中选中项发生改变是触发 change 事件,detail = {value:[选中的checkbox的value的数组]}
checkbox 多选项目
属性名 类型 默认值 说明
value String <checkbox/>标识,选中时触发<checkbox-group/>的 change 事件,并携带 <checkbox/> 的 value
disabled Boolean false 是否禁用
checked Boolean false 当前是否选中,可用来设置默认选中
color Color c heckbox的颜色,同css的color
3. form
表单,将组件内的用户输入
<switch/> <input/> <checkbox/> <slider/> <radio/><picker/>
提交
当点击<form/>
表单中 formType 为 submit 的<button/>
组件时,会将表单组件中的 value 值进行提交,需要在表单组件中加上 name 来作为 key
属性名 类型 说明
report-submit Boolean 是否返回 formId 用于发送模板消息
bindsubmit EventHandle 携带 form 中的数据触发 submit 事件,event.detail = {value : {'name': 'value'} , formId: ''}
bindreset EventHandle 表单重置时会触发 reset 事件
4. 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 指定的距离的最小值作为光标与键盘的距离
focus Boolean false 获取焦点
confirm-type String "done" 设置键盘右下角按钮的文字,仅在type='text'时生效
confirm-hold Boolean false 点击键盘右下角按钮时是否保持键盘不收起
cursor Number 指定focus时的光标位置
selection-start Number -1 光标起始位置,自动聚集时有效,需与selection-end搭配使用
selection-end Number -1 光标结束位置,自动聚集时有效,需与selection-start搭配使用
adjust-position Boolean true 键盘弹起时,是否自动上推页面
bindinput EventHandle 键盘输入时触发,event.detail = {value, cursor, keyCode},keyCode 为键值,2.1.0 起支持,处理函数可以直接 return 一个字符串,将替换输入框的内容。
bindfocus EventHandle 输入框聚焦时触发,event.detail = { value, height },height 为键盘高度,在基础库 1.9.90 起支持
bindblur EventHandle 输入框失去焦点时触发,event.detail = {value: value}
bindconfirm EventHandle 点击完成按钮时触发,event.detail = {value: value}
type 有效值:
值 说明
text 文本输入键盘
number 数字输入键盘
idcard 身份证输入键盘
digit 带小数点的数字键盘
confirm-type 有效值:
值 说明
send 右下角按钮为“发送”
search 右下角按钮为“搜索”
next 右下角按钮为“下一个”
go 右下角按钮为“前往”
done 右下角按钮为“完成”
注意:
- confirm-type的最终表现与手机输入法本身的实现有关,部分安卓系统输入法和第三方输入法可能不支持或不完全支持
- input 组件是一个原生组件,字体是系统字体,所以无法设置 font-family;
- 在 input 聚焦期间,避免使用 css 动画;
- 对于将 input 封装在自定义组件中、而 from 在自定义组件外的情况,form 将不能获得这个自定义组件中 input 的值。此时需要使用自定义组件的 内置 behaviors wx://form-field
5. label
- 用来改进表单组件的可用性,使用
for
属性找到对应的id
,或者将控件放在该标签下,当点击时,就会触发对应的控件。for
优先级高于内部控件,内部有多个控件的时候默认触发第一个控件- 目前可以绑定的控件有:
<button/>, <checkbox/>, <radio/>, <switch/>
6. picker
从底部弹起的滚动选择器,现支持五种选择器,通过
mode
来区分,分别是普通选择器,多列选择器,时间选择器,日期选择器,省市区选择器,默认是普通选择器
普通选择器: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 是否禁用
bindcancel EventHandle 取消选择或点遮罩层收起 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 [] value 每一项的值表示选择了 range 对应项中的第几个(下标从 0 开始)
bindchange EventHandle value 改变时触发 change 事件,event.detail = {value: value}
bindcolumnchange EventHandle 某一列的值改变时触发 columnchange 事件,event.detail = {column: column, value: value},column 的值表示改变了第几列(下标从0开始),value 的值表示变更值的下标
bindcancel EventHandle 取消选择时触发
disabled Boolean false 是否禁用
时间选择器:mode = time
属性名 类型 默认值 说明
value String 表示选中的时间,格式为"hh:mm"
start String 表示有效时间范围的开始,字符串格式为"hh:mm"
end String 表示有效时间范围的结束,字符串格式为"hh:mm"
bindchange EventHandle value 改变时触发 change 事件,event.detail = {value: value}
bindcancel EventHandle 取消选择时触发
disabled Boolean false 是否禁用
日期选择器: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}
bindcancel EventHandle 取消选择时触发
disabled Boolean false 是否禁用
fields 有效值:
值 说明
year 选择器粒度为年
month 选择器粒度为月份
day 选择器粒度为天
省市区选择器:mode = region
属性名 类型 默认值 说明
value Array [] 表示选中的省市区,默认选中每一列的第一个值
custom-item String 可为每一列的顶部添加一个自定义的项
bindchange EventHandl value 改变时触发 change 事件,event.detail = {value: value, code: code, postcode: postcode},其中字段code是统计用区划代码,postcode是邮政编码
bindcancel EventHandle 取消选择时触发
disabled Boolean false 是否禁用
7. picker-view 嵌入页面的滚动选择器
属性名 类型 说明
value NumberArray 数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项(下标从 0 开始),数字大于 picker-view-column 可选项长度时,选择最后一项。
indicator-style String 设置选择器中间选中框的样式
indicator-class String 设置选择器中间选中框的类名
mask-style String 设置蒙层的样式
mask-class String 设置蒙层的类名
bindchange EventHandle 当滚动选择,value 改变时触发 change 事件,event.detail = {value: value};value为数组,表示 picker-view 内的 picker-view-column 当前选择的是第几项(下标从 0 开始)
picker-view-column
仅可放置于中,其孩子节点的高度会自动设置成与picker-view的选中框的高度一致
注意:
- 其中只可放置组件,其他节点不会显示。
- 滚动时在iOS自带振动反馈,可在系统设置 -> 声音与触感 -> 系统触感反馈中关闭
8. radio 单选项目
radio-group 单项选择器,内部由多个组成。
属性名 类型 说明
bindchange EventHandle <radio-group/>中的选中项发生变化时触发 change 事件,event.detail = {value: 选中项radio的value}
radio 单选项目
属性名 类型 默认值 说明
value String <radio/> 标识。当该<radio/> 选中时,<radio-group/> 的 change 事件会携带<radio/>的value
checked Boolean false 当前是否选中
disabled Boolean false 是否禁用
color Color radio的颜色,同css的color
9. slider 滑动选择器
属性名 类型 默认值 说明
min Number 0 最小值
max Number 100 最大值
step Number 1 步长,取值必须大于 0,并且可被(max - min)整除
disabled Boolean false 是否禁用
value Number 0 当前取值
color Color #e9e9e9 背景条的颜色(请使用 backgroundColor)
activeColor Color #1aad19 已选择的颜色
backgroundColor Color #e9e9e9 背景条的颜色
block-size Number 28 滑块的大小,取值范围为 12 - 28
block-color Color #ffffff 滑块的颜色
show-value Boolean false 是否显示当前 value
bindchange EventHandle 完成一次拖动后触发的事件,event.detail = {value: value}
bindchanging EventHandle 拖动过程中触发的事件,event.detail = {value: value}
10. switch 开关选择器
属性名 类型 默认值 说明
checked Boolean false 是否选中
disabled Boolean false 是否禁用
type String switch 样式,有效值:switch, checkbox
bindchange EventHandle checked改变时触发 change 事件,event.detail={ value:checked}
color Color switch的颜色,同 css 的 color
注意: switch类型切换时在iOS自带振动反馈,可在系统设置 -> 声音与触感 -> 系统触感反馈中关闭
-
textarea 多行文本输入框.该组件是原生组件,使用时请注意相关限制
属性名 类型 默认值 说明 value String 输入框的内容 placeholder String 输入框为空时占位符 placeholder-style String 指定 placeholder 的样式 placeholder-class String textarea-placeholder 指定 placeholder 的样式类 disabled Boolean false 是否禁用 maxlength Number 140 最大输入长度,设置为 -1 的时候不限制最大长度 auto-focus Boolean false 自动聚焦,拉起键盘 focus Boolean false 获取焦点 auto-height Boolean false 是否自动增高,设置auto-height时,style.height不生效 fixed Boolean false 如果 textarea 是在一个 position:fixed 的区域,需要显示指定属性 fixed 为 true cursor-spacing Number 0 指定光标与键盘的距离,单位 px 。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离 cursor Number 指定focus时的光标位置 show-confirm-bar Boolean true 是否显示键盘上方带有”完成“按钮那一栏 selection-start Number -1 光标起始位置,自动聚集时有效,需与selection-end搭配使用 selection-end Number -1 光标结束位置,自动聚集时有效,需与selection-start搭配使用 adjust-position Boolean true 键盘弹起时,是否自动上推页面 bindfocus EventHandle 输入框聚焦时触发,event.detail = { value, height },height 为键盘高度 bindblur EventHandle 输入框失去焦点时触发,event.detail = {value, cursor} bindlinechange EventHandle 输入框行数变化时调用,event.detail = {height: 0, heightRpx: 0, lineCount: 0} bindinput EventHandle 当键盘输入时,触发 input 事件,event.detail = {value, cursor},bindinput 处理函数的返回值并不会反映到 textarea 上 bindconfirm EventHandle 点击完成时, 触发 confirm 事件,event.detail = {value: value}
注意:
1 .
textarea
的blur
事件会晚于页面上的tap
事件,如果需要在 button 的点击事件获取 textarea,可以使用 form 的 bindsubmit
2.不建议在多行文本上对用户的输入进行修改,所以 textarea 的bindinput
处理函数并不会将返回值反映到 textarea 上。
二. 地图
map 地图
该组件是原生组件,使用时请注意相关限制。 个性化地图能力可在小程序后台“设置-开发者工具-腾讯位置服务”申请开通。
设置subkey
后,小程序内的地图组件均会使用该底图效果
属性名 类型 默认值 说明
longitude Number 中心经度
latitude Number 中心纬度
scale Number 16 缩放级别,取值范围为5-18
markers Array 标记点
polyline Array 路线
polygons Array 多边形
circles Array 圆
include-points Array 缩放视野以包含所有给定的坐标点
show-location Boolean 显示带有方向的当前定位点
subkey String 个性化地图使用的key,仅初始化地图时有效
show-compass Boolean false 显示指南针
enable-overlooking Boolean false 开启俯视
enable-zoom Boolean true 是否支持缩放
enable-scroll Boolean true 是否支持拖动
enable-rotate Boolean false 是否支持旋转
bindmarkertap EventHandle 点击标记点时触发,会返回marker的id
bindcallouttap EventHandle 点击标记点对应的气泡时触发,会返回marker的id
bindcontroltap EventHandle 点击控件时触发,会返回control的id
bindregionchange EventHandle 视野发生变化时触发 2.3.0起增加causedBy 参数区分拖动、缩放和调用接口等来源
bindtap EventHandle 点击地图时触发
bindupdated EventHandle 在地图渲染更新完成时触发
bindpoitap EventHandle 点击地图poi点时触发
markers
标记点用于在地图上显示标记的位置
属性 说明 类型 必填 备注
id 标记点id Number 否 marker点击事件回调会返回此id。建议为每个marker设置上Number类型id,保证更新marker时有更好的性能。
latitude 纬度 Number 是 浮点数,范围 -90 ~ 90
longitude 经度 Number 是 浮点数,范围 -180 ~ 180
title 标注点名 String 否
zIndex 显示层级 Number 否
iconPath 显示的图标 String 是 项目目录下的图片路径,支持相对路径写法,以'/'开头则表示相对小程序根目录;也支持临时路径和网络图片
rotate 旋转角度 Number 否 顺时针旋转的角度,范围 0 ~ 360,默认为 0
alpha 标注的透明度 Number 否 默认1,无透明,范围 0 ~ 1
width 标注图标宽度 Number 否 默认为图片实际宽度
height 标注图标高度 Number 否 默认为图片实际高度
callout 自定义标记点上方的气泡窗口 Object 否 支持的属性见下表,可识别换行符
label 为标记点旁边增加标签 Object 否 支持的属性见下表,可识别换行符
anchor 经纬度在标注图标的锚点,默认底边中点 Object 否 {x, y},x表示横向(0-1),y表示竖向(0-1)。{x: .5, y: 1} 表示底边中
marker 上的气泡 callout
属性 说明 类型
content 文本 String
color 文本颜色 String
fontSize 文字大小 Number
borderRadius 边框圆角 Number
borderWidth 边框宽度 Number
borderColor 边框颜色 String
bgColor 背景色 String
padding 文本边缘留白 Number
display 'BYCLICK':点击显示; 'ALWAYS':常显 String
textAlign 文本对齐方式。有效值: left, right, center String
marker 上的气泡 label
属性 说明 类型
content 文本 String
color 文本颜色 String
fontSize 文字大小 Number
anchorX label的坐标,原点是 marker 对应的经纬度 Number
anchorY label的坐标,原点是 marker 对应的经纬度 Number
borderWidth 边框宽度 Number
borderColor 边框颜色 String
borderRadius 边框圆角 Number
bgColor 背景色 String
padding 文本边缘留白 Number
textAlign 文本对齐方式。有效值: left, right, center String
polyline
指定一系列坐标点,从数组第一项连线至最后一项
属性 说明 类型 必填 备注
points 经纬度数组 Array 是 [{latitude: 0, longitude: 0}]
color 线的颜色 String 否 8位十六进制表示,后两位表示alpha值,如:#000000AA
width 线的宽度 Number 否
dottedLine 是否虚线 Boolean 否 默认false
arrowIconPath 更换箭头图标 String 否 在arrowLine为true时生效
borderColor 线的边框颜色 String 否
borderWidth 线的厚度 Number 否
polygons
指定一系列坐标点,根据 points 坐标数据生成闭合多边形
属性 说明 类型 必填 备注
points 经纬度数 Array 是 [{latitude: 0, longitude: 0}]
strokeWidth 描边的宽度 Number 否
strokeColor 描边的颜色 String 否 8位十六进制表示,后两位表示alpha值,如:#000000AA
fillColor 填充颜色 String 否 8位十六进制表示,后两位表示alpha值,如:#000000AA
zIndex 设置多边形Z轴数值 Number 否
circles
在地图上显示圆
属性 说明 类型 必填 备注
latitude 纬度 Number 是 浮点数,范围 -90 ~ 90
longitude 经度 Number 是 浮点数,范围 -180 ~ 180
color 描边的颜色 String 否 8位十六进制表示,后两位表示alpha值,如:#000000AA
fillColor 填充颜色 String 否 8位十六进制表示,后两位表示alpha值,如:#000000AA
radius 半径 Number 是
strokeWidth 描边的宽度 Number 否
position
属性 说明 类型 必填 备注
left 距离地图的左边界多远 Number 否 默认为0
top 距离地图的上边界多远 Number 否 默认为0
width 控件宽度 Number 否 默认为图片宽度
height 控件高度 Number 否 默认为图片高度
注意:
- 地图组件的经纬度必填, 如果不填经纬度则默认值是北京的经纬度
- map 组件使用的经纬度是火星坐标系,调用
wx.getLocation
接口需要指定type
为gcj02