Swiper 轮播图 | 我的资料管理-uv-ui 是全面兼容vue3+2、nvue、app、h5、小程序等多端的uni-app生态框架

# Swiper 轮播图

✈

组件名：uv-swiper

该组件一般用于导航轮播，banner展示等场景，可开箱即用，具有如下特点：

自定义指示器模式，可配置指示器样式
3D轮播图效果，满足不同的开发需求
可配置显示标题，涵盖不同的应用场景
具有设置加载状态和嵌入视频的能力，功能齐全丰富

# 平台兼容性

App（vue）	App（nvue）	H5	小程序	VUE2	VUE3
√	√	√	√	√	√

注意事项

为了避免错误使用，给大家带来不好的开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。

swiper在App的vue中、百度支付宝头条QQ小程序中，不支持内嵌video、map等原生组件。在微信基础库2.4.4起和App nvue2.1.5起支持内嵌原生组件。
uv-swiper 是在uni提供的swiper基础上进行封装，更多问题可以去官方swiper查看 (opens new window)

# 基本使用

通过list参数传入轮播图列表值，该值为一个数组，键值为图片路径，例如：

<template>
	<uv-swiper :list="list"></uv-swiper>
</template>
<script>
	export default {
		data() {
			return {
				list: [
					'https://cdn.uviewui.com/uview/swiper/swiper1.png',
					'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					'https://cdn.uviewui.com/uview/swiper/swiper3.png',
				]
			}
		}
	}
</script>

# 带标题

通过showTitle属性以展示标题，此时list的参数应为一个对象，如下示例：
通过titleStyle属性设置标题的样式

注意

您期望使用对象作为参数时，需要配置uv-swiper组件的keyName参数为您当前对象的图片key值）如：keyName="image"

<template>
	<uv-swiper 
	:list="list" 
	keyName="image" 
	showTitle 
	:title-style="{color:'red',textAlign: 'center'}" 
	:autoplay="false"
	circular></uv-swiper>
</template>
<script>
	export default {
		data() {
			return {
				list: [{
					image: 'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					title: '丙辰中秋，欢饮达旦，大醉，作此篇，兼怀子由',
				}, {
					image: 'https://cdn.uviewui.com/uview/swiper/swiper1.png',
					title: '明月几时有？把酒问青天'
				}, {
					image: 'https://cdn.uviewui.com/uview/swiper/swiper3.png',
					title: '不知天上宫阙，今夕是何年'
				}]
			}
		}
	}
</script>

# 带指示器

通过indicator属性添加指示器
通过indicatorMode属性设置指示器的类型：line - 线形状 dot - 点形状

<template>
	<uv-swiper :list="list" indicator indicatorMode="line" circular></uv-swiper>
</template>
<script>
	export default {
		data() {
			return {
				list: [
					'https://cdn.uviewui.com/uview/swiper/swiper3.png',
					'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					'https://cdn.uviewui.com/uview/swiper/swiper1.png',
				]
			}
		}
	}
</script>

# 加载中

通过添加loading属性设置加载中的状态
您也可以动态的来控制加载状态，比如：:loading='loading'

<template>
	<uv-swiper :list="[]" loading></uv-swiper>
</template>

# 嵌入视频

我们提供了嵌入视频的能力，为避免资源浪费，在您切换轮播的时候视频会停止播放，你可以设置poster指定视频封面，案例如下：

注意事项

swiper在App的vue中、百度支付宝头条QQ小程序中，不支持内嵌video、map等原生组件。在微信基础库2.4.4起和App nvue2.1.5起支持内嵌原生组件。

<template>
	<uv-swiper :list="list" keyName="url" :autoplay="false"></uv-swiper>
</template>
<script>
	export default {
		data() {
			return {
				list: [{
					url: 'https://cdn.uviewui.com/uview/resources/video.mp4',
					title: '昨夜星辰昨夜风，画楼西畔桂堂东',
					poster: 'https://cdn.uviewui.com/uview/swiper/swiper1.png'
				}, {
					url: 'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					title: '身无彩凤双飞翼，心有灵犀一点通'
				}, {
					url: 'https://cdn.uviewui.com/uview/swiper/swiper3.png',
					title: '谁念西风独自凉，萧萧黄叶闭疏窗，沉思往事立残阳'
				}]
			}
		}
	}
</script>

# 指定类型

默认会根据链接自动判断swiper-item类型，但是在极端情况下可能会不准确，所以我们提供了指定item的类型，通过设置type为video或image，如下：

<template>
	<uv-swiper :list="list" keyName="url" :autoplay="false"></uv-swiper>
</template>
<script>
	export default {
		data() {
			return {
				list: [{
					url: 'https://cdn.uviewui.com/uview/resources/video.mp4',
					title: '昨夜星辰昨夜风，画楼西畔桂堂东',
					poster: 'https://cdn.uviewui.com/uview/swiper/swiper1.png',
					type: 'video'
				}, {
					url: 'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					title: '身无彩凤双飞翼，心有灵犀一点通',
					type: 'image'
				}, {
					url: 'https://cdn.uviewui.com/uview/swiper/swiper3.png',
					title: '谁念西风独自凉，萧萧黄叶闭疏窗，沉思往事立残阳'
				}]
			}
		}
	}
</script>

# 自定义指示器

如您需要以指示点或数字形式来自定义指示器，请参考如下案例：

<template>
	<view class="uv-demo-block">
		<text class="uv-demo-block__title">自定义指示器</text>
		<uv-swiper 
			:list="list1" 
			@change="e => current1 = e.current" 
			:autoplay="false">
			<template v-slot:indicator>
				<view class="indicator">
					<view class="indicator__dot" 
						v-for="(item, index) in list1" 
						:key="index" 
						:class="[index === current1 && 'indicator__dot--active']"
					></view>
				</view>
			</template>
		</uv-swiper>
		<view style="height: 15px;"></view>
		<uv-swiper 
			:list="list2" 
			@change="e => current2 = e.current" 
			:autoplay="false" 
			indicatorStyle="right: 20px">
			<template v-slot:indicator>
				<view class="indicator-num">
					<text class="indicator-num__text">{{ current2 + 1 }}/{{ list2.length }}</text>
				</view>
			</template>
		</uv-swiper>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				current1: 0,
				current2: 0,
				list1: [
					'https://cdn.uviewui.com/uview/swiper/swiper3.png',
					'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					'https://cdn.uviewui.com/uview/swiper/swiper1.png',
				],
				list2: [
					'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					'https://cdn.uviewui.com/uview/swiper/swiper3.png',
					'https://cdn.uviewui.com/uview/swiper/swiper1.png',
				]
			}
		}
	}
</script>
<style lang="scss">
	@mixin flex($direction: row) {
		/* #ifndef APP-NVUE */
		display: flex;
		/* #endif */
		flex-direction: $direction;
	}
	.indicator {
		@include flex(row);
		justify-content: center;
		&__dot {
			height: 6px;
			width: 6px;
			border-radius: 100px;
			background-color: rgba(255, 255, 255, 0.35);
			margin: 0 5px;
			transition: background-color 0.3s;
			&--active {
				background-color: #ffffff;
			}
		}
	}
	.indicator-num {
		padding: 2px 0;
		background-color: rgba(0, 0, 0, 0.35);
		border-radius: 100px;
		width: 35px;
		@include flex;
		justify-content: center;
		&__text {
			color: #FFFFFF;
			font-size: 12px;
		}
	}
</style>

# 卡片式轮播

在实际开发中，普通的轮播或许不能满足您的开发需求，swiper组件提供了卡片式轮播的api，您可以参考以下案例实现此功能

<template>
	<!-- #ifndef APP-NVUE || MP-TOUTIAO -->
	<view class="uv-demo-block">
		<text class="uv-demo-block__title">卡片式</text>
		<uv-swiper 
			:list="list" 
			previousMargin="30" 
			nextMargin="30" 
			circular 
			:autoplay="false" 
			radius="5" 
			bgColor="#ffffff">
		</uv-swiper>
	</view>
	<!-- #endif -->
</template>
<script>
	export default {
		data() {
			return {
				list: [
					'https://cdn.uviewui.com/uview/swiper/swiper3.png',
					'https://cdn.uviewui.com/uview/swiper/swiper2.png',
					'https://cdn.uviewui.com/uview/swiper/swiper1.png'
				]
			}
		}
	}
</script>

# 控制轮播效果

autoplay 是否自动轮播，默认为true
interval 前后两张图自动轮播的时间间隔
duration 切换一张轮播图所需的时间
circular 是否衔接滑动，即到最后一张时，是否可以直接转到第一张

# 完整示例

完整示例下载地址

https://ext.dcloud.net.cn/plugin?name=uv-ui (opens new window)

# API

# Swiper Props

参数	说明	类型	默认值	可选值
list	轮播图数据，见上方"基本使用"说明	Array	-	-
indicator	是否显示面板指示器	Boolean	false	true \| false
indicatorActiveColor	指示器激活的颜色	String	#FFFFFF	-
indicatorInactiveColor	指示器非激活颜色	String	rgba(255, 255, 255, 0.35)	-
indicatorStyle	指示器样式，可通过bottom，left，right进行定位	String \| Object	-	-
indicatorMode	指示器模式	String	line	line \| dot
autoplay	是否自动切换	Boolean	true	true \| false
current	当前所在滑块的 index	Number \| String	0	-
currentItemId	当前所在滑块的 item-id ，不能与 current 被同时指定，支付宝小程序不支持	String	-	-
interval	滑块自动切换时间间隔（ms）	String \| Number	3000	-
duration	滑块切换过程所需时间（ms），nvue不支持	String \| Number	300	-
circular	播放到末尾后是否重新回到开头	Boolean	false	true \| false
vertical1.0.4	滑动方向是否为纵向	Boolean	false	true \| false
previousMargin	前边距，可用于露出前一项的一小部分，app-nvue、抖音小程序、飞书小程序不支持	String \| Number	0	-
nextMargin	后边距，可用于露出后一项的一小部分，app-nvue、抖音小程序、飞书小程序不支持	String \| Number	0	-
acceleration	当开启时，会根据滑动速度，连续滑动多屏，仅支付宝小程序支持	Boolean	false	true \| false
displayMultipleItems	同时显示的滑块数量，nvue、支付宝小程序不支持	Number	1	-
easingFunction	指定swiper切换缓动动画类型，仅支持微信小程序、快手小程序、京东小程序	String	default	linear、easeInCubic、easeOutCubic、easeInOutCubic，参考swiper (opens new window)
keyName	list数组中指定对象的目标属性名	String	url	-
imgMode	图片的裁剪模式，不建议设置widthFix，如果图片比例不一样，理论上是会在切换的时候不断变化高度，实际上内部高度定死，所以是矛盾的，在部分平台显示会有异常	String	aspectFill	详见图片裁剪
height	组件高度	String \| Number	130	-
bgColor	背景颜色	String	#f3f4f6	-
radius	组件圆角，数值或带单位的字符串	String \| Number	4	-
loading	是否加载中	Boolean	false	true \| false
showTitle	是否显示标题，要求数组对象中有`title`属性	Boolean	false	-
titleStyle1.0.3	显示的标题样式	Object	-	-

# Swiper Events

事件名	说明	回调参数
@click	点击轮播图时触发	index：点击了第几张图片，从0开始
@change	轮播图切换时触发(自动或者手动切换)	index：切换到了第几张图片，从0开始

# SwiperIndicator Props

参数	说明	类型	默认值	可选值
length	轮播的长度	String \| Number	0	-
current	当前处于活动状态的轮播的索引	String \| Number	0	-
indicatorActiveColor	指示器非激活颜色	String	-	-
indicatorInactiveColor	指示器的激活颜色	String	-	-
indicatorStyle	指示器的形式	String	line	line \| dot

← ScrollList 横向滚动列表 Collapse 折叠面板 →