Carousel

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

用法

使用 Carousel 组件以轮播形式显示项目列表。

<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 }

您可以通过在 item 上使用basis / width工具类来控制可见的项目数量。

<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>

插件

Carousel 组件实现了官方的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>

示例

带缩略图

您可以使用emblaApi函数scrollTo在轮播下方显示缩略图，允许您导航到特定幻灯片。

<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{ size: 'md', color: 'neutral', variant: 'link' }Omit<ButtonProps, LinkPropsKeys>

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

prevIconappConfig.ui.icons.arrowLeftany

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

next{ size: 'md', color: 'neutral', variant: 'link' }Omit<ButtonProps, LinkPropsKeys>

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

nextIconappConfig.ui.icons.arrowRightany

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

arrowsfalseboolean

显示上一张和下一张按钮以滚动轮播。

dotsfalseboolean

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

orientation'horizontal'"vertical" | "horizontal"

轮播的方向。

itemsCarouselItem[]
autoplayfalseboolean | Partial<CreateOptionsType<OptionsType>>

启用自动播放插件

autoScrollfalseboolean | Partial<CreateOptionsType<OptionsType>>

启用自动滚动插件

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

启用自动高度插件

classNamesfalseboolean | Partial<CreateOptionsType<OptionsType>>

启用类名插件

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

启用渐隐插件

wheelGesturesfalseboolean | WheelGesturesPluginOptions

启用滚轮手势插件

align'center'"start" | "center" | "end" | (viewSize: number, snapSize: number, index: number): number
containScroll'trimSnaps'false | "trimSnaps" | "keepSnaps"
slidesToScroll1number | "auto"
dragFreefalseboolean
dragThreshold10number
inViewThreshold0number | number[]
循环falseboolean
skipSnapsfalseboolean
duration25number
startIndex0number
watchDragtruefalse | true | (emblaApi: EmblaCarouselType, evt: PointerEventType): boolean | void
watchResizetruefalse | true | (emblaApi: EmblaCarouselType, entries: ResizeObserverEntry[]): boolean | void
watchSlidestruefalse | true | (emblaApi: EmblaCarouselType, mutations: MutationRecord[]): boolean | void
watchFocustruefalse | true | (emblaApi: EmblaCarouselType, evt: FocusEvent): boolean | void
activetrueboolean
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'
              }
            }
          }
        }
      }
    })
  ]
})

更新日志

184ea— chore: 减少类型冗余，通过省略操作按钮中的链接属性

36a78— 修复：一致的 stopOnInteraction 行为 (#5489)

dd81d— feat: 添加 data-slot 属性 (#5447)

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)

手风琴

一组可折叠的堆叠面板。

空状态

用于显示空状态的组件。