Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Carousel 轮播图
在有限的空间里轮流展示一组同类内容,例如首页横幅、图片集、公告。
引入
import { NsCarousel, NsCarouselItem } from '@ns/ui'
基础用法
每一页放在一个 NsCarouselItem 里。height 设置轮播区域的高度,不写时是 300px;页面内容要自己撑满这个高度(height: 100%)。默认每 3 秒自动切换一次,鼠标悬停时暂停。
<script setup lang="ts">
import { NsCarousel, NsCarouselItem } from '@ns/ui'
</script>
<template>
<NsCarousel height="200px">
<NsCarouselItem v-for="i in 4" :key="i">
<div class="slide">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
</template>
<style scoped>
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
background: var(--ns-color-primary);
color: var(--ns-color-white);
}
</style>
高度
height 可以写字符串('200px'、'50vh'),也可以写数字,数字按 px 处理。下面两个轮播的高度分别是数字 120 和字符串 '180px':
<template>
<NsSpace direction="vertical" fill>
<NsCarousel :height="120">
<NsCarouselItem v-for="i in 3" :key="i">
<div :class="['slide', `slide--${i}`]">:height="120",第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
<NsCarousel height="180px">
<NsCarouselItem v-for="i in 3" :key="i">
<div :class="['slide', `slide--${i}`]">height="180px",第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
</NsSpace>
</template>
<style scoped>
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
}
.slide--1 {
background: var(--ns-color-primary);
}
.slide--2 {
background: var(--ns-color-success);
}
.slide--3 {
background: var(--ns-color-warning);
}
</style>
自动播放
autoplay 控制是否自动切换,interval 是间隔(毫秒),pauseOnHover 控制鼠标悬停时是否暂停。这几个属性运行中修改会立即生效;页面是异步加载出来的也会自动开始播放。下面可以直接改这几个属性看效果:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCarousel, NsCarouselItem, NsCheckbox, NsSpace } from '@ns/ui'
const autoplay = ref(true)
const pauseOnHover = ref(false)
const interval = ref(5000)
const intervals = [1000, 3000, 5000]
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap align="center">
<NsCheckbox v-model="autoplay">自动播放(autoplay)</NsCheckbox>
<NsCheckbox v-model="pauseOnHover">悬停暂停(pause-on-hover)</NsCheckbox>
<span>间隔(interval):</span>
<NsButton
v-for="ms in intervals"
:key="ms"
size="small"
:type="interval === ms ? 'primary' : 'default'"
@click="interval = ms"
>
{{ ms / 1000 }} 秒
</NsButton>
</NsSpace>
<NsCarousel
height="200px"
:autoplay="autoplay"
:interval="interval"
:pause-on-hover="pauseOnHover"
>
<NsCarouselItem v-for="i in 3" :key="i">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
</NsSpace>
</template>
<style scoped>
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
}
.slide--1 {
background: var(--ns-color-primary);
}
.slide--2 {
background: var(--ns-color-success);
}
.slide--3 {
background: var(--ns-color-warning);
}
</style>
箭头
arrow 控制左右箭头的显示时机:'hover'(默认)鼠标悬停或键盘焦点在轮播里时显示,'always' 一直显示,'never' 不显示(还可以点指示器或用方向键切换)。
loop 为 false 时不循环,到了第一张或最后一张,对应的箭头会禁用。下面第一个轮播同时关掉了 loop:
<template>
<NsSpace direction="vertical" fill>
<span class="caption">arrow="always",:loop="false"</span>
<NsCarousel height="160px" arrow="always" :loop="false" :autoplay="false">
<NsCarouselItem v-for="i in 3" :key="i">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
<span class="caption">arrow="hover"(默认,鼠标移上来才显示)</span>
<NsCarousel height="160px" :autoplay="false">
<NsCarouselItem v-for="i in 3" :key="i">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
<span class="caption">arrow="never"</span>
<NsCarousel height="160px" arrow="never" :autoplay="false">
<NsCarouselItem v-for="i in 3" :key="i">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
}
.slide--1 {
background: var(--ns-color-primary);
}
.slide--2 {
background: var(--ns-color-success);
}
.slide--3 {
background: var(--ns-color-warning);
}
</style>
指示器
指示器默认显示在轮播区域外面(indicator-position="outside"),'none' 不显示。每个指示器的读屏文字是对应 NsCarouselItem 的 label,没写时是“第 N 张”。
<template>
<NsSpace direction="vertical" fill>
<span class="caption">indicator-position="outside"(默认)</span>
<NsCarousel height="160px">
<NsCarouselItem v-for="i in 3" :key="i" :label="`第 ${i} 张`">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
<span class="caption">indicator-position="none"</span>
<NsCarousel height="160px" indicator-position="none">
<NsCarouselItem v-for="i in 3" :key="i" :label="`第 ${i} 张`">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
}
.slide--1 {
background: var(--ns-color-primary);
}
.slide--2 {
background: var(--ns-color-success);
}
.slide--3 {
background: var(--ns-color-warning);
}
</style>
卡片模式
type="card" 时,当前页在中间,前后两页缩小后露在左右边缘,点击它们可以切换。type 默认是 ''(普通模式)。
<template>
<NsCarousel type="card" height="200px">
<NsCarouselItem v-for="i in 5" :key="i">
<div :class="['slide', `slide--${i}`]">卡片 {{ i }}</div>
</NsCarouselItem>
</NsCarousel>
</template>
<style scoped>
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
}
.slide--1 {
background: var(--ns-color-primary);
}
.slide--2 {
background: var(--ns-color-success);
}
.slide--3 {
background: var(--ns-color-warning);
}
.slide--4 {
background: var(--ns-color-danger);
}
.slide--5 {
background: var(--ns-color-help);
}
</style>
竖向
direction 默认 'horizontal'(左右切换)。direction="vertical" 时上下切换:箭头在上下两端,指示器在右侧居中,键盘用上下方向键。卡片模式也能竖向,两侧的卡片露在上下边缘。
<template>
<NsSpace direction="vertical" fill>
<span class="caption">direction="vertical"</span>
<NsCarousel direction="vertical" height="240px">
<NsCarouselItem v-for="i in 4" :key="i">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 页</div>
</NsCarouselItem>
</NsCarousel>
<span class="caption">direction="vertical",type="card"</span>
<NsCarousel direction="vertical" type="card" height="240px" :autoplay="false">
<NsCarouselItem v-for="i in 4" :key="i">
<div :class="['slide', `slide--${i}`]">卡片 {{ i }}</div>
</NsCarouselItem>
</NsCarousel>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
}
.slide--1 {
background: var(--ns-color-primary);
}
.slide--2 {
background: var(--ns-color-success);
}
.slide--3 {
background: var(--ns-color-warning);
}
.slide--4 {
background: var(--ns-color-danger);
}
</style>
受控切换
用 v-model 绑定当前页的序号(从 0 开始),在外面改它就能切换;也可以通过 ref 调用 prev、next、setActiveItem。切换时触发 change,参数里有新旧序号和当前页的 name、label。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCarousel, NsCarouselItem, NsSpace } from '@ns/ui'
import type { CarouselChangeEvent } from '@ns/ui'
const active = ref(0)
const carouselRef = ref<InstanceType<typeof NsCarousel>>()
const lastChange = ref('')
const handleChange = (event: CarouselChangeEvent) => {
lastChange.value = `prevIndex ${event.prevIndex} → activeIndex ${event.activeIndex},name:${event.name},label:${event.label}`
}
</script>
<template>
<div style="margin-bottom: 12px">
<NsSpace wrap>
<NsButton @click="carouselRef?.prev()">上一张(prev)</NsButton>
<NsButton @click="carouselRef?.next()">下一张(next)</NsButton>
<NsButton @click="carouselRef?.setActiveItem(2)">跳到第 3 张(setActiveItem)</NsButton>
<NsButton @click="active = 0">回到第一张(v-model)</NsButton>
</NsSpace>
</div>
<NsCarousel
ref="carouselRef"
v-model="active"
height="200px"
:autoplay="false"
@change="handleChange"
>
<NsCarouselItem v-for="i in 4" :key="i" :name="`slide-${i}`" :label="`第 ${i} 张`">
<div :class="['slide', `slide--${i}`]">第 {{ i }} 张</div>
</NsCarouselItem>
</NsCarousel>
<p style="margin-top: 12px">v-model:{{ active }}</p>
<p>change:{{ lastChange || '还没有切换' }}</p>
</template>
<style scoped>
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
}
.slide--1 {
background: var(--ns-color-primary);
}
.slide--2 {
background: var(--ns-color-success);
}
.slide--3 {
background: var(--ns-color-warning);
}
.slide--4 {
background: var(--ns-color-danger);
}
</style>
动态增删
NsCarouselItem 可以用 v-for 渲染、随时增删。指示器按页面在 DOM 里的顺序排列;删掉当前页(或它后面的页)以后,当前序号会修正到新的最后一页,并触发 update:modelValue 和 change。
切到最后一页再点“删掉最后一页”,可以看到当前序号跟着修正:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCarousel, NsCarouselItem, NsSpace } from '@ns/ui'
const pages = ref([1, 2, 3])
const active = ref(0)
let nextId = 4
const add = () => {
pages.value = [...pages.value, nextId]
nextId += 1
}
const removeLast = () => {
pages.value = pages.value.slice(0, -1)
}
</script>
<template>
<div style="margin-bottom: 12px">
<NsSpace wrap>
<NsButton icon="plus" @click="add">加一页</NsButton>
<NsButton icon="minus" :disabled="pages.length <= 1" @click="removeLast">
删掉最后一页
</NsButton>
</NsSpace>
</div>
<NsCarousel v-model="active" height="160px" arrow="always" :autoplay="false">
<NsCarouselItem v-for="id in pages" :key="id">
<div class="slide">页面 {{ id }}</div>
</NsCarouselItem>
</NsCarousel>
<p style="margin-top: 12px">共 {{ pages.length }} 页,当前序号 {{ active }}</p>
</template>
<style scoped>
.slide {
height: 100%;
display: flex;
align-items: center;
justify-content: center;
color: var(--ns-color-white);
background: var(--ns-color-primary);
}
</style>
键盘操作
- 箭头和指示器都是原生按钮,可以用 Tab 聚焦,按空格或回车切换。
- 焦点在轮播里面时,横向按左右方向键、竖向按上下方向键切换到上一张、下一张。
NsCarousel Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | number | 0 | 当前页的序号,从 0 开始,支持 v-model |
| height | string | number | '' | 轮播区域的高度,数字按 px 处理。不写时是 300px |
| autoplay | boolean | true | 是否自动切换。只有一页时不切换 |
| interval | number | 3000 | 自动切换的间隔(毫秒) |
| indicatorPosition | 'outside' | 'none' | 'outside' | 指示器的位置。'outside' 在轮播区域外面,'none' 不显示 |
| arrow | 'always' | 'hover' | 'never' | 'hover' | 箭头的显示时机。'hover' 是鼠标悬停或键盘焦点在轮播里时显示 |
| loop | boolean | true | 是否循环切换。关掉后到头的箭头禁用 |
| direction | 'horizontal' | 'vertical' | 'horizontal' | 方向 |
| pauseOnHover | boolean | true | 鼠标悬停时是否暂停自动切换 |
| type | '' | 'card' | '' | 类型。'card' 是卡片模式,两侧的卡片露在左右(竖向时上下)边缘,可点击 |
NsCarouselItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| name | string | number | - | 页面的名字,change 事件里会带上 |
| label | string | - | 对应指示器的读屏文字,change 事件里也会带上 |
NsCarousel Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (index: number) | 当前页变化时触发,v-model 用的就是它 |
| change | (event: CarouselChangeEvent) | 当前页变化时触发,参数里有新旧序号和新页面的 name、label |
NsCarousel Slots
| 插槽 | 说明 |
|---|---|
| default | 放 NsCarouselItem,每个是一页 |
NsCarouselItem Slots
| 插槽 | 说明 |
|---|---|
| default | 这一页的内容 |
NsCarousel 方法
通过 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| setActiveItem | index: number | - | 切换到指定序号的页面。超出范围时:循环模式下绕到另一头,不循环时停在两端 |
| prev | - | - | 切换到上一页 |
| next | - | - | 切换到下一页 |
另外暴露了 activeIndex(Ref<number>),是当前页的序号。
类型
import type {
CarouselProps,
CarouselItemProps,
CarouselChangeEvent,
CarouselDirection,
CarouselIndicatorPosition,
CarouselArrow,
CarouselType
} from '@ns/ui'
type CarouselDirection = 'horizontal' | 'vertical'
type CarouselIndicatorPosition = 'outside' | 'none'
type CarouselArrow = 'always' | 'hover' | 'never'
type CarouselType = '' | 'card'
interface CarouselProps {
modelValue?: number
height?: string | number
autoplay?: boolean
interval?: number
indicatorPosition?: CarouselIndicatorPosition
arrow?: CarouselArrow
loop?: boolean
direction?: CarouselDirection
pauseOnHover?: boolean
type?: CarouselType
}
interface CarouselItemProps {
name?: string | number
label?: string
}
interface CarouselChangeEvent {
activeIndex: number
prevIndex: number
name?: string | number
label?: string
}
另外还导出了 CarouselContext、CarouselItemInstance 和 CAROUSEL_INJECTION_KEY,是 NsCarousel 和 NsCarouselItem 之间通信用的内部类型。
注意事项
NsCarouselItem必须放在NsCarousel里,单独使用会在控制台警告。- 页面是绝对定位的,不会撑开容器,高度要靠
height设置;页面内容写height: 100%才能填满。 - 普通模式下切换没有滑动动画,是直接显示和隐藏。卡片模式下有位移和缩放的过渡。
- 只有一页时不显示箭头和指示器,也不自动播放。
- 键盘方向键在轮播的根元素上监听,页面里放了输入框时,在输入框里按方向键也会切换。
- 箭头和指示器按钮都写了
type="button",放在<form>里点击不会提交表单。 - 卡片模式下不在舞台上(不是当前页和前后两页)的卡片是隐藏的,不能被点击和聚焦。
优化点
- [ ] 支持滑动、淡入淡出等切换动画
- [ ] 支持一次切换多页(
numScroll) - [ ] 支持自定义箭头插槽(
arrow),参数带total、currentIndex、to、prev、next - [ ] 支持指示器放在轮播区域里面,以及线条样式的指示器
- [ ] 支持鼠标悬停在指示器上切换(
trigger="hover") - [ ] 支持鼠标滚轮、触摸滑动切换