uView Next
4.0.105

外观

Swiper 轮播图

约 1736 字大约 6 分钟

2025-10-31

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

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

基础功能

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

<template>
	<un-swiper :list="list1" @change="change" @click="click"></un-swiper>
</template>

<script setup lang="uts">
	import { ref } from 'vue';
	import { UnSwiperItem } from '@/uni_modules/uview-unix';

	const list1 = ref<UnSwiperItem[]>([{
		url: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
	},
	{
		url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
	},
	{
		url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
	}]);

	function change(e: number) {
		 console.log('change', e);
	}

	function click(e: number) {
		console.log('click', e);
	}
</script>

带标题

添加showTitle属性以展示标题，此时list的参数应为一个对象：

<template>
	<un-swiper :list="list2" showTitle :autoplay="false" circular></un-swiper>
</template>

<script setup lang="uts">
	import { ref } from 'vue';
	import { UnSwiperItem } from '@/uni_modules/uview-unix';

	const list2 = ref<UnSwiperItem[]>([{
		url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
		title: '昨夜星辰昨夜风，画楼西畔桂堂东',
	},
	{
		url: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
		title: '身无彩凤双飞翼，心有灵犀一点通'
	},
	{
		url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
		title: '谁念西风独自凉，萧萧黄叶闭疏窗，沉思往事立残阳'
	}
	]);
</script>

带指示器

通过indicator属性添加指示器，例如：

<template>
	<un-swiper :list="list3" indicator indicatorMode="line" circular></un-swiper>
</template>

<script setup lang="uts">
	import { ref } from 'vue';
	import { UnSwiperItem } from '@/uni_modules/uview-unix';

	const list3 = ref<UnSwiperItem[]>([
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
		}
	]);
</script>

加载中

通过添加loading属性达到加载中的状态，例如：

<template>
	<un-swiper :list="list3" loading></un-swiper>
</template>

<script setup lang="uts">
	import { ref } from 'vue';
	import { UnSwiperItem } from '@/uni_modules/uview-unix';

	const list3 = ref<UnSwiperItem[]>([
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
		}
	]);
</script>

嵌入视频

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

<template>
	<un-swiper :list="list4" :autoplay="false"></un-swiper>
</template>

<script setup lang="uts">
	import { ref } from 'vue';
	import { UnSwiperItem } from '@/uni_modules/uview-unix';

	const list4 = ref<UnSwiperItem[]>([
		{
			url: 'https://uview.d3u.cn/web/static/uview/resources/video.mp4',
			title: '昨夜星辰昨夜风，画楼西畔桂堂东',
			poster: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
			title: '身无彩凤双飞翼，心有灵犀一点通'
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
			title: '谁念西风独自凉，萧萧黄叶闭疏窗，沉思往事立残阳'
		}
	]);
</script>

自定义指示器

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

<template>
	<un-swiper :list="list5" @change="change5" :autoplay="false">
		<template #indicator>
			<view class="indicator">
				<view class="indicator__dot" v-for="(item, index) in list5" :key="index"
					:class="[index == current ? 'indicator__dot--active' : '']">
				</view>
			</view>
		</template>
	</un-swiper>
	<un-gap bgColor="transparent" height="15"></un-gap>
	<un-swiper 
		:list="list6" 
		@change="change6" 
		:autoplay="false"
		indicatorStyle="right: 20px"
	>
		<template #indicator>
			<view class="indicator-num">
				<text class="indicator-num__text">{{ currentNum + 1 }}/{{ list6.length }}</text>
			</view>
		</template>
	</un-swiper>
</template>

<script setup lang="uts">
	import { ref } from 'vue';
	import { UnSwiperItem } from '@/uni_modules/uview-unix';

	const current = ref(0);
	const currentNum = ref(0);

	const list5 = ref<UnSwiperItem[]>([
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
		}
	]);

	const list6 = ref<UnSwiperItem[]>([
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
		}
	]);

	function change5(e: number) {
		console.log('change5', e);
	}

	function change6(e: number) {
		console.log('change6', e);
	}
</script>

<style lang="scss">
	.indicator {
		display: flex;
		flex-direction: 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;
		display: flex;
		flex-direction: row;
		justify-content: center;

		&__text {
			color: #FFFFFF;
			font-size: 12px;
		}
	}
</style>

卡片式轮播

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

<template>
	<un-swiper :list="list3" previousMargin="30" nextMargin="30" circular :autoplay="false" radius="5" bgColor="#ffffff"></un-swiper>
</template>

<script setup lang="uts">
	import { ref } from 'vue';
	import { UnSwiperItem } from '@/uni_modules/uview-unix';

	const list3 = ref<UnSwiperItem[]>([
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/3.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/2.jpg',
		},
		{
			url: 'https://uview.d3u.cn/web/static/uview/album/1.jpg',
		}
	]);
</script>

控制轮播效果

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

API

SwiperProps

参数说明类型默认值
list轮播图数据列表UnSwiperItem[][]
indicator是否显示指示器booleanfalse
indicatorActiveColor指示器激活状态颜色string'#FFFFFF'
indicatorInactiveColor指示器非激活状态颜色string'rgba(255, 255, 255, 0.35)'
indicatorStyle指示器样式（可选）string | object''
indicatorMode指示器模式
Enum
line
autoplay是否自动播放booleantrue
current当前轮播图索引string | number0
currentItemId当前轮播图项的IDstring''
interval自动播放间隔时间string | number3000
duration轮播动画时长string | number300
circular是否循环播放booleanfalse
previousMargin前边距string'0px'
nextMargin后边距string'0px'
acceleration是否启用加速动效booleanfalse
displayMultipleItems同时显示的轮播图数量number1
easingFunction缓动函数类型stringdefault
imgMode图片模式stringaspectFill
height轮播图高度string | number130
bgColor背景颜色string''
radius圆角大小string | number4
loading是否显示加载状态booleanfalse
showTitle是否显示标题booleanfalse

Swiper Events

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

SwiperIndicator Props

参数说明类型默认值
length轮播的长度Number0
current当前处于活动状态的轮播的索引Number0
activeColor 4.0.101指示器激活颜色String-
inactiveColor 4.0.101指示器非激活颜色String-
mode 4.0.101指示器模式
Enum
line
size 4.0.101指示器尺寸String|Number单值为 line 时，为 22
customStyle 4.0.101自定义样式String|Object''

Slot

名称说明作用域
default默认插槽，用于自定义轮播图项的内容
indicator自定义指示器

数据类型

// 轮播图项的数据类型，用于定义 `list` 属性的数据结构。
type UnSwiperItem = {
    url: string                    // 轮播图项的图片或视频地址
    title?: string                 // 轮播图项的标题（可选）
    poster?: string                // 轮播图项的海报图地址，用于视频封面（可选）
    type?: string                  // 轮播图项的类型，可选值为 'image' 或 'video'（可选）
}

Scss 变量

组件提供了以下 SCSS 变量，可用于自定义样式：

变量名默认值说明
$un-swiper-bg-color$bg-color轮播图背景颜色
$un-swiper-transition-duration0.3s轮播图切换过渡时间
$un-swiper-title-padding6px 12px标题内边距
$un-swiper-title-font-size$text-base标题字体大小
$un-swiper-title-bg-colorrgba(0, 0, 0, 0.3)标题背景颜色
$un-swiper-indicator-bottom10px指示器底部距离
$un-swiper-item-scale0.92非激活轮播图缩放比例
$un-swiper-loading-bg-color$bg-color加载状态背景颜色
$un-swiper-loading-size20px加载图标大小
$un-swiper-loading-color$text-color加载图标颜色

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next