简体中文
组件类型:UniScrollViewElement
可滚动视图容器
Android | iOS | web |
---|---|---|
3.9 | 4.11 | 4.0 |
名称 | 类型 | 默认值 | 描述 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | string | - | 渲染模式,可取值 nested | ||||||||||
| |||||||||||||
direction | string | "vertical" | 滚动方向,可取值 none、all、horizontal、vertical,默认值vertical | ||||||||||
| |||||||||||||
boolean | false | 允许横向滚动,不支持同时设置scroll-y属性为true,同时设置true时scroll-y生效。已废弃,请改用direction | |||||||||||
boolean | true | 允许纵向滚动,不支持同时设置scroll-x属性为true,同时设置true时scroll-y生效。已废弃,请改用direction | |||||||||||
boolean | true | 控制是否回弹效果。已废弃,请改用bounces | |||||||||||
associative-container | string | "" | 关联的滚动容器 | ||||||||||
| |||||||||||||
enable-back-to-top | boolean | false | iOS点击顶部状态栏滚动条返回顶部,只支持竖向 | ||||||||||
bounces | boolean | true | 控制是否回弹效果 优先级高于rebound | ||||||||||
upper-threshold | number | 50 | 距顶部/左边多远时(单位px),触发 scrolltoupper 事件 | ||||||||||
lower-threshold | number | 50 | 距底部/右边多远时(单位px),触发 scrolltolower 事件 | ||||||||||
scroll-top | number | 0 | 设置竖向滚动条位置 | ||||||||||
scroll-left | number | 0 | 设置横向滚动条位置 | ||||||||||
scroll-into-view | string(string.IDString) | - | 值应为某子元素id(id不能以数字开头)。设置哪个方向可滚动,则在哪个方向滚动到该元素起始位置 | ||||||||||
scroll-with-animation | boolean | false | 是否在设置滚动条位置时使用滚动动画,设置false没有滚动动画 | ||||||||||
refresher-enabled | boolean | false | 开启下拉刷新,暂时不支持scroll-x = true横向刷新 | ||||||||||
refresher-threshold | number | 45 | 设置下拉刷新阈值 | ||||||||||
refresher-max-drag-distance | number | - | 设置下拉最大拖拽距离(单位px),默认是下拉刷新控件高度的2.5倍 | ||||||||||
refresher-default-style | string | "black" | 设置下拉刷新默认样式,支持设置 black | white | none, none 表示不使用默认样式 | ||||||||||
| |||||||||||||
refresher-background | string(string.ColorString) | "transparent" | 设置下拉刷新区域背景颜色,默认透明 | ||||||||||
refresher-triggered | boolean | false | 设置当前下拉刷新状态,true 表示下拉刷新已经被触发,false 表示下拉刷新未被触发 | ||||||||||
show-scrollbar | boolean | true | 控制是否出现滚动条 | ||||||||||
custom-nested-scroll | boolean | false | 子元素是否开启嵌套滚动 将滚动事件与父元素协商处理 | ||||||||||
nested-scroll-child | string(string.IDString) | "" | 嵌套滚动子元素的id属性,不支持ref,scroll-view惯性滚动时会让对应id元素视图进行滚动,子元素滚动时会触发scroll-view的nestedprescroll事件,嵌套子元素需要设置custom-nested-scroll = true | ||||||||||
@refresherpulling | (event: UniRefresherEvent) => void | - | 下拉刷新控件被下拉 | ||||||||||
@refresherrefresh | (event: UniRefresherEvent) => void | - | 下拉刷新被触发 | ||||||||||
@refresherrestore | (event: UniRefresherEvent) => void | - | 下拉刷新被复位 | ||||||||||
@refresherabort | (event: UniRefresherEvent) => void | - | 下拉刷新被中止 | ||||||||||
@scrolltoupper | (event: UniScrollToUpperEvent) => void | - | 滚动到顶部/左边,会触发 scrolltoupper 事件 | ||||||||||
@scrolltolower | (event: UniScrollToLowerEvent) => void | - | 滚动到底部/右边,会触发 scrolltolower 事件 | ||||||||||
@scroll | (event: UniScrollEvent) => void | - | 滚动时触发,event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} | ||||||||||
@scrollend | (event: UniScrollEvent) => void | - | 滚动结束时触发,event.detail = {scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY} | ||||||||||
@startnestedscroll | (event: UniStartNestedScrollEvent) => Boolean | - | 子元素开始滚动时触发, return ture表示与子元素开启滚动协商 默认return false! event = {node} | ||||||||||
@nestedprescroll | (event: UniNestedPreScrollEvent) => void | - | 子元素滚动时触发,可执行event.consumed(x,y)告知子元素deltaX、deltaY各消耗多少。子元素将执行差值后的deltaX、deltaY滚动距离。不执行consumed(x,y)则表示父元素不消耗deltaX、deltaY。event = {deltaX, deltaY} | ||||||||||
@stopnestedscroll | (event: UniStopNestedScrollEvent) => void | - | 子元素滚动结束或意外终止时触发 |
Android | iOS | web | |
---|---|---|---|
nested | 4.11 | 4.11 | x |
Android | iOS | web | |
---|---|---|---|
none | 4.0 | 4.11 | 4.0 |
all | x | x | 4.0 |
horizontal | 4.0 | 4.11 | 4.0 |
vertical | 4.0 | 4.11 | 4.0 |
Android | iOS | web | |
---|---|---|---|
nested-scroll-view | 4.11 | 4.11 | x |
Android | iOS | web | |
---|---|---|---|
black | 3.9 | 4.11 | - |
white | 3.9 | 4.11 | - |
none | 3.9 | 4.11 | - |
名称 | 类型 | 必填 | 默认值 | 描述 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
detail | UniRefresherEventDetail | 是 | - | - | ||||||||||
| ||||||||||||||
bubbles | boolean | 是 | - | 是否冒泡 | ||||||||||
cancelable | boolean | 是 | - | 是否可以取消 | ||||||||||
type | string | 是 | - | 事件类型 | ||||||||||
target | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | ||||||||||
currentTarget | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | ||||||||||
timeStamp | number | 是 | - | 事件发生时的时间戳 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
stopPropagation | () => void | 是 | - | 阻止当前事件的进一步传播 |
preventDefault | () => void | 是 | - | 阻止当前事件的默认行为 |
名称 | 类型 | 必填 | 默认值 | 描述 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
detail | UniScrollToUpperEventDetail | 是 | - | |||||||||||
| ||||||||||||||
bubbles | boolean | 是 | - | 是否冒泡 | ||||||||||
cancelable | boolean | 是 | - | 是否可以取消 | ||||||||||
type | string | 是 | - | 事件类型 | ||||||||||
target | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | ||||||||||
currentTarget | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | ||||||||||
timeStamp | number | 是 | - | 事件发生时的时间戳 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
stopPropagation | () => void | 是 | - | 阻止当前事件的进一步传播 |
preventDefault | () => void | 是 | - | 阻止当前事件的默认行为 |
名称 | 类型 | 必填 | 默认值 | 描述 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
detail | UniScrollToLowerEventDetail | 是 | - | |||||||||||
| ||||||||||||||
bubbles | boolean | 是 | - | 是否冒泡 | ||||||||||
cancelable | boolean | 是 | - | 是否可以取消 | ||||||||||
type | string | 是 | - | 事件类型 | ||||||||||
target | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | ||||||||||
currentTarget | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | ||||||||||
timeStamp | number | 是 | - | 事件发生时的时间戳 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
stopPropagation | () => void | 是 | - | 阻止当前事件的进一步传播 |
preventDefault | () => void | 是 | - | 阻止当前事件的默认行为 |
名称 | 类型 | 必填 | 默认值 | 描述 | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
detail | UniScrollEventDetail | 是 | - | ||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
bubbles | boolean | 是 | - | 是否冒泡 | |||||||||||||||||||||||||||||||||||
cancelable | boolean | 是 | - | 是否可以取消 | |||||||||||||||||||||||||||||||||||
type | string | 是 | - | 事件类型 | |||||||||||||||||||||||||||||||||||
target | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | |||||||||||||||||||||||||||||||||||
currentTarget | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 | |||||||||||||||||||||||||||||||||||
timeStamp | number | 是 | - | 事件发生时的时间戳 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
stopPropagation | () => void | 是 | - | 阻止当前事件的进一步传播 |
preventDefault | () => void | 是 | - | 阻止当前事件的默认行为 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
node | UniElement | 是 | - | 开始滚动子节点对象 |
isTouch | boolean | 是 | - | 是否由触摸行为发生的Event |
bubbles | boolean | 是 | - | 是否冒泡 |
cancelable | boolean | 是 | - | 是否可以取消 |
type | string | 是 | - | 事件类型 |
target | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 |
currentTarget | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 |
timeStamp | number | 是 | - | 事件发生时的时间戳 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
stopPropagation | () => void | 是 | - | 阻止当前事件的进一步传播 |
preventDefault | () => void | 是 | - | 阻止当前事件的默认行为 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
deltaX | number | 是 | - | x轴滚动距离 |
deltaY | number | 是 | - | y轴滚动距离 |
isTouch | boolean | 是 | - | 是否由触摸行为发生的Event |
bubbles | boolean | 是 | - | 是否冒泡 |
cancelable | boolean | 是 | - | 是否可以取消 |
type | string | 是 | - | 事件类型 |
target | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 |
currentTarget | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 |
timeStamp | number | 是 | - | 事件发生时的时间戳 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
consumed | (consumedX: number, consumedY: number) => void | 是 | - | 通知到子节点x,y轴滚动距离的消耗 |
stopPropagation | () => void | 是 | - | 阻止当前事件的进一步传播 |
preventDefault | () => void | 是 | - | 阻止当前事件的默认行为 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
isTouch | boolean | 是 | - | 是否由触摸行为发生的Event |
bubbles | boolean | 是 | - | 是否冒泡 |
cancelable | boolean | 是 | - | 是否可以取消 |
type | string | 是 | - | 事件类型 |
target | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 |
currentTarget | UniElement | null | 否 | - | UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。 |
timeStamp | number | 是 | - | 事件发生时的时间戳 |
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
stopPropagation | () => void | 是 | - | 阻止当前事件的进一步传播 |
preventDefault | () => void | 是 | - | 阻止当前事件的默认行为 |
refresher-default-style
属性为 none 不使用默认样式注意: 目前自定义下拉刷新元素不支持放在scroll-view的首个子元素位置上。可能无法正常显示
<scroll-view refresher-default-style="none" :refresher-enabled="true" :refresher-triggered="refresherTriggered"
@refresherpulling="onRefresherpulling" @refresherrefresh="onRefresherrefresh"
@refresherrestore="onRefresherrestore" style="flex:1" >
<view v-for="i in 20" class="content-item">
<text class="text">item-{{i}}</text>
</view>
<!-- 自定义下拉刷新元素 -->
<view slot="refresher" class="refresh-box">
<text class="tip-text">{{text[state]}}</text>
</view>
</scroll-view>
具体代码请参考:自定义下拉刷新样式示例
当存在两个 scroll-view 相互嵌套的场景时,两者滚动存在冲突不能很丝滑的进行衔接,可将外层 scroll-view 改成嵌套模式,这样可以让两个 scroll-view 的滚动衔接起来。
<scroll-view style="flex:1" type="nested">
<nested-scroll-header>
<view style="height: 200px;background-color: #66ccff;align-items: center;justify-content: center;">
<text>nested-scroll-header</text>
</view>
</nested-scroll-header>
<nested-scroll-body>
<view style="flex:1">
<scroll-view style="flex:1" associative-container="nested-scroll-view">
<view v-for="index in 20" style="background-color: aliceblue; height: 80px;justify-content: center;">
<text style="color: black;">{{index}}</text>
</view>
</scroll-view>
</view>
</nested-scroll-body>
</scroll-view>
开启嵌套模式设置如下:
associative-container
属性为 "nested-scroll-view",开启内层 scroll-view 支持与外层 scroll-view 嵌套滚动嵌套滚动策略:
当向下滚动时,先滚动外层 scroll-view 再滚动内层 scroll-view;当向上滚动时,先滚动内层 scroll-view 再滚动外层 scroll-view
注意事项:
nested-scroll-header
和nested-scroll-body
和自定义 refreshernested-scroll-body
nested-scroll-header
和 nested-scroll-body
只能有一个子节点nested-scroll-header
只能渲染在 nested-scroll-body
上面nested-scroll-header
和 nested-scroll-body
优先级高于nested-scroll嵌套滚动协商具体代码请参考:嵌套模式示例
嵌套滚动是原生才有的概念,web没有。
它是指父子2个滚动容器嵌套,在滚动时可以互相协商,控制父容器怎么滚、子容器怎么滚。
custom-nested-scroll = true
,开启与父组件实现嵌套滚动协商。仅list-view、scroll-view组件支持与父组件嵌套滚动协商。下面的示例代码,在一个scroll-view中嵌套了一个list-view。在list-view上设置了custom-nested-scroll="true"。
<scroll-view style="height: 100%;" scroll-y="true" rebound ="false" nested-scroll-child="listview" @startnestedscroll="onStartNestedScroll" @nestedprescroll="onNestedPreScroll"
@stopnestedscroll="onStopNestedScroll">
...
<view style="height: 100px;">停靠视图</view>
<list-view id="listview" class="child-scroll" scroll-y="true" custom-nested-scroll="true">
...
</list-view>
</scroll-view>
startnestedscroll
事件。父组件响应startnestedscroll
事件return ture则表示与子组件建立嵌套滚动协商。onStartNestedScroll(event: StartNestedScrollEvent): Boolean {
//开启与子组件建立嵌套滚动协商
return true
}
nestedprescroll
事件,这个事件的含义是嵌套滚动即将发生。
事件中会返回NestedPreScrollEvent子组件将要滚动的数据。nestedprescroll
事件deltaX、deltaY各消耗多少,即父组件要消费掉多少滚动距离。
子组件将执行差值后的deltaX、deltaY滚动距离,也就是剩余的滚动余量留给子组件。onNestedPreScroll(event: NestedPreScrollEvent) {
var deltaY = event.deltaY
var deltaX = event.deltaX
...
if() {
//告知子组件deltaX、deltaY各消耗多少
event.consumed(x, y)
}
}
nested-scroll-child
后,父组件惯性滚动时会让nested-scroll-child
配置的子元素进行滚动。从而触发nestedprescroll
协商处理滚动事件stopnestedscroll
事件注意:
nested-scroll-header
和 nested-scroll-body
不兼容,scroll-view 设置嵌套模式后,嵌套滚动手势协商相关事件将不会触发具体代码请参考:nested-scroll嵌套滚动示例
Android | iOS | web | |
---|---|---|---|
type | 4.11 | 4.11 | x |
direction | 4.0 | 4.11 | 4.0 |
3.9 | x | 4.0 | |
3.9 | x | 4.0 | |
3.9 | x | - | |
associative-container | 4.11 | 4.11 | x |
enable-back-to-top | x | 4.11 | x |
bounces | 4.0 | 4.11 | x |
upper-threshold | 3.9 | 4.11 | 4.0 |
lower-threshold | 3.9 | 4.11 | 4.0 |
scroll-top | 3.9 | 4.11 | 4.0 |
scroll-left | 3.9 | 4.11 | 4.0 |
scroll-into-view | 3.9 | 4.11 | 4.0 |
scroll-with-animation | 3.9 | 4.11 | 4.0 |
refresher-enabled | 3.9 | 4.11 | x |
refresher-threshold | 3.9 | 4.11 | x |
refresher-max-drag-distance | 3.9 | 4.11 | x |
refresher-default-style | 3.9 | 4.11 | x |
refresher-background | 3.9 | 4.11 | x |
refresher-triggered | 3.9 | 4.11 | x |
show-scrollbar | 3.9 | 4.11 | 4.0 |
custom-nested-scroll | 3.9 | x | x |
nested-scroll-child | 3.97 | x | x |
@refresherpulling | 3.9 | 4.11 | x |
@refresherrefresh | 3.9 | 4.11 | x |
@refresherrestore | 3.9 | 4.11 | x |
@refresherabort | 3.9 | 4.11 | x |
@scrolltoupper | 3.9 | 4.11 | 4.0 |
@scrolltolower | 3.9 | 4.11 | 4.0 |
@scroll | 3.9 | 4.11 | 4.0 |
@scrollend | 3.9 | 4.11 | 4.0 |
@startnestedscroll | 3.9 | x | x |
@nestedprescroll | 3.9 | x | x |
@stopnestedscroll | 3.9 | x | x |
Template
Script
<template>
<!-- #ifdef APP -->
<scroll-view class="page-scroll-view">
<!-- #endif -->
<view>
<page-head title="scroll-view,区域滚动视图"></page-head>
<view class="uni-padding-wrap uni-common-mt">
<view class="uni-title uni-common-mt">
<text class="uni-title-text">Vertical Scroll</text>
<text class="uni-subtitle-text">纵向滚动</text>
</view>
<view>
<scroll-view :scroll-top="scrollTop" direction="vertical" class="scroll-Y" scroll-with-animation="true"
@scrolltoupper="upper" @scrolltolower="lower" @scroll="scroll" :show-scrollbar="showScrollbar">
<view class="scroll-view-item uni-bg-red"><text class="text">A</text></view>
<view class="scroll-view-item uni-bg-green"><text class="text">B</text></view>
<view class="scroll-view-item uni-bg-blue"><text class="text">C</text></view>
</scroll-view>
</view>
<view @tap="goTop" class="uni-center uni-common-mt">
<text class="uni-link">点击这里返回顶部</text>
</view>
<view class="uni-title uni-common-mt">
<text class="uni-title-text">Horizontal Scroll</text>
<text class="uni-subtitle-text">横向滚动</text>
</view>
<view>
<scroll-view class="scroll-view_H" direction="horizontal" @scroll="scroll" :scroll-left="120" :show-scrollbar="showScrollbar">
<view class="scroll-view-item_H uni-bg-red"><text class="text">A</text></view>
<view class="scroll-view-item_H uni-bg-green"><text class="text">B</text></view>
<view class="scroll-view-item_H uni-bg-blue"><text class="text">C</text></view>
</scroll-view>
</view>
<navigator url="/pages/component/scroll-view/scroll-view-props" hover-class="none">
<button type="primary" class="button">
非下拉刷新的属性示例
</button>
</navigator>
<view class="uni-common-pb"></view>
<!-- #ifdef APP -->
<navigator url="/pages/component/scroll-view/scroll-view-refresher-props" hover-class="none">
<button type="primary" class="button">
下拉刷新的属性示例
</button>
</navigator>
<view class="uni-common-pb"></view>
<navigator url="/pages/component/scroll-view/scroll-view-refresher" hover-class="none">
<button type="primary" class="button"> 默认下拉刷新示例 </button>
</navigator>
<view class="uni-common-pb"></view>
<navigator url="/pages/component/scroll-view/scroll-view-custom-refresher-props" hover-class="none">
<button type="primary" class="button">
自定义下拉刷新示例
</button>
</navigator>
<view class="uni-common-pb"></view>
<!-- #endif -->
</view>
</view>
<!-- #ifdef APP -->
</scroll-view>
<!-- #endif -->
</template>
<style>
.scroll-Y {
height: 150px;
}
.scroll-view_H {
width: 100%;
flex-direction: row;
}
.scroll-view-item {
height: 150px;
justify-content: center;
align-items: center;
}
.scroll-view-item_H {
width: 100%;
height: 150px;
justify-content: center;
align-items: center;
}
.text {
font-size: 18px;
color: #ffffff;
}
.button {
margin-top: 15px;
}
</style>