小程序开发.微信小程序中的组件.视图容器组件
note:当前本文编辑中… 20220731
目 录
1. 概述
2. view 组件 和 scroll-view 组件
3. movable-view 组件 和 movable-area 组件
4. swiper 和 swiper-item 组件
5. match-media 组件
6. page-container 组件
7. root-portal 组件
视图容器组件用于排版页面与为其他组件提供载体。在微信小程序中提供了如下视图组件:
| 组件 | 描述 | 说明 |
|---|
view | 视图容器。 | 基础库 1.0.0 开始支持。 |
scroll-view | 可滚动 视图容器。 | 基础库 1.0.0 开始支持。 |
movable-view | 可移动的视图容器,在页面中可以拖拽滑动。movable-view必须在 movable-area 组件中,并且必须是直接子节点,否则不能移动。 | 基础库 1.2.0 开始支持。 |
movable-area | movable-view的可移动区域。 | 基础库 1.2.0 开始支持。 |
swiper | 滑块视图容器。其中只可放置swiper-item组件,否则会导致未定义的行为。 | 基础库 1.0.0 开始支持。 |
swiper-item | 仅可放置在swiper组件中,宽高自动设置为100%。 | 基础库 1.0.0 开始支持。 |
page-container | 页面容器。 | 基础库 2.16.0 开始支持。 |
root-portal | 使整个子树从页面中脱离出来,类似于在 CSS 中使用 fixed position 的效果。 | 基础库 1.0.0 开始支持,主要用于制作弹窗、弹出层等。 |
match-media | media query 匹配检测节点。可以指定一组 media query 规则,满足时,这个节点才会被展示。通过这个节点可以实现“页面宽高在某个范围时才展示某个区域”这样的效果。 | 基础库 2.11.1 开始支持。 |
share-element | 共享元素。 | 基础库 2.16.0 开始支持。 |
- view 容器组件在微信小程序中是最基本的容器组件,其就类似于 HTML 中的 div。但是注意,虽然两者各自在不同的体系中发挥着相似的作用,但 view 毕竟不是 div,这体现在 view 和 div 具有不同的属性。比如,在 HTML 中的 div,通过指定属性
contenteditable 的值为 true,就可以让元素可编辑,但是在 微信小程序中的 view,至今没有实现这样的属性。 - scroll-view 组件 为可滚动的视图容器,允许用户通过手指在容器上滑动来改变显示区域。和HTML中使用CSS的
scroll 一样,在平面上可以有 水平 和 垂直 两大可被允许的滚动方向。 - view 组件 和 scroll-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 |
| 属性 | 类型 | 默认值 | 必须 | 说明 | 最低版本 |
|---|
scroll-x | boolean | false | 否 | 允许横向滚动 | 1.0.0 |
scroll-y | boolean | false | 否 | 允许纵向滚动 | 1.0.0 |
upper-threshold | number/string | 50 | 否 | 距顶部/左边多远时,触发 scrolltoupper 事件 | 1.0.0 |
lower-threshold | number/string | 50 | 否 | 距底部/右边多远时,触发 scrolltolower 事件 | 1.0.0 |
scroll-top | number/string | - | 否 | 设置竖向滚动条位置 | 1.0.0 |
scroll-left | number/string | - | 否 | 设置横向滚动条位置 | 1.0.0 |
scroll-into-view | string | - | 否 | 值应为某子元素id(id不能以数字开头)。设置哪个方向可滚动,则在哪个方向滚动到该元素 | 1.0.0 |
scroll-with-animation | boolean | false | 否 | 在设置滚动条位置时使用动画过渡 | 1.0.0 |
enable-back-to-top | boolean | false | 否 | iOS点击顶部状态栏、安卓双击标题栏时,滚动条返回顶部,只支持竖向 | 1.0.0 |
enable-flex | boolean | false | 否 | 启用 flexbox 布局。开启后,当前节点声明了 display: flex 就会成为 flex container,并作用于其孩子节点。 | 2.7.3 |
scroll-anchoring | boolean | false | 否 | 开启 scroll anchoring 特性,即控制滚动位置不随内容变化而抖动,仅在 iOS 下生效,安卓下可参考 CSS overflow-anchor 属性。 | 2.8.2 |
refresher-enabled | boolean | false | 否 | 开启自定义下拉刷新 | 2.10.1 |
refresher-threshold | number | 45 | 否 | 设置自定义下拉刷新阈值 | 2.10.1 |
refresher-default-style | string | "black" | 否 | 设置自定义下拉刷新默认样式,支持设置 black | white | none, none 表示不使用默认样式 | 2.10.1 |
refresher-background | string | "#FFF" | 否 | 设置自定义下拉刷新区域背景颜色 | 2.10.1 |
refresher-triggered | boolean | false | 否 | 设置当前下拉刷新状态,true 表示下拉刷新已经被触发,false 表示下拉刷新未被触发 | 2.10.1 |
enhanced | boolean | false | 否 | 启用 scroll-view 增强特性,启用后可通过 ScrollViewContext 操作 scroll-view | 2.12.0 |
bounces | boolean | true | 否 | iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效) | 2.12.0 |
show-scrollbar | boolean | true | 否 | 滚动条显隐控制 (同时开启 enhanced 属性后生效) | 2.12.0 |
paging-enabled | boolean | false | 否 | 分页滑动效果 (同时开启 enhanced 属性后生效) | 2.12.0 |
fast-deceleration | boolean | false | 否 | 滑动减速速率控制 (同时开启 enhanced 属性后生效) | 2.12.0 |
binddragstart | eventhandle | - | 否 | 滑动开始事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft } | 2.12.0 |
binddragging | eventhandle | - | 否 | 滑动事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft } | 2.12.0 |
binddragend | eventhandle | - | 否 | 滑动结束事件 (同时开启 enhanced 属性后生效) detail { scrollTop, scrollLeft, velocity } | 2.12.0 |
bindscrolltoupper | eventhandle | - | 否 | 滚动到顶部/左边时触发 | 1.0.0 |
bindscrolltolower | eventhandle | - | 否 | 滚动到底部/右边时触发 | 1.0.0 |
bindscroll | eventhandle | - | 否 | 滚动时触发,event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} | 1.0.0 |
bindrefresherpulling | eventhandle | - | 否 | 自定义下拉刷新控件被下拉 | 2.10.1 |
bindrefresherrefresh | eventhandle | - | 否 | 自定义下拉刷新被触发 | 2.10.1 |
bindrefresherrestore | eventhandle | - | 否 | 自定义下拉刷新被复位 | 2.10.1 |
bindrefresherabort | eventhandle | - | 否 | 自定义下拉刷新被中止 | 2.10.1 |
movable-view 组件为可移动的视图容器组件,在页面中可以拖拽滑动;movable-area 组件为movable-view的可移动区域;movable-view 必须在 movable-area 组件中,并且必须是直接子节点,否则不能移动。
| 属性 | 类型 | 默认值 | 必须 | 说明 | 最低版本 |
|---|
direction | string | none | 否 | movable-view的移动方向,属性值有all、vertical、horizontal、none | 1.2.0 |
inertia | boolean | false | 否 | movable-view是否带有惯性 | 1.2.0 |
out-of-bounds | boolean | false | 否 | 超过可移动区域后,movable-view是否还可以移动 | 1.2.0 |
x | number/string | - | 否 | 定义 x 轴方向的偏移,如果 x 的值不在可移动范围内,会自动移动到可移动范围;改变 x 的值会触发动画;单位支持px(默认)、rpx; | 1.2.0 |
y | number/string | - | 否 | 定义 y 轴方向的偏移,如果 y 的值不在可移动范围内,会自动移动到可移动范围;改变 y 的值会触发动画;单位支持px(默认)、rpx; | 1.2.0 |
damping | number | 20 | 否 | 阻尼系数,用于控制 x 或y改变时的动画和过界回弹的动画,值越大移动越快 | 1.2.0 |
friction | number | 2 | 否 | 摩擦系数,用于控制惯性滑动的动画,值越大摩擦力越大,滑动越快停止;必须大于0,否则会被设置成默认值 | 1.2.0 |
disabled | boolean | false | 否 | 是否禁用 | 1.9.90 |
scale | boolean | false | 否 | 是否支持双指缩放,默认缩放手势生效区域是在 movable-view 内 | 1.9.90 |
scale-min | number | 0.5 | 否 | 定义缩放倍数最小值 | 1.9.90 |
scale-max | number | 10 | 否 | 定义缩放倍数最大值 | 1.9.90 |
scale-value | number | 1 | 否 | 定义缩放倍数,取值范围为 0.5 - 10 | 1.9.90 |
animation | boolean | true | 否 | 是否使用动画 | 2.1.0 |
bindscale | eventhandle | - | 否 | 缩放过程中触发的事件,event.detail = {x, y, scale},x和 y 字段在2.1.0之后支持 | 1.9.90 |
htouchmove | eventhandle | - | 否 | 初次手指触摸后移动为横向的移动时触发,如果 catch 此事件,则意味着 touchmove 事件也被catch | 1.9.90 |
vtouchmove | eventhandle | - | 否 | 初次手指触摸后移动为纵向的移动时触发,如果 catch 此事件,则意味着 touchmove 事件也被catch | 1.9.90 |
bindchange | eventhandle | - | 否 | 拖动过程中触发的事件,event.detail = {x, y, source} | 1.9.90 |
其中,bindchange 返回的 source 表示产生移动的原因:
| 值 | 描述 |
|---|
touch | 拖动 |
touch-out-of-bounds | 超出移动范围 |
out-of-bounds | 超出移动范围后的回弹 |
friction | 惯性 |
| 空字符串 | setData |
| 属性 | 类型 | 默认值 | 必须 | 说明 | 最低版本 |
|---|
scale-area | boolean | false | 否 | 当里面的 movable-view 设置为支持双指缩放时,设置此值可将缩放手势生效区域修改为整个 movable-area | 1.9.90 |
- swiper 组件是以一个滑块视图容器,通常用于图片之间的切换播放,也就是 Web 中的 轮播图。在 swiper 组件中只可放置
swiper-item 组件,否则会导致未定义的行为。一个swiper 组件看起来就像这样:

| 属性 | 类型 | 默认值 | 必须 | 说明 | 最低版本 |
|---|
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 |
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 | string | "default" | 否 | 指定 swiper 切换缓动动画类型 | 2.6.5 |
| 属性 | 类型 | 默认值 | 必须 | 说明 | 最低版本 |
|---|
item-id | string | - | 否 | 该 swiper-item 的标识符 | 1.9.0 |
skip-hidden-item-layout | boolean | false | 否 | 是否跳过未显示的滑块布局,设为 true 可优化复杂情况下的滑动性能,但会丢失隐藏状态滑块的布局信息 | 1.9.0 |
- media query 匹配检测节点。可以指定一组 media query 规则,满足时,这个节点才会被展示。
- 通过这个节点可以实现“页面宽高在某个范围时才展示某个区域”这样的效果。
| 属性 | 类型 | 默认值 | 必须 | 说明 | 最低版本 |
|---|
min-width | number | - | 否 | 页面最小宽度( px 为单位) | 2.11.1 |
max-width | number | - | 否 | 页面最大宽度( px 为单位) | 2.11.1 |
width | number | - | 否 | 页面宽度( px 为单位) 2.11.1 | |
min-height | number | - | 否 | 页面最小高度( px 为单位) | 2.11.1 |
max-height | number | - | 否 | 页面最大高度( px 为单位) | 2.11.1 |
height | number | - | 否 | 页面高度( px 为单位) | 2.11.1 |
orientation | string | - | 否 | 屏幕方向( landscape 或 portrait ) | 2.11.1 |
<match-media min-width="300" max-width="600">
<view>当页面宽度在 300 ~ 500 px 之间时展示这里view>
match-media>
<match-media min-height="400" orientation="landscape">
<view>当页面高度不小于 400 px 且屏幕方向为纵向时展示这里view>
match-media>
- 页面容器组件。
- 小程序如果在页面内进行复杂的界面设计(如在页面内弹出半屏的弹窗、在页面内加载一个全屏的子页面等),用户进行返回操作会直接离开当前页面,不符合用户预期,预期应为关闭当前弹出的组件。 为此提供“假页”容器组件,效果类似于 popup 弹出层,页面内存在该容器时,当用户进行返回操作,关闭该容器不关闭页面。返回操作包括三种情形,右滑手势、安卓物理返回键和调用 navigateBack 接口。
- 当前页面最多只有 1 个容器,若已存在容器的情况下,无法增加新的容器
- wx.navigateBack 无法在页面栈顶调用,此时没有上一级页面
| 属性 | 类型 | 默认值 | 必须 | 说明 | 最低版本 |
|---|
show | boolean | false | 否 | 是否显示容器组件 | 2.16.0 |
duration | number | 300 | 否 | 动画时长,单位毫秒 | 2.16.0 |
z-index | number | 100 | 否 | z-index 层级 | 2.16.0 |
overlay | boolean | true | 否 | 是否显示遮罩层 | 2.16.0 |
position | string | bottom | 否 | 弹出位置,可选值为 top bottom right center | 2.16.0 |
round | boolean | false | 否 | 是否显示圆角 | 2.16.0 |
close-on-slideDown | boolean | false | 否 | 是否在下滑一段距离后关闭 | 2.16.0 |
overlay-style | string | - | 否 | 自定义遮罩层样式 | 2.16.0 |
custom-style | string | - | 否 | 自定义弹出层样式 | 2.16.0 |
bind:beforeenter | eventhandle | - | 否 | 进入前触发 | 2.16.0 |
bind:enter | eventhandle | - | 否 | 进入中触发 | 2.16.0 |
bind:afterenter | eventhandle | - | 否 | 进入后触发 | 2.16.0 |
bind:beforeleave | eventhandle | - | 否 | 离开前触发 | 2.16.0 |
bind:leave | eventhandle | - | 否 | 离开中触发 | 2.16.0 |
bind:afterleave | eventhandle | - | 否 | 离开后触发 | 2.16.0 |
bind:clickoverlay | eventhandle | - | 否 | 点击遮罩层时触发 | 2.16.0 |
使整个子树从页面中脱离出来,类似于在 CSS 中使用 fixed position 的效果。主要用于制作弹窗、弹出层等。
例如:
<view class="intro">
<button bindtap="toggle">显示 root-portalbutton>
<root-portal wx:if="{{ show }}">
<view class="portal-content">
root-portal 内容
view>
root-portal>
view>