w3cschool-微信小程序开发文档-组件

https://www.w3cschool.cn/weixinapp/sp6z1q8q.html

微信小程序视图容器 view

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="section">
  <view class="section__title">flex-direction: row</view>
  <view class="flex-wrp" style="flex-direction:row;">
    <view class="flex-item bc_green">1</view>
    <view class="flex-item bc_red">2</view>
    <view class="flex-item bc_blue">3</view>
  </view>
</view>
<view class="section">
  <view class="section__title">flex-direction: column</view>
  <viewclass="flex-wrp"style="height: 300px;flex-direction:column;">
    <viewclass="flex-item bc_green">1</view>
    <viewclass="flex-item bc_red">2</view>
    <viewclass="flex-item bc_blue">3</view>
  </view>
</view>

微信小程序视图容器 scroll-view

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}

使用竖向滚动时，需要给<scroll-view/>一个固定高度，通过 WXSS 设置 height。

示例代码：

<view class="section">
  <view class="section__title">vertical scroll</view>
  <scroll-view scroll-y style="height: 200px;" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}">
    <view id="green" class="scroll-view-item bc_green"></view>
    <view id="red"  class="scroll-view-item bc_red"></view>
    <view id="yellow" class="scroll-view-item bc_yellow"></view>
    <view id="blue" class="scroll-view-item bc_blue"></view>
  </scroll-view>

  <view class="btn-area">
    <button size="mini" bindtap="tap">click me to scroll into view </button>
    <button size="mini" bindtap="tapMove">click me to scroll</button>
  </view>
</view>
<view class="section section_gap">
  <view class="section__title">horizontal scroll</view>
  <scroll-view class="scroll-view_H" scroll-x="true" style="width: 100%">
    <view id="green" class="scroll-view-item_H bc_green"></view>
    <view id="red"  class="scroll-view-item_H bc_red"></view>
    <view id="yellow" class="scroll-view-item_H bc_yellow"></view>
    <view id="blue" class="scroll-view-item_H bc_blue"></view>
  </scroll-view>
</view>

var order = ['red', 'yellow', 'blue', 'green', 'red']
Page({
  data: {
    toView: 'red',
    scrollTop: 100
  },
  upper: function(e) {
    console.log(e)
  },
  lower: function(e) {
    console.log(e)
  },
  scroll: function(e) {
    console.log(e)
  },
  tap: function(e) {
    for (var i = 0; i < order.length; ++i) {
      if (order[i] === this.data.toView) {
        this.setData({
          toView: order[i + 1]
        })
        break
      }
    }
  },
  tapMove: function(e) {
    this.setData({
      scrollTop: this.data.scrollTop + 10
    })
  }
})

微信小程序滑块视图容器 滑块视图容器

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
display-multiple-items	number	1	否	同时显示的滑块数量	1.9.0
skip-hidden-item-layout	boolean	false	否	是否跳过未显示的滑块布局，设为 true 可优化复杂情况下的滑动性能，但会丢失隐藏状态滑块的布局信息	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	缓入缓出动画

从公共库v1.4.0开始，change事件返回detail中包含一个source字段，表示导致变更的原因，可能值如下：

• autoplay自动播放导致swiper变化；
• touch用户划动引起swiper变化；
• 其他原因将用空字符串表示。

注意：如果在 bindchange 的事件回调函数中使用 setData 改变 current 值，则有可能导致 setData 被不停地调用，因而通常情况下请在改变 current 值前检测 source 字段来判断是否是由于用户触摸引起。

swiper-item

基础库 1.0.0 开始支持，低版本需做兼容处理。

仅可放置在<swiper/>组件中，宽高自动设置为100%。

属性	类型	默认值	必填	说明	最低版本
item-id	string		否	该 swiper-item 的标识符	1.9.0

示例代码：

<swiper indicator-dots="{{indicatorDots}}"
  autoplay="{{autoplay}}" interval="{{interval}}" duration="{{duration}}">
  <block wx:for="{{imgUrls}}">
    <swiper-item>
      <image src="{{item}}" class="slide-image" width="355" height="150"/>
    </swiper-item>
  </block>
</swiper>
<button bindtap="changeIndicatorDots"> indicator-dots </button>
<button bindtap="changeAutoplay"> autoplay </button>
<slider bindchange="intervalChange" show-value min="500" max="2000"/> interval
<slider bindchange="durationChange" show-value min="1000" max="10000"/> duration

微信小程序视图容器 movable-area

movable-view

基础库 1.2.0 开始支持，低版本需做兼容处理

可移动的视图容器，在页面中可以拖拽滑动

属性名	类型	默认值	说明
direction	String	none	movable-view的移动方向，属性值有all、vertical、horizontal、none
inertia	Boolean	false	movable-view是否带有惯性
out-of-bounds	Boolean	false	超过可移动区域后，movable-view是否还可以移动
x	Number		定义x轴方向的偏移，如果x的值不在可移动范围内，会自动移动到可移动范围；改变x的值会触发动画
y	Number		定义y轴方向的偏移，如果y的值不在可移动范围内，会自动移动到可移动范围；改变y的值会触发动画
damping	Number	20	阻尼系数，用于控制x或y改变时的动画和过界回弹的动画，值越大移动越快
friction	Number	2	摩擦系数，用于控制惯性滑动的动画，值越大摩擦力越大，滑动越快停止；必须大于0，否则会被设置成默认值

movable-view 必须设置width和height属性，不设置默认为10px

movable-view 默认为绝对定位，top和left属性为0px

当movable-view小于movable-area时，movable-view的移动范围是在movable-area内；当movable-view大于movable-area时，movable-view的移动范围必须包含movable-area（x轴方向和y轴方向分开考虑）

注意：movable-view必须在<movable-area/>组件中，并且必须是直接子节点，否则不能移动。

示例代码：

<view class="section">
  <view class="section__title">movable-view区域小于movable-area</view>
  <movable-area style="height: 200px;width: 200px;background: red;">
    <movable-view style="height: 50px; width: 50px; background: blue;" x="{{x}}" y="{{y}}" direction="all">
    </movable-view>
  </movable-area>
  <view class="btn-area">
    <button size="mini" bindtap="tap">click me to move to (30px, 30px)</button>
  </view>
  <view class="section__title">movable-view区域大于movable-area</view>
  <movable-area style="height: 100px;width: 100px;background: red;" direction="all">
    <movable-view style="height: 200px; width: 200px; background: blue;">
    </movable-view>
  </movable-area>
</view>

Page({
  data: {
    x: 0,
    y: 0
  },
  tap: function(e) {
    this.setData({
      x: 30,
      y: 30
    });
  }
})

微信小程序视图容器 cover-view

cover-view

基础库 1.4.0 开始支持，低版本需做兼容处理。

覆盖在原生组件之上的文本视图。

可覆盖的原生组件包括 map、video、canvas、camera、live-player、live-pusher

只支持嵌套 cover-view、cover-image，可在 cover-view 中使用 button。组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

属性	类型	默认值	必填	说明	最低版本
scroll-top	number/string		否	设置顶部滚动偏移量，仅在设置了 overflow-y: scroll 成为滚动元素后生效	2.1.0

提示

1. cover-view和cover-image的aria-role仅可设置为button，读屏模式下才可以点击，并朗读出“按钮”；为空时可以聚焦，但不可点击
2. 基础库 2.2.4 起支持 touch 相关事件，也可使用 hover-class 设置点击态
3. 基础库 2.1.0 起支持设置 scale rotate 的 css 样式，包括 transition 动画
4. 基础库 1.9.90 起 cover-view 支持 overflow: scroll，但不支持动态更新 overflow
5. 基础库 1.9.90 起最外层 cover-view 支持 position: fixed
6. 基础库 1.9.0 起支持插在 view 等标签下。在此之前只可嵌套在原生组件map、video、canvas、camera内，避免嵌套在其他组件内。
7. 基础库 1.6.0 起支持css transition动画，transition-property只支持transform (translateX, translateY)与opacity。
8. 基础库 1.6.0 起支持css opacity。
9. 事件模型遵循冒泡模型，但不会冒泡到原生组件。
10. 文本建议都套上cover-view标签，避免排版错误。
11. 只支持基本的定位、布局、文本样式。不支持设置单边的border、background-image、shadow、overflow: visible等。
12. 建议子节点不要溢出父节点
13. 支持使用 z-index 控制层级
14. 默认设置的样式有：white-space: nowrap; line-height: 1.2; display: block;
15. 自定义组件嵌套 cover-view 时，自定义组件的 slot 及其父节点暂不支持通过 wx:if 控制显隐，否则会导致 cover-view 不显示

微信小程序视图容器 cover-image

cover-image

基础库 1.4.0 开始支持，低版本需做兼容处理。

覆盖在原生组件之上的图片视图。可覆盖的原生组件同cover-view，支持嵌套在cover-view里。

属性	类型	默认值	必填	说明	最低版本
src	string		否	图标路径，支持临时路径、网络地址（1.6.0起支持）、云文件ID（2.2.3起支持）。	1.4.0
bindload	eventhandle		否	图片加载成功时触发	2.1.0
binderror	eventhandle		否	图片加载失败时触发	2.1.0

支持的格式

格式	iOS	Android
JPG	√	√
PNG	√	√
SVG	x	x
WEBP	√	√
GIF	√	√
BASE64	x	x

微信小程序内容组件图标 icon

icon

基础库 1.0.0 开始支持，低版本需做兼容处理。

图标。组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

属性名	类型	默认值	说明
type	String		icon的类型，有效值：success, success_no_circle, info, warn, waiting, cancel, download, search, clear
size	Number	23	icon的大小，单位px
color	Color		icon的颜色，同css的color

Page({ data: { iconSize: [20, 30, 40, 50, 60, 70], iconColor: [ 'red', 'orange', 'yellow', 'green', 'rgb(0,255,255)', 'blue', 'purple' ], iconType: [ 'success', 'success_no_circle', 'info', 'warn', 'waiting', 'cancel', 'download', 'search', 'clear' ] } })

微信小程序内容组件 text（文本）

2020-07-24 14:44 更新

text

---

文本。

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

space 有效值：

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

Tips

• decode可以解析的有   < > & '    
• 各个操作系统的空格标准并不一致。
• <text/> 组件内只支持 <text/> 嵌套。
• 除了文本节点以外的其他节点都无法长按选中。

示例：

代码片段

<view class="btn-area">
  <view class="body-view">
    <text>{{text}}</text>
    <button bindtap="add">add line</button>
    <button bindtap="remove">remove line</button>
  </view>
</view>

var initData = 'this is first line\nthis is second line'
var extraLine = [];
Page({
  data: {
    text: initData
  },
  add: function(e) {
    extraLine.push('other line')
    this.setData({
      text: initData + '\n' + extraLine.join('\n')
    })
  },
  remove: function(e) {
    if (extraLine.length > 0) {
      extraLine.pop()
      this.setData({
        text: initData + '\n' + extraLine.join('\n')
      })
    }
  }
})

微信小程序内容组件 rich-text

# 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

微信小程序内容组件 progress

progress

基础库 1.0.0 开始支持，低版本需做兼容处理。

进度条。组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

属性	类型	默认值	必填	说明	最低版本
percent	number		否	百分比0~100	1.0.0
show-info	boolean	false	否	在进度条右侧显示百分比	1.0.0
border-radius	number/string	0	否	圆角大小	2.3.1
font-size	number/string	16	否	右侧百分比字体大小	2.3.1
stroke-width	number/string	6	否	进度条线的宽度	1.0.0
color	string	#09BB07	否	进度条颜色（请使用activeColor）	1.0.0
activeColor	string	#09BB07	否	已选择的进度条的颜色	1.0.0
backgroundColor	string	#EBEBEB	否	未选择的进度条的颜色	1.0.0
active	boolean	false	否	进度条从左往右的动画	1.0.0
active-mode	string	backwards	否	backwards: 动画从头播；forwards：动画从上次结束点接着播	1.7.0
duration	number	30	否	进度增加1%所需毫秒数	2.8.2
bindactiveend	eventhandle		否	动画完成事件	2.4.1

示例代码

<view class="progress-box">
  <progress percent="20" show-info stroke-width="3"/>
</view>

<view class="progress-box">
  <progress percent="40" active stroke-width="3" />
  <icon class="progress-cancel" type="cancel"></icon>
</view>

<view class="progress-box">
  <progress percent="60" active stroke-width="3" />
</view>

<view class="progress-box">
  <progress percent="80" color="#10AEFF" active stroke-width="3" />
</view>

微信小程序按钮组件：button

微信小程序表单组件 checkbox

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		checkbox的颜色，同css的color

示例：

<checkbox-group bindchange="checkboxChange">
    <label class="checkbox" wx:for-items="{{items}}">
        <checkbox value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}
    </label>
</checkbox-group>

Page({
  data: {
    items: [
      {name: 'USA', value: '美国'},
      {name: 'CHN', value: '中国', checked: 'true'},
      {name: 'BRA', value: '巴西'},
      {name: 'JPN', value: '日本'},
      {name: 'ENG', value: '英国'},
      {name: 'TUR', value: '法国'},
    ]
  },
  checkboxChange: function(e) {
    console.log('checkbox发生change事件，携带value值为：', e.detail.value)
  }
})

微信小程序form

基础库 1.0.0 开始支持，低版本需做兼容处理。

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

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

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

示例代码：

<form bindsubmit="formSubmit" bindreset="formReset">
    <view class="section section_gap">
        <view class="section__title">switch</view>
        <switch name="switch"/>
    </view>
    <view class="section section_gap">
        <view class="section__title">slider</view>
        <slider name="slider" show-value ></slider>
    </view>

    <view class="section">
        <view class="section__title">input</view>
        <input name="input" placeholder="please input here" />
    </view>
    <view class="section section_gap">
        <view class="section__title">radio</view>
        <radio-group name="radio-group">
            <label><radio value="radio1"/>radio1</label>
            <label><radio value="radio2"/>radio2</label>
        </radio-group>
    </view>
    <view class="section section_gap">
        <view class="section__title">checkbox</view>
        <checkbox-group name="checkbox">
            <label><checkbox value="checkbox1"/>checkbox1</label>
            <label><checkbox value="checkbox2"/>checkbox2</label>
        </checkbox-group>
    </view>
    <view class="btn-area">
        <button formType="submit">Submit</button>
        <button formType="reset">Reset</button>
    </view>
</form>

Page({
  formSubmit: function(e) {
    console.log('form发生了submit事件，携带数据为：', e.detail.value)
  },
  formReset: function() {
    console.log('form发生了reset事件')
  }
})

微信小程序表单组件输入框 input

微信小程序表单组件 label

微信小程序表单组件 表单组件 picker

2020-07-24 15:12 更新

基础库 1.0.0 开始支持，低版本需做兼容处理。

从底部弹起的滚动选择器。

属性	类型	默认值	必填	说明	最低版本
header-text	string		否	选择器的标题，仅安卓可用	2.11.0
mode	string	selector	否	选择器类型	1.0.0
disabled	boolean	false	否	是否禁用	1.0.0
bindcancel	eventhandle		否	取消选择时触发	1.9.90

mode 的合法值

值	说明	最低版本
selector	普通选择器
multiSelector	多列选择器
time	时间选择器
date	日期选择器
region	省市区选择器

除了上述通用的属性，对于不同的mode，picker拥有不同的属性。

微信小程序表单组件 picker-view（嵌入页面的滚动选择器）

2020-07-24 15:11 更新

picker-view

---

嵌入页面的滚动选择器

属性名	类型	说明	最低版本
value	NumberArray	数组中的数字依次表示 picker-view 内的 picker-view-colume 选择的第几项（下标从 0 开始），数字大于 picker-view-column 可选项长度时，选择最后一项。
indicator-style	String	设置选择器中间选中框的样式
indicator-class	String	设置选择器中间选中框的类名	1.1.0
bindchange	EventHandle	当滚动选择，value 改变时触发 change 事件，event.detail = {value: value}；value为数组，表示 picker-view 内的 picker-view-column 当前选择的是第几项（下标从 0 开始）

注意：其中只可放置<picker-view-column/>组件，其他节点不会显示。

picker-view-column

仅可放置于<picker-view />中，其孩子节点的高度会自动设置成与picker-view的选中框的高度一致。

示例代码：

<view>
  <view>{{year}}年{{month}}月{{day}}日</view>
  <picker-view indicator-style="height: 50px;" style="width: 100%; height: 300px;" value="{{value}}" bindchange="bindChange">
    <picker-view-column>
      <view wx:for="{{years}}" style="line-height: 50px">{{item}}年</view>
    </picker-view-column>
    <picker-view-column>
      <view wx:for="{{months}}" style="line-height: 50px">{{item}}月</view>
    </picker-view-column>
    <picker-view-column>
      <view wx:for="{{days}}" style="line-height: 50px">{{item}}日</view>
    </picker-view-column>
  </picker-view>
</view>

微信小程序表单组件单选框 radio

2020-07-24 15:10 更新

微信小程序单选框radio

radio-group

---

单项选择器，内部由多个<radio/>组成。

属性名	类型	默认值	说明
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

<radio-group class="radio-group" bindchange="radioChange">
    <label class="radio" wx:for="{{items}}">
        <radio value="{{item.name}}" checked="{{item.checked}}"/>{{item.value}}
    </label>
</radio-group>

Page({
  data: {
    items: [
      {name: 'USA', value: '美国'},
      {name: 'CHN', value: '中国', checked: 'true'},
      {name: 'BRA', value: '巴西'},
      {name: 'JPN', value: '日本'},
      {name: 'ENG', value: '英国'},
      {name: 'TUR', value: '法国'},
    ]
  },
  radioChange: function(e) {
    console.log('radio发生change事件，携带value值为：', e.detail.value)
  }
})

微信小程序表单组件滑动选择器 slider

2020-07-24 15:10 更新

slider

---

滑动选择器。

属性名	类型	默认值	说明	最低版本
min	Number	0	最小值
max	Number	100	最大值
step	Number	1	步长，取值必须大于 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

2022-03-12 10:16 更新

switch

---

开关选择器。

属性名	类型	默认值	说明
checked	Boolean	false	是否选中
disabled	Boolean	false	是否禁用
type	String	switch	样式，有效值：switch, checkbox
bindchange	EventHandle		checked 改变时触发change事件，event.detail={ value}
color	String	#04BE02	switch的颜色，同css的color

<view class="body-view">
    <switch checked bindchange="switch1Change"/>
    <switch bindchange="switch2Change"/>
</view>

page({
  switch1Checked: function (e){    console.log('switch1 发生 change 事件，携带值为', e.detail.value)  },
  switch2Change: function (e){    console.log('switch2 发生 change 事件，携带值为', e.detail.value)
  }
})

微信小程序表单组件多行输入框 textarea

微信小程序表单组件 editor

2020-07-31 13:55 更新

editor

基础库 2.7.0 开始支持，低版本需做兼容处理。

富文本编辑器，可以对图片、文字进行编辑。

编辑器导出内容支持带标签的 html和纯文本的 text，编辑器内部采用 delta 格式进行存储。

通过setContents接口设置内容时，解析插入的 html 可能会由于一些非法标签导致解析错误，建议开发者在小程序内使用时通过 delta 进行插入。

富文本组件内部引入了一些基本的样式使得内容可以正确的展示，开发时可以进行覆盖。需要注意的是，在其它组件或环境中使用富文本组件导出的html时，需要额外引入 这段样式，并维护<ql-container><ql-editor></ql-editor></ql-container>的结构。

图片控件仅初始化时设置有效。

相关 api：EditorContext

属性	类型	默认值	必填	说明	最低版本
read-only	boolean	false	否	设置编辑器为只读	2.7.0
placeholder	string		否	提示信息	2.7.0
show-img-size	boolean	false	否	点击图片时显示图片大小控件	2.7.0
show-img-toolbar	boolean	false	否	点击图片时显示工具栏控件	2.7.0
show-img-resize	boolean	false	否	点击图片时显示修改尺寸控件	2.7.0
bindready	eventhandle		否	编辑器初始化完成时触发	2.7.0
bindfocus	eventhandle		否	编辑器聚焦时触发，event.detail = {html, text, delta}	2.7.0
bindblur	eventhandle		否	编辑器失去焦点时触发，detail = {html, text, delta}	2.7.0
bindinput	eventhandle		否	编辑器内容改变时触发，detail = {html, text, delta}	2.7.0
bindstatuschange	eventhandle		否	通过 Context 方法改变编辑器内样式时触发，返回选区已设置的样式	2.7.0

编辑器内支持部分 HTML 标签和内联样式，不支持class和id

支持的标签

不满足的标签会被忽略，<div>会被转行为<p>储存。

类型	节点
行内元素	<span> <strong> <b> <ins> <em> <i> <u> <a> <del> <s> <sub> <sup> <img>
块级元素	<p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <ol> <ul> <li>

支持的内联样式

内联样式仅能设置在行内元素或块级元素上，不能同时设置。例如 font-size 归类为行内元素属性，在 p 标签上设置是无效的。

类型	样式
块级样式	text-align direction margin margin-top margin-left margin-right margin-bottom padding padding-top padding-left padding-right padding-bottom line-height text-indent
行内样式	font font-size font-style font-variant font-weight font-family letter-spacing text-decoration color background-color

提示：

1. 使用 catchtouchend 绑定事件则不会使编辑器失去焦点(2.8.3)
2. 插入的 html 中事件绑定会被移除
3. formats 中的 color 属性会统一以 hex 格式返回
4. 粘贴时仅纯文本内容会被拷贝进编辑器
5. 插入 html 到编辑器内时，编辑器会删除一些不必要的标签，以保证内容的统一。例如<p><span>xxx</span></p>会改写为<p>xxx</p>
6. 编辑器聚焦时页面会被上推，系统行为以保证编辑区可见

微信小程序导航 navigator

navigator

基础库 1.0.0 开始支持，低版本需做兼容处理。

页面链接。

属性名	类型	默认值	说明
target	String	self	在哪个目标上发生跳转，默认当前小程序，可选值self/miniProgram
url	String		应用内的跳转链接
open-type	String	navigate	跳转方式
delta	Number		当 open-type 为 'navigateBack' 时有效，表示回退的层数
app-id	String		当target="miniProgram"时有效，要打开的小程序 appId
path	String		当target="miniProgram"时有效，打开的页面路径，如果为空则打开首页
extra-data	Object		当target="miniProgram"时有效，需要传递给目标小程序的数据，目标小程序可在 App.onLaunch() ，App.onShow()  中获取到这份数据。
version	version	release	当target="miniProgram"时有效，要打开的小程序版本，有效值 develop（开发版），trial（体验版），release（正式版），仅在当前小程序为开发版或体验版时此参数有效；如果当前小程序是正式版，则打开的小程序必定是正式版。
hover-class	String	navigator-hover	指定点击时的样式类，当hover-class="none"时，没有点击态效果
hover-stop-propagation	Boolean	false	指定是否阻止本节点的祖先节点出现点击态
hover-start-time	Number	50	按住后多久出现点击态，单位毫秒
hover-stay-time	Number	600	手指松开后点击态保留时间，单位毫秒
bindsuccess	String		当target="miniProgram"时有效，跳转小程序成功
bindfail	String		当target="miniProgram"时有效，跳转小程序失败
bindcomplete	String		当target="miniProgram"时有效，跳转小程序完成

 

open-type 有效值：

值	说明	最低版本
navigate	对应wx.navigateTo的功能
redirect	对应wx.redirectTo的功能
switchTab	对应wx.switchTab的功能
reLaunch	对应wx.reLaunch的功能	1.1.0
navigateBack	对应wx.navigateBack的功能	1.1.0
exit	退出小程序，target="miniProgram"时生效	2.1.0

注：navigator-hover默认为{ opacity: 0.7;}, <navigator/>的子节点背景色应为透明色

示例代码：

/** wxss **/
/** 修改默认的navigator点击态 **/
.navigator-hover {
    color:blue;
}
/** 自定义其他点击态样式类 **/
.other-navigator-hover {
    color:red;
}

<!-- sample.wxml -->
<view class="btn-area">
  <navigator url="/page/navigate/navigate?title=navigate" hover-class="navigator-hover">跳转到新页面</navigator>
  <navigator url="../../redirect/redirect/redirect?title=redirect" open-type="redirect" hover-class="other-navigator-hover">在当前页打开</navigator>
  <navigator url="/page/index/index" open-type="switchTab" hover-class="other-navigator-hover">切换 Tab</navigator>
</view>

<!-- navigator.wxml -->
<view style="text-align:center"> {{title}} </view>
<view> 点击左上角返回回到之前页面 </view>

<!-- redirect.wxml -->
<view style="text-align:center"> {{title}} </view>
<view> 点击左上角返回回到上级页面 </view>

// redirect.js navigator.js
Page({
  onLoad: function(options) {
    this.setData({
      title: options.title
    })
  }
})

微信小程序导航 navigation-bar

2020-07-31 13:59 更新

functional-page-navigator

基础库 2.9.0 开始支持，低版本需做兼容处理。

页面导航条配置节点，用于指定导航栏的一些属性。只能是 page-meta 组件内的第一个节点，需要配合它一同使用。

通过这个节点可以获得类似于调用 wx.setNavigationBarTitle wx.setNavigationBarColor 等接口调用的效果。

属性	类型	默认值	必填	说明	最低版本
title	string		否	导航条标题	2.9.0
loading	boolean	false	否	是否在导航条显示 loading 加载提示	2.9.0
front-color	string		否	导航条前景颜色值，包括按钮、标题、状态栏的颜色，仅支持 #ffffff 和 #000000	2.9.0
background-color	string		否	导航条背景颜色值，有效值为十六进制颜色	2.9.0
color-animation-duration	number	0	否	改变导航栏颜色时的动画时长，默认为 0 （即没有动画效果）	2.9.0
color-animation-timing-func	number	"linear"	否	改变导航栏颜色时的动画方式，支持 linear 、 easeIn 、 easeOut 和 easeInOut	2.9.0

示例代码

<page-meta>
  <navigation-bar
    title="{{nbTitle}}"
    loading="{{nbLoading}}"
    front-color="{{nbFrontColor}}"
    background-color="{{nbBackgroundColor}}"
    color-animation-duration="2000"
    color-animation-timing-func="easeIn"
  />
</page-meta>

Page({
  data: {
    nbFrontColor: '#000000',
    nbBackgroundColor: '#ffffff',
  },
  onLoad() {
    this.setData({
      nbTitle: '新标题',
      nbLoading: true,
      nbFrontColor: '#ffffff',
      nbBackgroundColor: '#000000',
    })
  }
})

微信小程序媒体组件 audio

audio

---

音频。

属性名	类型	默认值	说明
id	String		audio 组件的唯一标识符
src	String		要播放音频的资源地址
loop	Boolean	false	是否循环播放
controls	Boolean	true	是否显示默认控件
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 事件

MediaError.code

返回错误码	描述
MEDIA_ERR_ABORTED	获取资源被用户禁止
MEDIA_ERR_NETWORD	网络错误
MEDIA_ERR_DECODE	解码错误
MEDIA_ERR_SRC_NOT_SUPPOERTED	不合适资源

示例代码：

<!-- audio.wxml -->
<audio poster="{{poster}}" name="{{name}}" author="{{author}}" src="{{src}}" id="myAudio" controls loop></audio>

<button type="primary" bindtap="audioPlay">播放</button>
<button type="primary" bindtap="audioPause">暂停</button>
<button type="primary" bindtap="audio14">设置当前播放时间为14秒</button>
<button type="primary" bindtap="audioStart">回到开头</button>

// audio.js
Page({
  onReady: function (e) {
    // 使用 wx.createAudioContext 获取 audio 上下文 context
    this.audioCtx = wx.createAudioContext('myAudio')
  },
  data: {
    poster: 'http://y.gtimg.cn/music/photo_new/T002R300x300M000003rsKF44GyaSk.jpg?max_age=2592000',
    name: '此时此刻',
    author: '许巍',
    src: 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E06DCBDC9AB7C49FD713D632D313AC4858BACB8DDD29067D3C601481D36E62053BF8DFEAF74C0A5CCFADD6471160CAF3E6A&fromtag=46',
  },
  audioPlay: function () {
    this.audioCtx.play()
  },
  audioPause: function () {
    this.audioCtx.pause()
  },
  audio14: function () {
    this.audioCtx.seek(14)
  },
  audioStart: function () {
    this.audioCtx.seek(0)
  }
})

微信小程序媒体组件 image

微信小程序image

---

图片。

属性名	类型	默认值	说明
src	String		图片资源地址
mode	String	'scaleToFill'	图片裁剪、缩放的模式
binderror	HandleEvent		当错误发生时，发布到AppService的事件名，事件对象event.detail = { errMsg: 'something wrong' }
bindload	HandleEvent		当图片载入完毕时，发布到AppService的事件名，事件对象event.detail = {height:'图片高度px', width:'图片宽度px' }

注：image组件默认宽度300px、高度225px

mode 有效值：

mode有13种模式，其中4种是缩放模式，9种是裁剪模式。

模式	值	说明
缩放	scaleToFill	不保持纵横比缩放图片，使图片的宽高完全拉伸至填满 image 元素
缩放	aspectFit	保持纵横比缩放图片，使图片的长边能完全显示出来。也就是说，可以完整地将图片显示出来。
缩放	aspectFill	保持纵横比缩放图片，只保证图片的短边能完全显示出来。也就是说，图片通常只在水平或垂直方向是完整的，另一个方向将会发生截取。
缩放	widthFix	宽度不变，高度自动变化，保持原图宽高比不变
裁剪	top	不缩放图片，只显示图片的顶部区域
裁剪	bottom	不缩放图片，只显示图片的底部区域
裁剪	center	不缩放图片，只显示图片的中间区域
裁剪	left	不缩放图片，只显示图片的左边区域
裁剪	right	不缩放图片，只显示图片的右边区域
裁剪	top left	不缩放图片，只显示图片的左上边区域
裁剪	top right	不缩放图片，只显示图片的右上边区域
裁剪	bottom left	不缩放图片，只显示图片的左下边区域
裁剪	bottom right	不缩放图片，只显示图片的右下边区域

示例：

<view class="page">
  <view class="page__hd">
    <text class="page__title">image</text>
    <text class="page__desc">图片</text>
  </view>
  <view class="page__bd">
    <view class="section section_gap" wx:for="{{array}}" wx:for-item="item">
      <view class="section__title">{{item.text}}</view>
      <viewclass="section__ctn">
        <imagestyle="width: 200px; height: 200px; "mode="{{item.mode}}"src="{{src}}"></image>
      </view>
    </view>
  </view>
</view>

Page({
  data: {
    array: [{
      mode: 'scaleToFill',
      text: 'scaleToFill：不保持纵横比缩放图片，使图片完全适应'
    }, {
      mode: 'aspectFit',
      text: 'aspectFit：保持纵横比缩放图片，使图片的长边能完全显示出来'
    }, {
      mode: 'aspectFill',
      text: 'aspectFill：保持纵横比缩放图片，只保证图片的短边能完全显示出来'
    }, {
      mode: 'top',
      text: 'top：不缩放图片，只显示图片的顶部区域'
    }, {
      mode: 'bottom',
      text: 'bottom：不缩放图片，只显示图片的底部区域'
    }, {
      mode: 'center',
      text: 'center：不缩放图片，只显示图片的中间区域'
    }, {
      mode: 'left',
      text: 'left：不缩放图片，只显示图片的左边区域'
    }, {
      mode: 'right',
      text: 'right：不缩放图片，只显示图片的右边边区域'
    }, {
      mode: 'top left',
      text: 'top left：不缩放图片，只显示图片的左上边区域'
    }, {
      mode: 'top right',
      text: 'top right：不缩放图片，只显示图片的右上边区域'
    }, {
      mode: 'bottom left',
      text: 'bottom left：不缩放图片，只显示图片的左下边区域'
    }, {
      mode: 'bottom right',
      text: 'bottom right：不缩放图片，只显示图片的右下边区域'
    }],
    src: '../../resources/cat.jpg'
  },
  imageError: function(e) {
    console.log('image3发生error事件，携带值为', e.detail.errMsg)
  }
})

原图

scaleToFill

wxapp媒体组件 video

video

基础库 1.0.0 开始支持，低版本需做兼容处理。

视频（v2.4.0 起支持同层渲染）。相关api：wx.createVideoContext

属性	类型	默认值	必填	说明	最低版本
src	string		是	要播放视频的资源地址，支持网络路径、本地临时路径、云文件ID（2.3.0）	1.0.0
duration	number		否	指定视频时长	1.1.0
controls	boolean	true	否	是否显示默认播放控件（播放/暂停按钮、播放进度、时间）	1.0.0
danmu-list	Array.<object>		否	弹幕列表	1.0.0
danmu-btn	boolean	false	否	是否显示弹幕按钮，只在初始化时有效，不能动态变更	1.0.0
enable-danmu	boolean	false	否	是否展示弹幕，只在初始化时有效，不能动态变更	1.0.0
autoplay	boolean	false	否	是否自动播放	1.0.0
loop	boolean	false	否	是否循环播放	1.4.0
muted	boolean	false	否	是否静音播放	1.4.0
initial-time	number	0	否	指定视频初始播放位置	1.6.0
page-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势（废弃，见 vslide-gesture）	1.6.0
direction	number		否	设置全屏时视频的方向，不指定则根据宽高比自动判断	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
object-fit	string	contain	否	当视频大小与 video 容器大小不一致时，视频的表现形式	1.0.0
poster	string		否	视频封面的图片网络资源地址或云文件ID（2.3.0）。若 controls 属性值为 false 则设置 poster 无效	1.0.0
show-mute-btn	boolean	false	否	是否显示静音按钮	2.4.0
title	string		否	视频的标题，全屏时在顶部展示	2.4.0
play-btn-position	string	bottom	否	播放按钮的位置	2.4.0
enable-play-gesture	boolean	false	否	是否开启播放手势，即双击切换播放/暂停	2.4.0
auto-pause-if-navigate	boolean	true	否	当跳转到本小程序的其他页面时，是否自动暂停本页面的视频播放	2.5.0
auto-pause-if-open-native	boolean	true	否	当跳转到其它微信原生页面时，是否自动暂停本页面的视频	2.5.0
vslide-gesture	boolean	false	否	在非全屏模式下，是否开启亮度与音量调节手势（同 page-gesture）	2.6.2
vslide-gesture-in-fullscreen	boolean	true	否	在全屏模式下，是否开启亮度与音量调节手势	2.6.2
ad-unit-id	string		是	视频前贴广告单元ID，更多详情可参考开放能力视频前贴广告	2.8.1
poster-for-crawler	string		是	用于给搜索等场景作为视频封面展示，建议使用无播放 icon 的视频封面图，只支持网络地址
show-casting-button	boolean	false	否	显示投屏按钮。只安卓且同层渲染下生效，支持 DLNA 协议	2.10.2
picture-in-picture-mode	string/Array		否	设置小窗模式： push, pop，空字符串或通过数组形式设置多种模式（如： ["push", "pop"]）	2.11.0
picture-in-picture-show-progress	boolean	false	否	是否在小窗模式下显示播放进度	2.11.0
enable-auto-rotation	boolean	false	否	是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效	2.11.0
show-screen-lock-button	boolean	false	否	是否显示锁屏按钮，仅在全屏时显示，锁屏后控制栏的操作	2.11.0
bindplay	eventhandle		否	当开始/继续播放时触发play事件	1.0.0
bindpause	eventhandle		否	当暂停播放时触发 pause 事件	1.0.0
bindended	eventhandle		否	当播放到末尾时触发 ended 事件	1.0.0
bindtimeupdate	eventhandle		否	播放进度变化时触发，event.detail = {currentTime, duration} 。触发频率 250ms 一次	1.0.0
bindfullscreenchange	eventhandle		否	视频进入和退出全屏时触发，event.detail = {fullScreen, direction}，direction 有效值为 vertical 或 horizontal	1.4.0
bindwaiting	eventhandle		否	视频出现缓冲时触发	1.7.0
binderror	eventhandle		否	视频播放出错时触发	1.7.0
bindprogress	eventhandle		否	加载进度变化时触发，只支持一段加载。event.detail = {buffered}，百分比	2.4.0
bindloadedmetadata	eventhandle		否	视频元数据加载完成时触发。event.detail = {width, height, duration}	2.7.0
bindcontrolstoggle	eventhandle		否	切换 controls 显示隐藏时触发。event.detail = {show}	2.9.5
bindenterpictureinpicture	eventhandler		否	播放器进入小窗	2.11.0
bindleavepictureinpicture	eventhandler		否	播放器退出小窗	2.11.0
bindseekcomplete	eventhandler		否	seek 完成时触发	2.12.0

direction 的合法值

值	说明	最低版本
0	正常竖向
90	屏幕逆时针90度
-90	屏幕顺时针90度

object-fit 的合法值

值	说明	最低版本
contain	包含
fill	填充
cover	覆盖

play-btn-position 的合法值

值	说明	最低版本
bottom	controls bar上
center	视频中间

picture-in-picture-mode 的合法值

值	说明	最低版本
[]	取消小窗
push	路由 push 时触发小窗
pop	路由 pop 时触发小窗

提示

1. tip：`video 默认宽度 300px、高度 225px，可通过 wxss 设置宽高。
2. tip：从 2.4.0 起 video 支持同层渲染。

微信小程序媒体组件 camera

camera

---

基础库 1.6.0 开始支持，低版本需做兼容处理。

系统相机。

需要用户授权 scope.camera

属性名	类型	默认值	说明
device-position	String	back	前置或后置，值为front, back
flash	String	auto	闪光灯，值为auto, on, off
bindstop	EventHandle		摄像头在非正常终止时触发，如退出后台等情况
binderror	EventHandle		用户不允许使用摄像头时触发

相关api：wx.createCameraContext

Bug & Tip

1. tip: camera 组件是由客户端创建的原生组件，它的层级是最高的，不能通过 z-index 控制层级。可使用 cover-view cover-image覆盖在上面。
2. tip: 同一页面只能插入一个 camera 组件。
3. tip: 请勿在 scroll-view、swiper、picker-view、movable-view 中使用 camera 组件。

示例：

<!-- camera.wxml -->
<camera device-position="back" flash="off" binderror="error" style="width: 100%; height: 300px;"></camera>
<button type="primary" bindtap="takePhoto">拍照</button>
<view>预览</view>
<image mode="widthFix" src="{{src}}"></image>

// camera.js
Page({
    takePhoto() {
        const ctx = wx.createCameraContext()
        ctx.takePhoto({
            quality: 'high',
            success: (res) => {
                this.setData({
                    src: res.tempImagePath
                })
            }
        })
    },
    error(e) {
        console.log(e.detail)
    }
})

wxapp媒体组件 live-pusher

live-pusher

基础库 1.7.0 开始支持，低版本需做兼容处理。

实时音视频录制（v2.9.1 起支持同层渲染）。需要用户授权 scope.camera、scope.record。

暂只针对国内主体如下类目的小程序开放，需要先通过类目审核，再在小程序管理后台，「开发」-「接口设置」中自助开通该组件权限。

微信小程序媒体组件 live-player

live-player

基础库 1.7.0 开始支持，低版本需做兼容处理。

实时音视频播放（v2.9.1 起支持同层渲染）。

暂只针对国内主体如下类目的小程序开放，需要先通过类目审核，再在小程序管理后台，「开发」-「接口设置」中自助开通该组件权限。

微信小程序媒体组件 void-room

voip-room

基础库 2.11.0 开始支持，低版本需做兼容处理。

多人音视频对话。需用户授权 scope.camera、scope.record。相关接口： wx.joinVoIPChat

暂只针对国内主体如下类目的小程序开放，需要先通过类目审核，再在小程序管理后台，「开发」-「接口设置」中自助开通该组件权限。

微信小程序地图 map

2020-07-24 15:18 更新

基础库 1.0.0 开始支持，低版本需做兼容处理。

地图（v2.7.0 起支持同层渲染）。相关api wx.createMapContext。

个性化地图能力可在小程序后台“开发-开发者工具-腾讯位置服务”申请开通。 小程序内地图组件应使用同一 subkey，可通过 layer-style（地图官网设置的样式 style 编号）属性选择不同的底图风格。 组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

示例小程序

属性	类型	默认值	必填	说明	最低版本
longitude	number		是	中心经度	1.0.0
latitude	number		是	中心纬度	1.0.0
scale	number	16	否	缩放级别，取值范围为3-20	1.0.0
markers	Array.<marker>		否	标记点	1.0.0
covers	Array.<cover>		否	即将移除，请使用 markers	1.0.0
polyline	Array.<polyline>		否	路线	1.0.0
circles	Array.<circle>		否	圆	1.0.0
controls	Array.<control>		否	控件（即将废弃，建议使用 cover-view 代替）	1.0.0
include-points	Array.<point>		否	缩放视野以包含所有给定的坐标点	1.0.0
show-location	boolean	false	否	显示带有方向的当前定位点	1.0.0
polygons	Array.<polygon>		否	多边形	2.3.0
subkey	string		否	个性化地图使用的key	2.3.0
layer-style	number	1	否	个性化地图配置的 style，不支持动态修改
rotate	number	0	否	旋转角度，范围 0 ~ 360, 地图正北和设备 y 轴角度的夹角	2.5.0
skew	number	0	否	倾斜角度，范围 0 ~ 40 , 关于 z 轴的倾角	2.5.0
enable-3D	boolean	false	否	展示3D楼块(工具暂不支持）	2.3.0
show-compass	boolean	false	否	显示指南针	2.3.0
show-scale	boolean	false	否	显示比例尺，工具暂不支持	2.8.0
enable-overlooking	boolean	false	否	开启俯视	2.3.0
enable-zoom	boolean	true	否	是否支持缩放	2.3.0
enable-scroll	boolean	true	否	是否支持拖动	2.3.0
enable-rotate	boolean	false	否	是否支持旋转	2.3.0
enable-satellite	boolean	false	否	是否开启卫星图	2.7.0
enable-traffic	boolean	false	否	是否开启实时路况	2.7.0
setting	object		否	配置项	2.8.2
bindtap	eventhandle		否	点击地图时触发，2.9.0起返回经纬度信息	1.0.0
bindmarkertap	eventhandle		否	点击标记点时触发，e.detail = {markerId}	1.0.0
bindlabeltap	eventhandle		否	点击label时触发，e.detail = {markerId}	2.9.0
bindcontroltap	eventhandle		否	点击控件时触发，e.detail = {controlId}	1.0.0
bindcallouttap	eventhandle		否	点击标记点对应的气泡时触发e.detail = {markerId}	1.2.0
bindupdated	eventhandle		否	在地图渲染更新完成时触发	1.6.0
bindregionchange	eventhandle		否	视野发生变化时触发，	2.3.0
bindpoitap	eventhandle		否	点击地图poi点时触发，e.detail = {name, longitude, latitude}	2.3.0

regionchange 返回值

视野改变时，regionchange 会触发两次，返回的 type 值分别为 begin / end。

2.8.0起 begin 阶段返回 causedBy，有效值为 gesture（手势触发） & update（接口触发）

2.3.0起 end 阶段返回 causedBy，有效值为 drag（拖动导致）、scale（缩放导致）、update（调用更新接口导致） rotate、skew仅在 end 阶段返回

e = {
  causedBy,
  type,
  detail: {
    rotate,
    skew
  }
}

setting

提供 setting 对象统一设置地图配置。同时对于一些动画属性如 rotate 和 skew，通过 setData 分开设置时无法同时生效，需通过 settting 统一修改。

// 默认值
const setting = {
  skew: 0,
  rotate: 0,
  showLocation: false,
  showScale: false,
  subKey: '',
  layerStyle: -1,
  enableZoom: true,
  enableScroll: true,
  enableRotate: false,
  showCompass: false,
  enable3D: false,
  enableOverlooking: false,
  enableSatellite: false,
  enableTraffic: false,
}

this.setData({
  // 仅设置的属性会生效，其它的不受影响
  setting: {
    enable3D: true,
    enableTraffic: true
  }
})

marker

标记点用于在地图上显示标记的位置

属性	说明	类型	必填	备注	最低版本
id	标记点 id	number	否	marker 点击事件回调会返回此 id。建议为每个 marker 设置上 number 类型 id，保证更新 marker 时有更好的性能。
latitude	纬度	number	是	浮点数，范围 -90 ~ 90
longitude	经度	number	是	浮点数，范围 -180 ~ 180
title	标注点名	string	否	点击时显示，callout存在时将被忽略
zIndex	显示层级	number	否		2.3.0
iconPath	显示的图标	string	是	项目目录下的图片路径，支持网络路径、本地路径、代码包路径（2.3.0）
rotate	旋转角度	number	否	顺时针旋转的角度，范围 0 ~ 360，默认为 0
alpha	标注的透明度	number	否	默认 1，无透明，范围 0 ~ 1
width	标注图标宽度	number/string	否	默认为图片实际宽度
height	标注图标高度	number/string	否	默认为图片实际高度
callout	自定义标记点上方的气泡窗口	Object	否	支持的属性见下表，可识别换行符。	1.2.0
label	为标记点旁边增加标签	Object	否	支持的属性见下表，可识别换行符。	1.2.0
anchor	经纬度在标注图标的锚点，默认底边中点	Object	否	{x, y}，x 表示横向(0-1)，y 表示竖向(0-1)。{x: .5, y: 1} 表示底边中点	1.2.0
aria-label	无障碍访问，（属性）元素的额外描述	string	否		2.5.0

marker 上的气泡 callout

属性	说明	类型	最低版本
content	文本	string	1.2.0
color	文本颜色	string	1.2.0
fontSize	文字大小	number	1.2.0
borderRadius	边框圆角	number	1.2.0
borderWidth	边框宽度	number	2.3.0
borderColor	边框颜色	string	2.3.0
bgColor	背景色	string	1.2.0
padding	文本边缘留白	number	1.2.0
display	'BYCLICK':点击显示; 'ALWAYS':常显	string	1.2.0
textAlign	文本对齐方式。有效值: left, right, center	string	1.6.0
anchorX	横向偏移量，向右为正数	number	2.11.0
anchorY	纵向偏移量，向下为正数	number	2.11.0

marker 上的气泡 label

属性	说明	类型	最低版本
content	文本	string	1.2.0
color	文本颜色	string	1.2.0
fontSize	文字大小	number	1.2.0
x	label的坐标（废弃）	number	1.2.0
y	label的坐标（废弃）	number	1.2.0
anchorX	label的坐标，原点是 marker 对应的经纬度	number	2.1.0
anchorY	label的坐标，原点是 marker 对应的经纬度	number	2.1.0
borderWidth	边框宽度	number	1.6.0
borderColor	边框颜色	string	1.6.0
borderRadius	边框圆角	number	1.6.0
bgColor	背景色	string	1.6.0
padding	文本边缘留白	number	1.6.0
textAlign	文本对齐方式。有效值: left, right, center	string	1.6.0

polyline

指定一系列坐标点，从数组第一项连线至最后一项

属性	说明	类型	必填	备注	最低版本
points	经纬度数组	array	是	[{latitude: 0, longitude: 0}]
color	线的颜色	string	否	十六进制
width	线的宽度	number	否
dottedLine	是否虚线	boolean	否	默认 false
arrowLine	带箭头的线	boolean	否	默认 false，开发者工具暂不支持该属性	1.2.0
arrowIconPath	更换箭头图标	string	否	在 arrowLine 为 true 时生效	1.6.0
borderColor	线的边框颜色	string	否		1.2.0
borderWidth	线的厚度	number	否		1.2.0

polygon

指定一系列坐标点，根据 points 坐标数据生成闭合多边形

属性	说明	类型	必填	备注	最低版本
points	经纬度数组	array	是	[{latitude: 0, longitude: 0}]	2.3.0
strokeWidth	描边的宽度	number	否		2.3.0
strokeColor	描边的颜色	string	否	十六进制	2.3.0
fillColor	填充颜色	string	否	十六进制
zIndex	设置多边形Z轴数值	number	否		2.3.0

circle

在地图上显示圆

属性	说明	类型	必填	备注
latitude	纬度	number	是	浮点数，范围 -90 ~ 90
longitude	经度	number	是	浮点数，范围 -180 ~ 180
color	描边的颜色	string	否	十六进制
fillColor	填充颜色	string	否	十六进制
radius	半径	number	是
strokeWidth	描边的宽度	number	否

control

在地图上显示控件，控件不随着地图移动。即将废弃，请使用 cover-view

属性	说明	类型	必填	备注
id	控件id	number	否	在控件点击事件回调会返回此id
position	控件在地图的位置	object	是	控件相对地图位置
iconPath	显示的图标	string	是	项目目录下的图片路径，支持本地路径、代码包路径
clickable	是否可点击	boolean	否	默认不可点击

position

属性	说明	类型	必填	备注
left	距离地图的左边界多远	number	否	默认为0
top	距离地图的上边界多远	number	否	默认为0
width	控件宽度	number	否	默认为图片宽度
height	控件高度	number	否	默认为图片高度

bindregionchange 返回值

属性	说明	类型	备注
type	视野变化开始、结束时触发	string	视野变化开始为begin，结束为end
causedBy	导致视野变化的原因	string	拖动地图导致(drag)、缩放导致(scale)、调用接口导致(update)

Bug & Tip

1. tip：个性化地图暂不支持工具中调试。请先使用微信客户端进行测试。
2. tip：地图中的颜色值color/borderColor/bgColor等需使用6位（8位）十六进制表示，8位时后两位表示alpha值，如：#000000AA
3. tip：地图组件的经纬度必填, 如果不填经纬度则默认值是北京的经纬度。
4. tip: map 组件使用的经纬度是火星坐标系，调用 wx.getLocation 接口需要指定 type 为 gcj02
5. tip：从 2.8.0 起 map 支持同层渲染，更多请参考原生组件使用限制
6. tip：请注意原生组件使用限制。

比例尺

scale	3	4	5	6	7	8	9	10	11
比例	1000km	500km	200km	100km	50km	50km	20km	10km	5km
scale	12	13	14	15	16	17	18	19	20
比例	2km	1km	500m	200m	100m	50m	50m	20m	10m

示例代码

在开发者工具中预览效果

<!-- map.wxml -->
<map id="map" longitude="113.324520" latitude="23.099994" scale="14" controls="{{controls}}" bindcontroltap="controltap" markers="{{markers}}" bindmarkertap="markertap" polyline="{{polyline}}" bindregionchange="regionchange" show-location style="width: 100%; height: 300px;"></map>

// map.js
Page({
  data: {
    markers: [{
      iconPath: "/resources/others.png",
      id: 0,
      latitude: 23.099994,
      longitude: 113.324520,
      width: 50,
      height: 50
    }],
    polyline: [{
      points: [{
        longitude: 113.3245211,
        latitude: 23.10229
      }, {
        longitude: 113.324520,
        latitude: 23.21229
      }],
      color:"#FF0000DD",
      width: 2,
      dottedLine: true
    }],
    controls: [{
      id: 1,
      iconPath: '/resources/location.png',
      position: {
        left: 0,
        top: 300 - 50,
        width: 50,
        height: 50
      },
      clickable: true
    }]
  },
  regionchange(e) {
    console.log(e.type)
  },
  markertap(e) {
    console.log(e.detail.markerId)
  },
  controltap(e) {
    console.log(e.detail.controlId)
  }
})

微信小程序画布 canvas

微信小程序开放数据 open-data

2020-09-01 09:47 更新

基础库 1.4.0 开始支持，低版本需做兼容处理。

用于展示微信开放的数据。

属性	类型	默认值	必填	说明	最低版本
type	string		否	开放数据类型	1.4.0
open-gid	string		否	当 type="groupName" 时生效, 群 id	1.4.0
lang	string	en	否	当 type="user*" 时生效，以哪种语言展示 userInfo	1.4.0
default-text	string		否	数据为空时的默认文案	2.8.1
default-avatar	string		否	用户头像为空时的默认图片，支持相对路径和网络图片路径	2.8.1
binderror	eventhandle		否	群名称或用户信息为空时触发	2.8.1

type 的合法值

值	说明	最低版本
groupName	拉取群名称	1.4.0
userNickName	用户昵称	1.9.90
userAvatarUrl	用户头像	1.9.90
userGender	用户性别	1.9.90
userCity	用户所在城市	1.9.90
userProvince	用户所在省份	1.9.90
userCountry	用户所在国家	1.9.90
userLanguage	用户的语言	1.9.90

lang 的合法值

值	说明	最低版本
en	英文
zh_CN	简体中文
zh_TW	繁体中文

Bug & Tip

1. tip：只有当前用户在此群内才能拉取到群名称
2. tip：关于 open-gid 的获取请使用 wx.getShareInfo

示例代码

<open-data type="groupName" open-gid="xxxxxx"></open-data>
<open-data type="userAvatarUrl"></open-data>
<open-data type="userGender" lang="zh_CN"></open-data>

微信小程序承载网页 web-view

2020-07-28 16:12 更新

web-view

基础库 1.6.4 开始支持，低版本需做兼容处理

web-view 组件是一个可以用来承载网页的容器，会自动铺满整个小程序页面。个人类型与海外类型的小程序暂不支持使用。

属性名	类型	默认值	说明
src	String	none	webview 指向网页的链接。需登录小程序管理后台配置域名白名单。

示例代码：

<!-- wxml -->
<!-- 指向微信公众平台首页的web-view -->
<web-view src="https://mp.weixin.qq.com/" rel="external nofollow" ></web-view>

相关接口 1

<web-view/>网页中可使用JSSDK 1.3.0提供的接口返回小程序页面。 支持的接口有：

接口名	说明	最低版本
wx.miniProgram.navigateTo	参数与小程序接口一致	1.6.4
wx.miniProgram.navigateBack	参数与小程序接口一致	1.6.4
wx.miniProgram.switchTab	参数与小程序接口一致	1.6.5
wx.miniProgram.reLaunch	参数与小程序接口一致	1.6.5
wx.miniProgram.redirectTo	参数与小程序接口一致	1.6.5

示例代码：

<!-- html -->
<script type="text/javascript" src="https://res.wx.qq.com/open/js/jweixin-1.3.0.js" rel="external nofollow" ></script>

// javascript
wx.miniProgram.navigateTo({url: '/path/to/page'})

相关接口 2

<web-view/>网页中仅支持以下JSSDK接口：

接口模块	接口说明	具体接口
判断客户端是否支持js		checkJSApi
图像接口	拍照或上传	chooseImage
	预览图片	previewImage
	上传图片	uploadImage
	下载图片	downloadImage
	获取本地图片	getLocalImgData
音频接口	开始录音	startRecord
	停止录音	stopRecord
	监听录音自动停止	onVoiceRecordEnd
	播放语音	playVoice
	暂停播放	pauseVoice
	停止播放	stopVoice
	监听语音播放完毕	onVoicePlayEnd
	上传接口	uploadVoice
	下载接口	downloadVoice
智能接口	识别音频	translateVoice
设备信息	获取网络状态	getNetworkType
地理位置	使用内置地图	getLocation
	获取地理位置	openLocation
摇一摇周边	开启ibeacon	startSearchBeacons
	关闭ibeacon	stopSearchBeacons
	监听ibeacon	onSearchBeacons
微信扫一扫	调起微信扫一扫	scanQRCode
微信卡券	拉取使用卡券列表	chooseCard
	批量添加卡券接口	addCard
	查看微信卡包的卡券	openCard
长按识别	小程序圆形码	无

相关接口 3

用户分享时可获取当前<web-view/>的URL，即在onShareAppMessage回调中返回webViewUrl参数。

示例代码：

Page({
  onShareAppMessage(options) {
    console.log(options.webViewUrl)
  }
})

相关接口 4

在网页内可通过window.__wxjs_environment变量判断是否在小程序环境。

示例代码：

// web-view下的页面内
wx.ready(function() {
    console.log(window.__wxjs_environment === 'miniprogram') // true
})

Bug & Tip

1. 网页内iframe的域名也需要配置到域名白名单。
2. 开发者工具上，可以在 <web-view/> 组件上通过右键 - 调试，打开 <web-view/> 组件的调试。
3. 每个页面只能有一个<web-view/>，<web-view/>会自动铺满整个页面，并覆盖其他组件。
4. <web-view/>网页与小程序之间不支持除JSSDK提供的接口之外的通信。
5. 在iOS中，若存在JSSDK接口调用无响应的情况，可在<web-view/>的src后面加个#wechat_redirect解决。

微信小程序组件 contact-button（客服会话按钮）

2018-01-03 17:01 更新

contact-button

---

客服会话按钮，用于在页面上显示一个客服会话按钮，用户点击该按钮后会进入客服会话。

属性名	类型	默认值	说明
size	Number	18	会话按钮大小，有效值 18-27，单位：px
type	String	default-dark	会话按钮的样式类型
session-from	String		用户从该按钮进入会话时，开发者将收到带上本参数的事件推送。本参数可用于区分用户进入客服会话的来源。

type 有效值：

值	说明
default-dark
default-light

示例代码

<contact-button
  type="default-light"
  size="20"
  session-from="weapp"
>
</contact-button>

相关api：详见客服消息接口文档

相关组件：button 组件通过设置 open-type="contact" 亦可进入客服会话