@composy/carousel-vue

@composy/carousel-vue

@composy/carousel-core 的 Vue 适配层：提供 <Carousel> / <CarouselSlide> 组件、useCarousel 组合式函数与 Vue / Engine 插件，把核心轮播引擎的配置与事件完整映射到 Vue 响应式世界。

✨ 核心能力

• 🧩 声明式组件 —— <Carousel> 透传核心全部配置（效果、断点、自动播放、懒加载、滚动条、缩略图等），props 变化后自动重建实例
• 🔔 组件事件 —— 核心事件全部转发为 Vue 事件（slide-change、progress、lazy-load、autoplay-start 等），并通过 ready 事件拿到底层 Carousel 实例
• 🧪 组合式函数 —— useCarousel(container, options) 返回响应式状态 refs 与命令式控制方法，适合自定义结构
• 🔌 两种插件 —— CarouselVuePlugin 全局注册组件（可自定义前缀）；createCarouselEnginePlugin 接入 @composy/engine-vue
• ♻️ Vue 3 适配 —— 使用 Vue 3 Composition API，peer 依赖 vue ^3.5.32
• ⛓️ provide/inject 组合 —— CarouselSlide 自动注入父级轮播实例上下文，无需手动传递
• 🎨 复用核心样式 —— 沿用核心包 ldesign-carousel 类名前缀与 --ldesign-carousel-* CSS 变量

📦 安装

pnpm add @composy/carousel-vue
# 核心库会作为依赖自动安装；也可显式安装：
pnpm add @composy/carousel-core

Peer 依赖：vue ^3.5.32。Vue 2 不在当前适配层的支持范围内。

子路径导出：.、./components、./components/*、./composables、./plugins、./types。样式入口：@composy/carousel-vue/index.css（指向 dist/index.css）、./style/index.css、./style/index.less。

🚀 快速开始

组件用法

<script setup lang="ts">
import { Carousel, CarouselSlide } from '@composy/carousel-vue'
import '@composy/carousel-core/style.css'

function onSlideChange(event: {
  currentIndex: number
  previousIndex: number
  direction: 'next' | 'prev'
}) {
  console.info(event.currentIndex)
}
</script>

<template>
  <Carousel
    loop
    :navigation="true"
    :pagination="{ type: 'numbers' }"
    :scrollbar="{ enabled: true, draggable: true }"
    :lazy-load="{ enabled: true, preloadCount: 1 }"
    aria-label="产品轮播"
    @slide-change="onSlideChange"
  >
    <CarouselSlide>
      
    </CarouselSlide>
    <CarouselSlide>第二张</CarouselSlide>
    <CarouselSlide>第三张</CarouselSlide>
  </Carousel>
</template>

useCarousel 组合式函数

<script setup lang="ts">
import { useCarousel } from '@composy/carousel-vue'
import { ref } from 'vue'
import '@composy/carousel-core/style.css'

const container = ref<HTMLElement | null>(null)
const { activeIndex, progress, slideNext, slidePrev, pauseAutoplay, resumeAutoplay } = useCarousel({
  container,
  options: { loop: true, navigation: true, autoplay: { delay: 3000 } },
})
</script>

<template>
  <div ref="container">
    <div class="ldesign-carousel__slide">第一张</div>
    <div class="ldesign-carousel__slide">第二张</div>
  </div>
  <output>{{ activeIndex }} / {{ progress }}</output>
  <button type="button" @click="slidePrev">上一张</button>
  <button type="button" @click="slideNext">下一张</button>
  <button type="button" @click="pauseAutoplay">暂停播放</button>
  <button type="button" @click="resumeAutoplay">继续播放</button>
</template>

📖 API 参考

<Carousel> 组件

Props 与核心 CarouselOptions 一一对应（direction、effect、loop、rewind、slidesPerView、spaceBetween、breakpoints、autoplay、pagination、navigation、scrollbar、thumbnails、keyboard、mousewheel、lazyLoad、各 effect 配置、ariaLabel / ariaLive 等），默认值如 speed: 300、effect: 'slide'、touchThreshold: 50、watchOverflow: true、ariaLive: 'polite'。另有 containerStyle、containerClass、slideSelector 等展示相关 props。

事件：ready(instance)、destroy、error(error)、slideChange、transitionStart / transitionEnd、progress、lazyLoad / lazyError、autoplayStart / autoplayStop / autoplayPause / autoplayResume、lock / unlock / enable / disable、reachBeginning / reachEnd、resize。

通过模板 ref 暴露的方法：

<CarouselSlide> 组件

单个幻灯片容器，渲染 .ldesign-carousel__slide 元素。Props：className（自定义类名）、style（内联样式）、ariaLabel（无障碍标签），内容走默认插槽。

useCarousel(opts)

参数：{ container: Ref<HTMLElement | null>, options?: Partial<Omit<CarouselOptions, 'container'>> }。

返回：instance、activeIndex、totalSlides、progress、isBeginning、isEnd、isLocked、isDisabled（均为响应式 ref），以及命令式方法 slideTo / slideNext / slidePrev、startAutoplay / stopAutoplay / pauseAutoplay / resumeAutoplay、lock / unlock / enable / disable、update、destroy、getState。

container ref 变为 null 时，当前实例会销毁，所有状态 ref 会恢复初始值；之后 ref 指向新容器时会创建新实例。

插件

import { Carousel as CarouselPlugin } from '@composy/carousel-vue/plugins'
import { createApp } from 'vue'

createApp(App).use(CarouselPlugin) // 注册 LCarousel / LCarouselSlide 及 LDesignCarousel 别名

• CarouselVuePlugin（即 Carousel）：选项 { prefix?: string }（默认 'L'），注册 ${prefix}Carousel / ${prefix}CarouselSlide，并同时注册 LDesignCarousel / LDesignCarouselSlide 别名
• createCarouselEnginePlugin(config?)：接入 @composy/engine-vue，配置 { globalComponents?: boolean, defaultOptions?: Record<string, any> }

useCarousel 的状态快照

useCarousel 除 activeIndex、totalSlides、progress、isBeginning、isEnd、isLocked 和 isDisabled 外，还返回 isAnimating、isDragging、isAutoplayRunning。组合式函数会在 transitionStart、transitionEnd、touch、autoplay、lock、unlock、enable、disable 和 resize 事件后同步这些 refs。

容器 ref 变为 null 时会先取消所有事件订阅、销毁 Core，再把所有状态恢复为初始值。连续 props 变化由 revision 保护，已经过期的 nextTick 不会重新创建旧容器实例。

🎨 样式与主题

样式随核心包分发，在应用入口引入一次即可：

import '@composy/carousel-core/style.css'

类名前缀 ldesign-carousel、CSS 变量前缀 --ldesign-carousel-*（默认桥接全局 --ld-* token）均由核心包定义，主题定制方式见 核心包 README。

🔨 构建产物与验证

使用 @composy/builder（ldesign-builder build）生成四套产物：dist/（浏览器 IIFE + CSS）、es/（ESM + 类型）、esm/（ESM 备选输出）、lib/（CJS）。

Builder、ESLint 与 TypeScript 的权威配置位于 .ldesign/；根目录 tsconfig.json 和 eslint.config.js 保留为兼容入口。构建后会归一化并校验 package.json 导出目标。

验证命令（取自本包 package.json scripts）：

pnpm build        # 构建
pnpm type-check   # ESM Vue/TypeScript 检查
pnpm type-check:cjs # CJS Vue/TypeScript 检查
pnpm test:run     # 单元测试
pnpm lint:check   # ESLint 检查

🔗 相关链接

• ../../README.md —— LDesign Carousel 总览
• ../core/README.md —— 核心引擎配置项、事件与样式变量