外观
Swiper 轮播图
约 1546 字大约 5 分钟
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-是否自动轮播，默认为trueinterval-前后两张图自动轮播的时间间隔duration-切换一张轮播图所需的时间circular-是否衔接滑动，即到最后一张时，是否可以直接转到第一张
API
SwiperProps
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| list | 轮播图数据列表 | UnSwiperItem[] | [] |
| indicator | 是否显示指示器 | boolean | false |
| indicatorActiveColor | 指示器激活状态颜色 | string | '#FFFFFF' |
| indicatorInactiveColor | 指示器非激活状态颜色 | string | 'rgba(255, 255, 255, 0.35)' |
| indicatorStyle | 指示器样式（可选） | string | object | '' |
| indicatorMode | 指示器模式 | Enum | line |
| autoplay | 是否自动播放 | boolean | true |
| current | 当前轮播图索引 | string | number | 0 |
| currentItemId | 当前轮播图项的ID | string | '' |
| interval | 自动播放间隔时间 | string | number | 3000 |
| duration | 轮播动画时长 | string | number | 300 |
| circular | 是否循环播放 | boolean | false |
| previousMargin | 前边距 | string | '0px' |
| nextMargin | 后边距 | string | '0px' |
| acceleration | 是否启用加速动效 | boolean | false |
| displayMultipleItems | 同时显示的轮播图数量 | number | 1 |
| easingFunction | 缓动函数类型 | string | default |
| imgMode | 图片模式 | string | aspectFill |
| height | 轮播图高度 | string | number | 130 |
| bgColor | 背景颜色 | string | '' |
| radius | 圆角大小 | string | number | 4 |
| loading | 是否显示加载状态 | boolean | false |
| showTitle | 是否显示标题 | boolean | false |
Swiper Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击轮播图时触发 | index: 点击了第几张图片，从 0 开始 |
| change | 轮播图切换时触发(自动或者手动切换) | index: 切换到了第几张图片，从 0 开始 |
SwiperIndicator Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| length | 轮播的长度 | Number | 0 |
| current | 当前处于活动状态的轮播的索引 | Number | 0 |
| 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'（可选）
}