低代码高性能原生UI框架

Appearance

本页导读

Scroll 滚动列表 ​

组件类型：UxScrollComponentPublicInstance

滚动列表

平台兼容性 ​

AndroidiOSweb鸿蒙 Next小程序
√√√xx

Slots ​

name描述
default默认插槽
refresherrefresher插槽
loadmoreloadmore插槽
backtopbacktop插槽

Props ​

属性名类型默认值说明
typeString-渲染模式 可选值 nested
directionStringvertical滚动方向
associativeContainerString-关联的滚动容器 可选值 nested-scroll-view
enableBackToTopBooleanfalseiOS点击顶部状态栏滚动条返回顶部，只支持竖向
bouncesBooleantrue控制是否回弹效果
upperThresholdNumber50距顶部/左边多远时（单位px），触发 scrolltoupper 事件
lowerThresholdNumber50距底部/右边多远时（单位px），触发 scrolltolower 事件
scrollTopNumber0设置竖向滚动条位置
scrollLeftNumber0设置横向滚动条位置
scrollIntoViewString-值应为某子元素id（id不能以数字开头）。设置哪个方向可滚动，则在哪个方向滚动到该元素
scrollWithAnimationBooleantrue是否在设置滚动条位置时使用滚动动画，设置false没有滚动动画
refresherEnabledBooleanfalse开启下拉刷新
refresherThresholdNumber45设置下拉刷新阈值
refresherMaxDragDistanceNumber80设置下拉最大拖拽距离（单位px）
refresherBackgroundString'#ffffff'设置下拉刷新区域背景颜色
refresherTriggeredBooleanfalse设置当前下拉刷新状态，true 表示下拉刷新已经被触发，false 表示下拉刷新未被触发
refresherStatesString[]-下拉刷新状态文案
loadmoreEnabledBooleanfalse开启上拉加载
loadmoreStatesString[]-上拉加载状态文案
showScrollbarBooleantrue控制是否出现滚动条
customNestedScrollBooleanfalse子元素是否开启嵌套滚动 将滚动事件与父元素协商处理
openStartnestedscrollBooleanfalse与子元素开启滚动协商
nestedScrollChildString-嵌套滚动子元素的id属性，不支持ref，scroll-view惯性滚动时会让对应id元素视图进行滚动，子元素滚动时会触发scroll-view的nestedprescroll事件，嵌套子元素需要设置custom-nested-scroll = true
backtopBooleanfalse显示返回顶部
placeholderBooleanfalse底部导航栏高度占位
backgroundString'#FFFFFF'背景颜色

direction ​

值说明
none无
all全部
horizontal水平
vertical垂直

Events ​

事件名称说明回调参数
refresherpulling下拉刷新控件被下拉RefresherEvent
refresherrefresh下拉刷新被触发RefresherEvent
refresherrestore下拉刷新被复位RefresherEvent
refresherabort下拉刷新被中止RefresherEvent
loadmore上拉加载触发ScrollToLowerEvent
scrolltoupper滚动到顶部/左边，会触发 scrolltoupper 事件ScrollToUpperEvent
scrolltolower滚动到底部/右边，会触发 scrolltolower 事件ScrollToLowerEvent
scroll滚动时触发ScrollEvent
startnestedscroll子元素开始滚动时触发, return ture表示与子元素开启滚动协商 默认return falseStartNestedScrollEvent
nestedprescroll子元素滚动时触发，可执行event.consumed(x,y)告知子元素deltaX、deltaY各消耗多少。子元素将执行差值后的deltaX、deltaY滚动距离。不执行consumed(x,y)则表示父元素不消耗deltaX、deltaYNestedPreScrollEvent
stopnestedscroll子元素滚动结束或意外终止时触发Event

示例代码 ​

html
<template>
	<ux-page>
		<ux-navbar :title="title" :border="false"></ux-navbar>
		
		<ux-scroll
			ref="uxScrollRef"
			:refresherEnabled="true" 
			:refresherTriggered="refresherTriggered" 
			:loadmoreEnabled="loadmoreEnabled" 
			:backtop="true"
			@refresherrefresh="onRefresh"
			@loadmore="onLoadmore">
			
			<ux-card direction="column" icon="flag" title="Scroll列表" :bold="true">
				<ux-text text="扩展支持自定义下拉刷新、上拉加载自定义样式，可显示返回顶部按钮"></ux-text>
				<ux-row :flex="true" align="top" :mt="5">
					<ux-text text="详细文档："></ux-text>
					<ux-text style="flex: 1" name="Scroll列表" text="https://www.uxframe.cn/component/layout/scroll.html" mode="link"></ux-text>
				</ux-row>
			</ux-card>
			
			<ux-card v-for="(item, index) in list" :key="index">
				<ux-row :flex="true">
					<ux-image :radius="5" :src="item['cover']"></ux-image>
					<ux-col :ml="10">
						<ux-text :bold="true" :size="15" :text="item['author_name']"></ux-text>
						<ux-text :text="item['title']"></ux-text>
						<ux-text :text="item['published_at']"></ux-text>
					</ux-col>
				</ux-row>
			</ux-card>
		</ux-scroll>
	</ux-page>
</template>
<template>
	<ux-page>
		<ux-navbar :title="title" :border="false"></ux-navbar>
		
		<ux-scroll
			ref="uxScrollRef"
			:refresherEnabled="true" 
			:refresherTriggered="refresherTriggered" 
			:loadmoreEnabled="loadmoreEnabled" 
			:backtop="true"
			@refresherrefresh="onRefresh"
			@loadmore="onLoadmore">
			
			<ux-card direction="column" icon="flag" title="Scroll列表" :bold="true">
				<ux-text text="扩展支持自定义下拉刷新、上拉加载自定义样式，可显示返回顶部按钮"></ux-text>
				<ux-row :flex="true" align="top" :mt="5">
					<ux-text text="详细文档："></ux-text>
					<ux-text style="flex: 1" name="Scroll列表" text="https://www.uxframe.cn/component/layout/scroll.html" mode="link"></ux-text>
				</ux-row>
			</ux-card>
			
			<ux-card v-for="(item, index) in list" :key="index">
				<ux-row :flex="true">
					<ux-image :radius="5" :src="item['cover']"></ux-image>
					<ux-col :ml="10">
						<ux-text :bold="true" :size="15" :text="item['author_name']"></ux-text>
						<ux-text :text="item['title']"></ux-text>
						<ux-text :text="item['published_at']"></ux-text>
					</ux-col>
				</ux-row>
			</ux-card>
		</ux-scroll>
	</ux-page>
</template>
ts
<script setup>
	
	let title = ''
	const list = ref<UTSJSONObject[]>([] as UTSJSONObject[])
	const refresherTriggered = ref(false)
	const lastPage = ref(false)
	
	const uxScrollRef = ref<UxScrollComponentPublicInstance | null>(null)
	
	const loadmoreEnabled = computed((): boolean => {
		return list.value.length >= 10
	})
	
	function getList(refresh: boolean) {
		if(refresh) {
			lastPage.value = false
			refresherTriggered.value = true
		}
		
		if(list.value.length == 0) {
			uni.showLoading({
				title: 'loading...'
			})
		}
		
		uni.request<UTSJSONObject[]>({
			url: 'https://unidemo.dcloud.net.cn/api/news?column=title,author_name,cover,published_at',
			method:"GET",
			success: (res: RequestSuccess<UTSJSONObject[]>) => {
				if (res.statusCode == 200) {
					const result = res.data
					
					if(result != null){
						if(refresh) {
							list.value = result
						} else {
							if(list.value.length > 50) {
								lastPage.value = true
							} else {
								list.value = list.value.concat(result)
							}
						}
					}
				}
			},
			complete:() => {
				uni.hideLoading()
				
				if(refresh) {
					refresherTriggered.value = false
				}
				
				uxScrollRef.value!.loadSuccess(lastPage.value)
			}
		});
	}
	
	function onRefresh() {
		getList(true)
	}
	
	function onLoadmore() {
		getList(false)
	}
	
	onLoad((e: OnLoadOptions) => {
		title = e['title'] ?? ''
		
		getList(false)
	})
</script>
<script setup>
	
	let title = ''
	const list = ref<UTSJSONObject[]>([] as UTSJSONObject[])
	const refresherTriggered = ref(false)
	const lastPage = ref(false)
	
	const uxScrollRef = ref<UxScrollComponentPublicInstance | null>(null)
	
	const loadmoreEnabled = computed((): boolean => {
		return list.value.length >= 10
	})
	
	function getList(refresh: boolean) {
		if(refresh) {
			lastPage.value = false
			refresherTriggered.value = true
		}
		
		if(list.value.length == 0) {
			uni.showLoading({
				title: 'loading...'
			})
		}
		
		uni.request<UTSJSONObject[]>({
			url: 'https://unidemo.dcloud.net.cn/api/news?column=title,author_name,cover,published_at',
			method:"GET",
			success: (res: RequestSuccess<UTSJSONObject[]>) => {
				if (res.statusCode == 200) {
					const result = res.data
					
					if(result != null){
						if(refresh) {
							list.value = result
						} else {
							if(list.value.length > 50) {
								lastPage.value = true
							} else {
								list.value = list.value.concat(result)
							}
						}
					}
				}
			},
			complete:() => {
				uni.hideLoading()
				
				if(refresh) {
					refresherTriggered.value = false
				}
				
				uxScrollRef.value!.loadSuccess(lastPage.value)
			}
		});
	}
	
	function onRefresh() {
		getList(true)
	}
	
	function onLoadmore() {
		getList(false)
	}
	
	onLoad((e: OnLoadOptions) => {
		title = e['title'] ?? ''
		
		getList(false)
	})
</script>
css
<style lang="scss">
	
</style>
<style lang="scss">
	
</style>