Carousel 轮播图

用于循环播放一组图片或内容区域，支持自动播放、手动切换、指示器等多种功能。

基础用法

基础的轮播图用法，包含自动播放、指示器和箭头按钮。

基础轮播图

第一张幻灯片

美丽的渐变背景

第二张幻灯片

粉色系的浪漫风格

第三张幻灯片

清新的蓝色调

<template>
    <div class="demo-basic">
        <h3>基础轮播图</h3>
        <hy-carousel height="300px" @change="handleChange">
            <hy-carousel-item>
                <div class="slide-content" style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
                    <h3>第一张幻灯片</h3>
                    <p>美丽的渐变背景</p>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);">
                    <h3>第二张幻灯片</h3>
                    <p>粉色系的浪漫风格</p>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%);">
                    <h3>第三张幻灯片</h3>
                    <p>清新的蓝色调</p>
                </div>
            </hy-carousel-item>
        </hy-carousel>
    </div>
</template>

<script setup lang="ts">
function handleChange(currentIndex: number, oldIndex: number) {
    console.log(`从第${oldIndex + 1}张切换到第${currentIndex + 1}张`)
}
</script>

<style scoped>
.demo-basic {
    padding: 20px;
}

.slide-content {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    height: 100%;
    color: white;
    text-align: center;
}

.slide-content h3 {
    font-size: 24px;
    margin-bottom: 10px;
}

.slide-content p {
    font-size: 16px;
    opacity: 0.9;
}
</style>

禁用自动播放

通过设置 autoplay 属性为 false 来禁用自动播放功能。

禁用自动播放

手动切换 1

手动切换 2

手动切换 3

<template>
    <div class="demo-no-autoplay">
        <h3>禁用自动播放</h3>
        <hy-carousel :autoplay="false" height="250px">
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #42b983;">
                    <h3>手动切换 1</h3>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #ff6b6b;">
                    <h3>手动切换 2</h3>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #4ecdc4;">
                    <h3>手动切换 3</h3>
                </div>
            </hy-carousel-item>
        </hy-carousel>
    </div>
</template>

<script setup lang="ts">
</script>

<style scoped>
.demo-no-autoplay {
    padding: 20px;
}

.slide-content {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100%;
    color: white;
    font-size: 20px;
}
</style>

垂轮播

通过设置 direction 属性为 vertical 来实现垂直轮播。

垂直轮播

垂直滚动 1

从上到下滚动

垂直滚动 2

流畅的垂直动画

垂直滚动 3

不一样的滚动方向

<template>
    <div class="demo-vertical">
        <h3>垂直轮播</h3>
        <hy-carousel direction="vertical" height="300px" :autoplay="true" :interval="2000">
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #ffeaa7;">
                    <h3>垂直滚动 1</h3>
                    <p>从上到下滚动</p>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #dda0dd;">
                    <h3>垂直滚动 2</h3>
                    <p>流畅的垂直动画</p>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #a8edea;">
                    <h3>垂直滚动 3</h3>
                    <p>不一样的滚动方向</p>
                </div>
            </hy-carousel-item>
        </hy-carousel>
    </div>
</template>

<script setup lang="ts">
</script>

<style scoped>
.demo-vertical {
    padding: 20px;
}

.slide-content {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    height: 100%;
    color: #333;
    text-align: center;
}

.slide-content h3 {
    font-size: 22px;
    margin-bottom: 10px;
}

.slide-content p {
    font-size: 16px;
}
</style>

自定义高度

通过 height 属性设置轮播图的高度。

自定义高度

200px高度

<template>
    <div class="demo-height">
        <h3>自定义高度</h3>
        <hy-carousel height="200px" :autoplay="true">
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #f1c40f;">
                    <h3>200px高度</h3>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #e67e22;">
                    <h3>200px高度</h3>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #e74c3c;">
                    <h3>200px高度</h3>
                </div>
            </hy-carousel-item>
        </hy-carousel>
    </div>
</template>

<script setup lang="ts">
</script>

<style scoped>
.demo-height {
    padding: 20px;
}

.slide-content {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100%;
    color: white;
    font-size: 20px;
}
</style>

隐藏指示器

通过设置 indicator 属性为 false 来隐藏指示器。

隐藏指示器

无指示器 1

无指示器 2

<template>
    <div class="demo-no-indicator">
        <h3>隐藏指示器</h3>
        <hy-carousel :indicator="false" height="250px">
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #9b59b6;">
                    <h3>无指示器 1</h3>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #3498db;">
                    <h3>无指示器 2</h3>
                </div>
            </hy-carousel-item>
        </hy-carousel>
    </div>
</template>

<script setup lang="ts">
</script>

<style scoped>
.demo-no-indicator {
    padding: 20px;
}

.slide-content {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100%;
    color: white;
    font-size: 20px;
}
</style>

箭头显示方式

通过 arrow 属性控制箭头的显示方式：always | hover | never。

箭头始终显示

箭头始终显示 1

箭头始终显示 2

箭头始终显示 3

<template>
    <div class="demo-arrow">
        <h3>箭头始终显示</h3>
        <hy-carousel arrow="always" height="250px" :autoplay="false">
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #1abc9c;">
                    <h3>箭头始终显示 1</h3>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #2ecc71;">
                    <h3>箭头始终显示 2</h3>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #3498db;">
                    <h3>箭头始终显示 3</h3>
                </div>
            </hy-carousel-item>
        </hy-carousel>
    </div>
</template>

<script setup lang="ts">
</script>

<style scoped>
.demo-arrow {
    padding: 20px;
}

.slide-content {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100%;
    color: white;
    font-size: 20px;
}
</style>

禁用循环

通过设置 loop 属性为 false 来禁用循环播放。

禁用循环

非循环 1

到达边界后不会循环

非循环 2

最后一张后停止

非循环 3

第一张前停止

<template>
    <div class="demo-no-loop">
        <h3>禁用循环</h3>
        <hy-carousel :loop="false" height="250px" :autoplay="false">
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #e74c3c;">
                    <h3>非循环 1</h3>
                    <p>到达边界后不会循环</p>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #f39c12;">
                    <h3>非循环 2</h3>
                    <p>最后一张后停止</p>
                </div>
            </hy-carousel-item>
            <hy-carousel-item>
                <div class="slide-content" style="background-color: #27ae60;">
                    <h3>非循环 3</h3>
                    <p>第一张前停止</p>
                </div>
            </hy-carousel-item>
        </hy-carousel>
    </div>
</template>

<script setup lang="ts">
</script>

<style scoped>
.demo-no-loop {
    padding: 20px;
}

.slide-content {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    height: 100%;
    color: white;
    text-align: center;
}

.slide-content h3 {
    font-size: 20px;
    margin-bottom: 10px;
}

.slide-content p {
    font-size: 14px;
    opacity: 0.9;
}
</style>

Carousel API

Props

Name	Description	Type	Default
height	轮播图高度	`string`	`'300px'`
initialIndex	初始索引	`number`	`0`
autoplay	是否自动播放	`boolean`	`true`
interval	自动播放间隔	`number`	`3000`
indicator	是否显示指示器	`boolean`	`true`
indicatorPosition	指示器位置	`enum` - `'outside' \| 'inside'`	`'outside'`
arrow	箭头显示方式	`enum` - `'always' \| 'hover' \| 'never'`	`'hover'`
direction	轮播方向	`enum` - `'horizontal' \| 'vertical'`	`'horizontal'`
pauseOnHover	悬停时暂停	`boolean`	`true`
loop	是否循环播放	`boolean`	`true`

Events

Name	Description	Type
change	轮播图切换时触发	`(currentIndex: number, oldIndex: number) => void`

Slots

Name	Description
default	轮播项内容插槽

Expose

Name	Description	Type
setActionItem	设置活动项	`(index: number) => void`
prev	上一项	`() => void`
next	下一项	`() => void`

CarouselItem Props

Name	Description	Type	Default
—	—	—	—

CarouselItem Slots

Name	Description
default	轮播项内容

Carousel 轮播图 ​

基础用法 ​

基础轮播图

第一张幻灯片

第二张幻灯片

第三张幻灯片

禁用自动播放 ​

禁用自动播放

手动切换 1

手动切换 2

手动切换 3

垂轮播 ​

垂直轮播

垂直滚动 1

垂直滚动 2

垂直滚动 3

自定义高度 ​

自定义高度

200px高度

200px高度

200px高度

隐藏指示器 ​

隐藏指示器

无指示器 1

无指示器 2

箭头显示方式 ​

箭头始终显示

箭头始终显示 1

箭头始终显示 2

箭头始终显示 3

禁用循环 ​

禁用循环

非循环 1

非循环 2

非循环 3

Carousel API ​

Props ​

Events ​

Slots ​

Expose ​

CarouselItem Props ​

CarouselItem Slots ​

Carousel 轮播图

基础用法

禁用自动播放

垂轮播

自定义高度

隐藏指示器

箭头显示方式

禁用循环

Carousel API

Props

Events

Slots

Expose

CarouselItem Props

CarouselItem Slots