微信小程序官方组件展示之视图容器scroll-view

软件事业部

修改于 2022-08-15 10:31:41

1.7K0

修改于 2022-08-15 10:31:41

文章被收录于专栏：软件事业部专栏

以下将展示小程序官方组件能力，组件样式仅供参考，开发者可根据自身需求定义组件样式，具体属性参数详见小程序开发文档。

功能描述：

可滚动视图区域。使用竖向滚动时，需要给scroll-view一个固定高度，通过 WXSS 设置 height。组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

属性说明：

WebView

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

Skyline

组件差异

1. 默认只会渲染在屏节点，会根据直接子节点是否在屏来按需渲染，若只有一个直接子节点则性能会退化

2. 横向滚动需打开 enable-flex 以兼容 WebView，如 <scroll-view scroll-x enable-flex style="flex-direction: row;"/>

3. 滚动条的长度是预估的，若直接子节点的高度差别较大，则滚动条长度可能会不准确

属性	说明
type	新增必填属性且目前只有 list 选项；后续计划提供 type=custom 等更多列表特性
enable-back-to-top	暂未支持
enable-flex	不支持，默认 flex
scroll-anchoring	暂未支持
enhanced	不支持，默认开启
paging-enabled	不支持，可用 Skyline 手势系统实现

Bug & Tip

1. tip: 基础库 2.4.0以下不支持嵌套textarea、map、canvas、video 组件

2. tip: scroll-into-view 的优先级高于 scroll-top

3. tip: 在滚动 scroll-view 时会阻止页面回弹，所以在 scroll-view 中滚动，是无法触发 onPullDownRefresh

4. tip: 若要使用下拉刷新，请使用页面的滚动，而不是 scroll-view ，这样也能通过点击顶部状态栏回到页面顶部

5. tip: scroll-view 自定义下拉刷新可以结合 WXS 事件响应开发交互动画

示例代码：

JAVASCRIPT

const order = ['demo1', 'demo2', 'demo3']
Page({
 onShareAppMessage() {
 return {
 title: 'scroll-view',
 path: 'page/component/pages/scroll-view/scroll-view'
 }
 },
 data: {
 toView: 'green'
 },
 upper(e) {
 console.log(e)
 },
 lower(e) {
 console.log(e)
 },
 scroll(e) {
 console.log(e)
 },
 scrollToTop() {
 this.setAction({
 scrollTop: 0
 })
 },
 tap() {
 for (let i = 0; i < order.length; ++i) {
 if (order[i] === this.data.toView) {
 this.setData({
 toView: order[i + 1],
 scrollTop: (i + 1) * 200
 })
 break
 }
 }
 },
 tapMove() {
 this.setData({
 scrollTop: this.data.scrollTop + 10
 })
 }
})

WXML：

<view class="container">
 <view class="page-body">
 <view class="page-section">
 <view class="page-section-title">
 <text>Vertical Scroll\n纵向滚动</text>
 </view>
 <view class="page-section-spacing">
 <scroll-view scroll-y="true" style="height: 300rpx;" bindscrolltoupper="upper" bindscrolltolower="lower" bindscroll="scroll" scroll-into-view="{{toView}}" scroll-top="{{scrollTop}}">
 <view id="demo1" class="scroll-view-item demo-text-1"></view>
 <view id="demo2" class="scroll-view-item demo-text-2"></view>
 <view id="demo3" class="scroll-view-item demo-text-3"></view>
 </scroll-view>
 </view>
 </view>
 <view class="page-section">
 <view class="page-section-title">
 <text>Horizontal Scroll\n横向滚动</text>
 </view>
 <view class="page-section-spacing">
 <scroll-view class="scroll-view_H" scroll-x="true" bindscroll="scroll" style="width: 100%">
 <view id="demo1" class="scroll-view-item_H demo-text-1"></view>
 <view id="demo2" class="scroll-view-item_H demo-text-2"></view>
 <view id="demo3" class="scroll-view-item_H demo-text-3"></view>
 </scroll-view>
 </view>
 </view>
 </view>
</view>

WXSS：

.page-section-spacing{
 margin-top: 60rpx;
}
.scroll-view_H{
 white-space: nowrap;
}
.scroll-view-item{
 height: 300rpx;
}
.scroll-view-item_H{
 display: inline-block;
 width: 100%;
 height: 300rpx;
}