Swiper 轮播图

17:06

说明

轮播图，接收 list 数组并循环自动播放，支持 rect / dot / round / number 四种指示器（mode）与指示器位置（indicatorPos）、3D 立体效果（effect3d）、底部标题叠加（title）以及圆角、高度、切换间隔等配置。列表项既可以是图片地址字符串，也可以是带图片字段与 title 的对象（图片字段名由 name 指定，默认 image）。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持（swiper 为原生组件，项与指示器的 transition 被禁用，切换与 3D 缩放为瞬时，无过渡动画）

示例

基础用法

默认自动播放、循环衔接，底部显示圆角指示器。

查看源码

<template>
    <ux-swiper :list="list" />
</template>

<script setup lang="uts">
type SwiperItem = {
    image: string;
    title?: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300' },
    { image: 'https://picsum.photos/id/1016/600/300' },
    { image: 'https://picsum.photos/id/1018/600/300' }
];
</script>

指示器模式 mode

通过 mode 切换 rect(矩形)/dot(圆点)/round(圆角长条)/number(数字) 四种指示器。

查看源码

<template>
    <ux-swiper :list="list" :mode="mode" />
    <view class="btn-wrap">
        <ux-button v-for="(item, index) in modeList" :key="index" :type="mode === item.value ? 'primary' : 'default'" custom-class="btn-item" size="small" @click="mode = item.value">{{ item.label }}</ux-button>
    </view>
</template>

<script setup lang="uts">
import type { SwiperMode } from '@/uni_modules/uview-pro-x';

type SwiperItem = {
    image: string;
    title?: string;
};

type ModeItem = {
    value: SwiperMode;
    label: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300' },
    { image: 'https://picsum.photos/id/1016/600/300' },
    { image: 'https://picsum.photos/id/1018/600/300' }
];

const mode = ref<SwiperMode>('round');

const modeList: ModeItem[] = [
    { value: 'rect', label: '矩形' },
    { value: 'dot', label: '圆点' },
    { value: 'round', label: '圆条' },
    { value: 'number', label: '数字' }
];
</script>

<style scoped>
.btn-wrap {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    align-items: center;
    margin-top: 12px;
}
.btn-item {
    margin-right: 12px;
    margin-bottom: 12px;
}
</style>

3D效果 effect3d

effect3d=true 时，非激活项缩放并留出两侧间距，营造 3D 立体感。

查看源码

<template>
    <ux-swiper :list="list" :effect3d="true" />
</template>

<script setup lang="uts">
type SwiperItem = {
    image: string;
    title?: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300' },
    { image: 'https://picsum.photos/id/1016/600/300' },
    { image: 'https://picsum.photos/id/1018/600/300' }
];
</script>

标题显示 title

title=true 配合 list 数据中的 title 字段，在底部叠加显示标题。

查看源码

<template>
    <ux-swiper :list="list" :title="true" height="100" />
</template>

<script setup lang="uts">
type SwiperItem = {
    image: string;
    title?: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300', title: '风景一' },
    { image: 'https://picsum.photos/id/1016/600/300', title: '风景二' },
    { image: 'https://picsum.photos/id/1018/600/300', title: '风景三' }
];
</script>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
list	轮播数据列表，数组对象	any[]	-	-
title	是否显示标题	boolean	false	-
borderRadius	圆角，单位px	string | number	4	-
interval	自动切换时间间隔，单位ms	string | number	3000	-
mode	指示器类型 round/dot/rect/number/none	SwiperMode	'round'	-
height	轮播高度，单位px	string | number	125	-
indicatorPos	指示器位置	SwiperIndicatorPosition	'bottomCenter'	-
effect3d	是否开启3D效果	boolean	false	-
effect3dPreviousMargin	3D模式下前一项的边距，单位px	string | number	25	-
autoplay	是否自动播放	boolean	true	-
duration	切换动画时长，单位ms	string | number	500	-
circular	是否循环播放	boolean	true	-
imgMode	图片裁剪模式	ImgMode	'aspectFill'	-
name	轮播项对象的图片字段名	string	'image'	-
bgColor	轮播背景色	string	''	-
current	当前激活项索引	string | number	0	-
titleStyle	标题样式对象	UTSJSONObject	-	-

Events

事件名	说明	回调参数	版本
click	点击轮播图时触发，参数：index（当前点击项索引）	index: number	-
change	轮播项切换时触发，参数：current（当前激活项索引）	current: number	-

Slots

ux-swiper 无插槽。

注意事项

1. mode 仅实现 rect / dot / round / number 四种；mode="none" 时不渲染任何指示器。
2. effect3d 仅在 true 时露出前后项（通过 previous-margin / next-margin，间距由 effect3dPreviousMargin 控制，默认 25px）；非 3D 时前后间距为 0，非激活项会 scaleY(0.9) 并左右各留 10px。
3. 列表项为对象时，图片字段名由 name 指定（默认 image），标题取对象的 title 字段，且需 title=true 才显示。
4. list 长度变化时内部激活索引会重置为 0；current 只用于初始定位与外部受控，用户手动滑动后不会回写 current，如需同步请监听 change。
5. click 事件虽在 API 中声明，但当前源码模板未在轮播项上绑定点击处理，实际点击不会触发；需要在点击时自行在列表项外层包裹可点击元素。
6. 微信小程序端 transition 被禁用（避免与原生组件共存卡顿），切换与 3D 缩放无过渡动画。
7. title 标题在图片底部叠加半透明黑底白字；当 mode="number" 且指示器在底部时，标题会预留 30px 内边距避免被指示器遮挡。
8. interval 默认 3000ms，duration 默认 500ms，imgMode 默认 aspectFill。