Carousel

EmblaGitHub
一个使用 Embla 构建的带动画和滑动的轮播。

用法

使用走马灯组件以走马灯形式显示项目列表。

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel v-slot="{ item }" :items="items" class="w-full max-w-xs mx-auto">
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>
在桌面端，使用鼠标水平拖动走马灯。

项

使用数组形式的 items 属性，并通过默认插槽渲染每个项目

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel v-slot="{ item }" :items="items" class="w-full max-w-xs mx-auto">
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>

您还可以传入一个包含以下属性的对象数组

  • class?: any
  • ui?: { item?: ClassNameValue }

您可以使用basis / width实用类来控制 item 上可见的项目数量。

<script setup lang="ts">
const items = [
  'https://picsum.photos/468/468?random=1',
  'https://picsum.photos/468/468?random=2',
  'https://picsum.photos/468/468?random=3',
  'https://picsum.photos/468/468?random=4',
  'https://picsum.photos/468/468?random=5',
  'https://picsum.photos/468/468?random=6'
]
</script>

<template>
  <UCarousel v-slot="{ item }" :items="items" :ui="{ item: 'basis-1/3' }">
    <img :src="item" width="234" height="234" class="rounded-lg">
  </UCarousel>
</template>

Orientation

使用 orientation 属性更改进度条的方向。默认为 horizontal。

在桌面端，使用鼠标垂直拖动走马灯。
<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    orientation="vertical"
    :items="items"
    :ui="{ container: 'h-[336px]' }"
    class="w-full max-w-xs mx-auto"
  >
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>
在垂直方向上，您需要在容器上指定一个 height。

箭头

使用 arrows 属性显示上一个和下一个按钮。

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel v-slot="{ item }" arrows :items="items" class="w-full max-w-xs mx-auto">
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>

上一个/下一个

使用 prev 和 next 属性，使用任何 Button 属性自定义上一个和下一个按钮。

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    arrows
    :prev="{ color: 'primary' }"
    :next="{ variant: 'solid' }"
    :items="items"
    class="w-full max-w-xs mx-auto"
  >
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>

上一个/下一个图标

使用 prev-icon 和 next-icon 属性自定义按钮 Icon。默认为 i-lucide-arrow-left / i-lucide-arrow-right。

<script setup lang="ts">
defineProps<{
  prevIcon?: string
  nextIcon?: string
}>()

const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    arrows
    :prev-icon="prevIcon"
    :next-icon="nextIcon"
    :items="items"
    class="w-full max-w-xs mx-auto"
  >
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>
您可以在 app.config.ts 中的 ui.icons.arrowLeft / ui.icons.arrowRight 键下全局自定义这些图标。
您可以在 vite.config.ts 中的 ui.icons.arrowLeft / ui.icons.arrowRight 键下全局自定义这些图标。

点

使用 dots 属性显示点列表以滚动到特定幻灯片。

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel v-slot="{ item }" dots :items="items" class="w-full max-w-xs mx-auto">
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>

点的数量基于视图中显示的幻灯片数量

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel v-slot="{ item }" dots :items="items" :ui="{ item: 'basis-1/3' }">
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>

插件

走马灯组件实现了官方的Embla Carousel 插件.

自动播放

此插件用于扩展 Embla Carousel 的自动播放功能。

使用布尔值或对象形式的 autoplay 属性来配置自动播放插件.

<script setup lang="ts">
const items = [
  'https://picsum.photos/468/468?random=1',
  'https://picsum.photos/468/468?random=2',
  'https://picsum.photos/468/468?random=3',
  'https://picsum.photos/468/468?random=4',
  'https://picsum.photos/468/468?random=5',
  'https://picsum.photos/468/468?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    loop
    arrows
    dots
    :autoplay="{ delay: 2000 }"
    :items="items"
    :ui="{ item: 'basis-1/3' }"
  >
    <img :src="item" width="234" height="234" class="rounded-lg">
  </UCarousel>
</template>
在此示例中，我们使用 loop 属性来实现无限走马灯。

自动滚动

此插件用于扩展 Embla Carousel 的自动滚动功能。

使用布尔值或对象形式的 auto-scroll 属性来配置自动滚动插件.

<script setup lang="ts">
const items = [
  'https://picsum.photos/468/468?random=1',
  'https://picsum.photos/468/468?random=2',
  'https://picsum.photos/468/468?random=3',
  'https://picsum.photos/468/468?random=4',
  'https://picsum.photos/468/468?random=5',
  'https://picsum.photos/468/468?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    loop
    dots
    arrows
    auto-scroll
    :items="items"
    :ui="{ item: 'basis-1/3' }"
  >
    <img :src="item" width="234" height="234" class="rounded-lg">
  </UCarousel>
</template>
在此示例中，我们使用 loop 属性来实现无限走马灯。

自动高度

此插件用于扩展 Embla Carousel 的自动高度功能。它会改变走马灯容器的高度以适应视图中最高幻灯片的高度。

使用布尔值或对象形式的 auto-height 属性来配置自动高度插件.

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/320?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/320?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/320?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    auto-height
    arrows
    dots
    :items="items"
    :ui="{
      container: 'transition-[height]',
      controls: 'absolute -top-8 inset-x-12',
      dots: '-top-7',
      dot: 'w-6 h-1'
    }"
    class="w-full max-w-xs mx-auto"
  >
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>
在此示例中，我们在容器上添加了 transition-[height] 类来动画高度变化。

类名

类名是一个 Embla Carousel 的类名切换实用插件，它可以让您自动切换走马灯上的类名。

使用布尔值或对象形式的 class-names 属性来配置类名插件.

<script setup lang="ts">
const items = [
  'https://picsum.photos/528/528?random=1',
  'https://picsum.photos/528/528?random=2',
  'https://picsum.photos/528/528?random=3',
  'https://picsum.photos/528/528?random=4',
  'https://picsum.photos/528/528?random=5',
  'https://picsum.photos/528/528?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    class-names
    arrows
    :items="items"
    :ui="{
      item: 'basis-[70%] transition-opacity [&:not(.is-snapped)]:opacity-10'
    }"
    class="mx-auto max-w-sm"
  >
    <img :src="item" width="264" height="264" class="rounded-lg">
  </UCarousel>
</template>
在此示例中，我们在 item 上添加了 transition-opacity [&:not(.is-snapped)]:opacity-10 类来动画不透明度变化。

淡入淡出

此插件用于将 Embla Carousel 的滚动功能替换为淡入淡出过渡。

使用布尔值或对象形式的 fade 属性来配置淡入淡出插件.

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    fade
    arrows
    dots
    :items="items"
    class="w-full max-w-xs mx-auto"
  >
    <img :src="item" width="320" height="320" class="rounded-lg">
  </UCarousel>
</template>

滚轮手势

此插件用于扩展 Embla Carousel 的功能，使其能够使用鼠标/触控板滚轮来导航走马灯。

使用布尔值或对象形式的 wheel-gestures 属性来配置滚轮手势插件.

使用鼠标滚轮滚动走马灯。
<script setup lang="ts">
const items = [
  'https://picsum.photos/468/468?random=1',
  'https://picsum.photos/468/468?random=2',
  'https://picsum.photos/468/468?random=3',
  'https://picsum.photos/468/468?random=4',
  'https://picsum.photos/468/468?random=5',
  'https://picsum.photos/468/468?random=6'
]
</script>

<template>
  <UCarousel
    v-slot="{ item }"
    loop
    wheel-gestures
    :items="items"
    :ui="{ item: 'basis-1/3' }"
  >
    <img :src="item" width="234" height="234" class="rounded-lg">
  </UCarousel>
</template>

示例

带缩略图

您可以使用emblaApifunctionscrollTo在走马灯下方显示缩略图，允许您导航到特定幻灯片。

<script setup lang="ts">
const items = [
  'https://picsum.photos/640/640?random=1',
  'https://picsum.photos/640/640?random=2',
  'https://picsum.photos/640/640?random=3',
  'https://picsum.photos/640/640?random=4',
  'https://picsum.photos/640/640?random=5',
  'https://picsum.photos/640/640?random=6'
]

const carousel = useTemplateRef('carousel')
const activeIndex = ref(0)

function onClickPrev() {
  activeIndex.value--
}
function onClickNext() {
  activeIndex.value++
}
function onSelect(index: number) {
  activeIndex.value = index
}

function select(index: number) {
  activeIndex.value = index

  carousel.value?.emblaApi?.scrollTo(index)
}
</script>

<template>
  <div class="flex-1 w-full">
    <UCarousel
      ref="carousel"
      v-slot="{ item }"
      arrows
      :items="items"
      :prev="{ onClick: onClickPrev }"
      :next="{ onClick: onClickNext }"
      class="w-full max-w-xs mx-auto"
      @select="onSelect"
    >
      <img :src="item" width="320" height="320" class="rounded-lg">
    </UCarousel>

    <div class="flex gap-1 justify-between pt-4 max-w-xs mx-auto">
      <div
        v-for="(item, index) in items"
        :key="index"
        class="size-11 opacity-25 hover:opacity-100 transition-opacity"
        :class="{ 'opacity-100': activeIndex === index }"
        @click="select(index)"
      >
        <img :src="item" width="44" height="44" class="rounded-lg">
      </div>
    </div>
  </div>
</template>

API

属性

属性默认值类型
as

'div'

any

此组件应渲染为的元素或组件。

prev

启用箭头时配置上一个按钮。

prevIcon

appConfig.ui.icons.arrowLeft

字符串 | 对象

上一个按钮中显示的图标。

next

{ size: 'md', color: 'neutral', variant: 'link' }

ButtonProps

启用箭头时配置下一个按钮。

nextIcon

appConfig.ui.icons.arrowRight

字符串 | 对象

下一个按钮中显示的图标。

arrows

false

boolean

显示上一个和下一个按钮以滚动走马灯。

dots

false

boolean

显示点以滚动到特定幻灯片。

orientation

'horizontal'

"vertical" | "horizontal"

走马灯的方向。

items

CarouselItem[]

autoplay

false

启用自动播放插件

autoScroll

false

启用自动滚动插件

autoHeight

false

启用自动高度插件

classNames

false

boolean | Partial<CreateOptionsType<OptionsType>>

启用类名插件

fade

false

boolean | Partial<CreateOptionsType<{ active: boolean; breakpoints: { [key: string]: Omit<Partial<any>, "breakpoints">; }; }>>

启用淡入淡出插件

wheelGestures

false

boolean | WheelGesturesPluginOptions

启用滚轮手势插件

align

'center'

"start" | "center" | "end" | (viewSize: number, snapSize: number, index: number): number

containScroll

'trimSnaps'

false | "trimSnaps" | "keepSnaps"

slidesToScroll

1

number | "auto"

dragFree

false

boolean

dragThreshold

10

number

inViewThreshold

0

number | number[]

循环

false

boolean

skipSnaps

false

boolean

duration

25

number

startIndex

0

number

watchDrag

true

false | true | (emblaApi: EmblaCarouselType, evt: PointerEventType): boolean | void

watchResize

true

false | true | (emblaApi: EmblaCarouselType, entries: ResizeObserverEntry[]): boolean | void

watchSlides

true

false | true | (emblaApi: EmblaCarouselType, mutations: MutationRecord[]): boolean | void

watchFocus

true

false | true | (emblaApi: EmblaCarouselType, evt: FocusEvent): boolean | void

active

true

boolean

breakpoints

{}

{ [key: string]: Omit<Partial<CreateOptionsType<{ align: AlignmentOptionType; axis: AxisOptionType; container: string | HTMLElement | null; slides: string | HTMLElement[] | NodeListOf<HTMLElement> | null; containScroll: ScrollContainOptionType; direction: AxisDirectionOptionType; slidesToScroll: SlidesToScrollOptionType; dragFree: boolean; dragThreshold: number; inViewThreshold: number | number[] | undefined; loop: boolean; skipSnaps: boolean; duration: number; startIndex: number; watchDrag: DragHandlerOptionType; watchResize: ResizeHandlerOptionType; watchSlides: SlidesHandlerOptionType; watchFocus: FocusHandlerOptionType; }>>, "breakpoints">; }

ui

{ root?: ClassNameValue; viewport?: ClassNameValue; container?: ClassNameValue; item?: ClassNameValue; controls?: ClassNameValue; arrows?: ClassNameValue; prev?: ClassNameValue; next?: ClassNameValue; dots?: ClassNameValue; dot?: ClassNameValue; }

插槽

插槽类型
default

{ item: CarouselItem; index: number; }

事件

事件类型
select

[selectedIndex: number]

可访问属性

您可以使用useTemplateRef.

<script setup lang="ts">
const carousel = useTemplateRef('carousel')
</script>

<template>
  <UCarousel ref="carousel" />
</template>

这将使您能够访问以下内容

名称类型
emblaRefRef<HTMLElement | null>
emblaApiRef<EmblaCarouselType | null>

主题

app.config.ts
export default defineAppConfig({
  ui: {
    carousel: {
      slots: {
        root: 'relative focus:outline-none',
        viewport: 'overflow-hidden',
        container: 'flex items-start',
        item: 'min-w-0 shrink-0 basis-full',
        controls: '',
        arrows: '',
        prev: 'absolute rounded-full',
        next: 'absolute rounded-full',
        dots: 'absolute inset-x-0 -bottom-7 flex flex-wrap items-center justify-center gap-3',
        dot: [
          'cursor-pointer size-3 bg-accented rounded-full',
          'transition'
        ]
      },
      variants: {
        orientation: {
          vertical: {
            container: 'flex-col -mt-4',
            item: 'pt-4',
            prev: 'top-4 sm:-top-12 left-1/2 -translate-x-1/2 rotate-90 rtl:-rotate-90',
            next: 'bottom-4 sm:-bottom-12 left-1/2 -translate-x-1/2 rotate-90 rtl:-rotate-90'
          },
          horizontal: {
            container: 'flex-row -ms-4',
            item: 'ps-4',
            prev: 'start-4 sm:-start-12 top-1/2 -translate-y-1/2',
            next: 'end-4 sm:-end-12 top-1/2 -translate-y-1/2'
          }
        },
        active: {
          true: {
            dot: 'data-[state=active]:bg-inverted'
          }
        }
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        carousel: {
          slots: {
            root: 'relative focus:outline-none',
            viewport: 'overflow-hidden',
            container: 'flex items-start',
            item: 'min-w-0 shrink-0 basis-full',
            controls: '',
            arrows: '',
            prev: 'absolute rounded-full',
            next: 'absolute rounded-full',
            dots: 'absolute inset-x-0 -bottom-7 flex flex-wrap items-center justify-center gap-3',
            dot: [
              'cursor-pointer size-3 bg-accented rounded-full',
              'transition'
            ]
          },
          variants: {
            orientation: {
              vertical: {
                container: 'flex-col -mt-4',
                item: 'pt-4',
                prev: 'top-4 sm:-top-12 left-1/2 -translate-x-1/2 rotate-90 rtl:-rotate-90',
                next: 'bottom-4 sm:-bottom-12 left-1/2 -translate-x-1/2 rotate-90 rtl:-rotate-90'
              },
              horizontal: {
                container: 'flex-row -ms-4',
                item: 'ps-4',
                prev: 'start-4 sm:-start-12 top-1/2 -translate-y-1/2',
                next: 'end-4 sm:-end-12 top-1/2 -translate-y-1/2'
              }
            },
            active: {
              true: {
                dot: 'data-[state=active]:bg-inverted'
              }
            }
          }
        }
      }
    })
  ]
})

更新日志

21fbe— 修复：确保插件在客户端导航后初始化 (#5117)

a9fe7— 修复：为保持一致性，添加缺少的 data-orientation

fde53— 修复：在 RTL 方向反转箭头键 (#5072)

788d2— 修复：标准化类型接口命名 (#4990)

fd6a6— 杂项：使用 tsdoc @see 代替 @link

61b60— 功能：允许传递组件而不是名称 (#4766)

5cb65— 特性：导入 @nuxt/ui-pro 组件

55e06— 修复：改善可访问性

fc24e— 修复：为可访问性添加按钮元素类型 (#4493)

1ba8a— 修复：为活动点添加 aria-current 属性 (#4447)

3b67d— 修复：通过页面过渡解析插件 (#4380)

be41a— 修复：移除按钮默认md尺寸 (#4357)

2ee1c— 功能：允许自定义活动点颜色 (#4229)

b9adc— feat: 在 items 中添加 ui 字段 (#4060)

e6e51— fix：class 应该优先于 ui 属性

22edf— 功能：添加 select 事件 (#3678)

39c86— fix：@nuxt/module-builder 升级后重构类型（#3855)

b9983— 修复：改进泛型类型 (#3331)

手风琴

一组可折叠的堆叠面板。

空状态

一个显示空状态的组件。