手把手带你开发一个易用又灵活的 Carousel 组件

本文由体验技术团队Kagol同学创作~

前端组件库作为 Web 应用开发重要的基石，发挥了用户体验统一和开发效率提升的双层价值，但业务场景变化和需求变化万千，没有任何组件库可以满足所有业务场景，但我们依然可以通过精心的 API 设计，让组件在易用性和灵活性这两个看似矛盾的能力中取得平衡，覆盖尽可能丰富的业务场景，在业务开发中发挥更大的价值。

本文主要以 Carousel 走马灯组件为例，给大家分享我的组件设计经验，如何通过子组件+插槽的设计思想，让组件在易用性和灵活性之间取得平衡。

先来看下我们要实现的 VueCarousel 组件的效果图：

可以看到它的功能是很强大的，可以应用于丰富的业务场景，接下来就带大家一起来设计和实现 VueCarousel。

实现步骤

1、创建初始项目工程

先使用 vite 命令行工具创建一个初始项目工程。

npm create vite vue-carousel 

cd vue-carousel npm i npm run dev 

然后安装必要的依赖。

npm i -D @vitejs/plugin-vue-jsx sass 

配置下 vite.config.ts

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' ++ import vueJsx from '@vitejs/plugin-vue-jsx' ++ import path from 'path'   // https://vitejs.dev/config/ export default defineConfig({ --  plugins: [vue()], ++  plugins: [vue(), vueJsx()], ++  resolve: { ++    alias: [ ++      { find: '@kagol/vue-carousel', replacement: path.resolve(__dirname, 'carousel') } ++    ]   } }) 

2、创建空的 Carousel 组件

在实现具体的组件功能之前，我们先创建一个空的组件结构，走通组件本地效果预览的流程。

先看下这个组件怎么使用。

在 src/main.ts 中导入和注册组件插件：

import { createApp } from 'vue' ++ import Carousel from '@kagol/vue-carousel' import './style.css' import App from './App.vue' -- createApp(App).mount('#app') ++ createApp(App).use(Carousel).mount('#app') 

然后在 src/App.vue 中使用：

<template>   <HelloWorld msg="Vite + Vue" /> ++  <XCarousel /> </template> 

接下来设计这个组件的目录结构：

vue-carousel ├── carousel |  ├── index.ts |  └── src |     ├── carousel.scss |     └── carousel.tsx 

先编写入口文件 carousel/index.ts

import type { App } from 'vue' import XCarousel from './src/carousel' export { XCarousel } export default {   install(app: App) {     app.component(XCarousel.name, XCarousel)   } } 

然后是定义组件 carousel/src/carousel.tsx

import { defineComponent } from 'vue' import './carousel.scss'   export default defineComponent({   name: 'XCarousel',   setup(props, context) {     return () => {       return <div class="x-carousel">XCarousel</div>     }   } }) 

编写样式 carousel/src/carousel.scss

.x-carousel {   color: red; } 

效果如下：

3、增加 usePage 实现基础分页能力

接下来实现组件逻辑，Carousel 组件本质上是一个简化的分页组件。

先实现分页逻辑 composables/use-page.ts

import { ref } from 'vue'   export default function usePage(defaultPageIndex = 1) {   // 当前页码   const pageIndex = ref(defaultPageIndex)     // 跳到第几页   const setPageIndex = (current: number) => {     pageIndex.value = current   }     // 一次性往前（或往后）跳几页   const jumpPage = (page: number) => {     pageIndex.value += page   }     // 上一页   const prevPage = () => jumpPage(-1)     // 下一页   const nextPage = () => jumpPage(1)     return { pageIndex, setPageIndex, jumpPage, prevPage, nextPage } } 

然后配合 UI 展示 carousel.tsx

import { defineComponent } from 'vue' ++ import usePage from './composables/use-page' import './carousel.scss'   export default defineComponent({   name: 'XCarousel',   setup(props, context) { ++    const { pageIndex, prevPage, nextPage } = usePage(1)     return () => { --      return <div class="x-carousel">XCarousel</div> ++      return <div class="x-carousel"> ++        <button onClick={ prevPage }>上一页</button> ++        <span>当前页码：{ pageIndex.value }</span> ++        <button onClick={ nextPage }>下一页</button> ++      </div>     }   } }) 

carousel/src/carousel.scss

.x-carousel { --  color: red; ++  color: #3c3c43; } 

效果如下：

点击上一个、下一页按钮可以切换页码。

4、实现 Carousel 基础功能

我们再配合轮播内容，实现 Carousel 基础功能。

carousel.tsx

import { defineComponent, renderSlot, useSlots } from 'vue' import usePage from './composables/use-page' import './carousel.scss'   export default defineComponent({   name: 'XCarousel',   setup(props, context) {     const { pageIndex, prevPage, nextPage } = usePage(1) ++    // 获取插槽内容中的元素数量 ++    const count = useSlots().default().length     return () => {       return <div class="x-carousel"> ++        <div class="x-carousel-item-container" style={{ ++          width: count * 100 + '%', // 根据内容元素的数量计算容器宽度 ++          left: - (pageIndex.value - 1) * 100 + '%', // 根据当前页码计算容器偏移的位置，从而显示特定的元素内容 ++        }}>{renderSlot(useSlots(), 'default')}</div>         <button onClick={ prevPage }>上一页</button>         <span>当前页码：{ pageIndex.value }</span>         <button onClick={ nextPage }>下一页</button>       </div>     }   } }) 

carousel/src/carousel.scss

.x-carousel { ++  overflow: hidden;   color: #3c3c43; } ++ .x-carousel-item-container { ++  display: flex; ++  position: relative; ++ ++  & > * { ++    flex: 1; ++  } ++} 

在 App.vue 中使用：

<template> --  <XCarousel /> ++  <XCarousel> ++    <div class="carousel-item">page 1</div> ++    <div class="carousel-item">page 2</div> ++    <div class="carousel-item">page 3</div> ++  </XCarousel> </template> <style scoped> ++.carousel-item { ++  text-align: center; ++  line-height: 200px; ++  background: #f3f6f8; ++} </style> 

效果如下： 

点击上一页、下一页，不仅页码会变化，上面的轮播内容也会跟随变化，基础功能已实现，接下来就是完善分页器样式，并增加页码指示器，让 Carousel 组件的功能更加完整。

5、增加分页器

用一个向左和向右的箭头图标代替之前的上一页、下一页按钮。

carousel.tsx

import { defineComponent, renderSlot, useSlots } from 'vue' import usePage from './composables/use-page' import './carousel.scss'   export default defineComponent({   name: 'XCarousel',   setup(props, context) {     const { pageIndex, prevPage, nextPage } = usePage(1)     // 获取插槽内容中的元素数量     const count = useSlots().default().length     return () => {       return <div class="x-carousel">         <div class="x-carousel-item-container" style={{           width: count * 100 + '%', // 根据内容元素的数量计算容器宽度           left: - (pageIndex.value - 1) * 100 + '%', // 根据当前页码计算容器偏移的位置，从而显示特定的元素内容         }}>{renderSlot(useSlots(), 'default')}</div> --        <button onClick={ prevPage }>上一页</button> --        <span>当前页码：{ pageIndex.value }</span> --        <button onClick={ nextPage }>下一页</button> ++        <div class="x-carousel-pagination"> ++          <button class="arrow arrow-left" onClick={ prevPage }> ++            <svg width="18px" height="18px" viewBox="0 0 16 16">XXX</svg> ++          </button> ++          <button class="arrow arrow-right" onClick={ nextPage }> ++            <svg width="18px" height="18px" viewBox="0 0 16 16" version="1.1">XXX</svg> ++          </button> ++        </div>       </div>     }   } }) 

并调整对应的样式，增加切换时的动效。

carousel.scss

.x-carousel { ++  position: relative;   overflow: hidden;   color: #3c3c43; } .x-carousel-item-container {   display: flex;   position: relative; ++  transition: left 500ms ease 0s; // 内容切换时的动效   & > * {     flex: 1;   } } ++.x-carousel-pagination { ++  position: absolute; ++  width: 100%; ++  top: 50%; ++  display: flex; ++  justify-content: space-between; ++  margin-top: -18px; ++  ++  .arrow { ++    cursor: pointer; ++    width: 36px; ++    height: 36px; ++    border-radius: 18px; ++    background: rgba(255, 255, 255, .8); ++    box-shadow: 0 4px 16px 0 rgba(0, 0, 0, .1); ++    display: inline-flex; ++    align-items: center; ++    justify-content: center; ++    border: 0; ++    outline: 0; ++    transition: background-color .3s cubic-bezier(.645, .045, .355, 1); // 按钮hover时的动效 ++ ++    &:hover { ++      background: #f8f8f8; ++    } ++  ++    &.arrow-left { ++      margin-left: 20px; ++    } ++  ++    &.arrow-right { ++      margin-right: 20px; ++    } ++  } ++} 

效果如下：

6、增加页码指示器

为了了解当前轮播到了哪一页，还需要增加增加页码指示器，页码指示器其实就类似分页组件里面的页码，只是一般显示成小圆点，而不是数字。

carousel.tsx

import { defineComponent, renderSlot, useSlots } from 'vue' import usePage from './composables/use-page' import './carousel.scss'   export default defineComponent({   name: 'XCarousel',   setup(props, context) {     // 跳转特定页码时，需要使用到 setPageIndex 方法     const { pageIndex, prevPage, nextPage, setPageIndex } = usePage(1)     // 获取插槽内容中的元素数量     const count = useSlots().default().length   ++    // 生成指示器数组 ++    const indicatorArr = Array.from(new Array(count).keys())     return () => {       return <div class="x-carousel">         <div class="x-carousel-item-container" style={{           width: count * 100 + '%', // 根据内容元素的数量计算容器宽度           left: - (pageIndex.value - 1) * 100 + '%', // 根据当前页码计算容器偏移的位置，从而显示特定的元素内容         }}>{renderSlot(useSlots(), 'default')}</div>         <div class="x-carousel-pagination">           <button class="arrow arrow-left" onClick={ prevPage }>             <svg width="18px" height="18px" viewBox="0 0 16 16">XXX</svg>           </button>           <button class="arrow arrow-right" onClick={ nextPage }>             <svg width="18px" height="18px" viewBox="0 0 16 16" version="1.1">XXX</svg>           </button>         </div> ++        <div class="x-carousel-indicator"> ++          { ++            indicatorArr.map((item, index) => { ++              return <div class={`x-carousel-indicator-item${pageIndex.value === index+1 ? ' active' : ''}`} onClick={() => setPageIndex(index + 1)}></div> ++            }) ++          } ++        </div>       </div>     }   } }) 

调整下样式 carousel.scss

... ++.x-carousel-indicator { ++  display: flex; ++  position: absolute; ++  bottom: 12px; ++  justify-content: center; ++  width: 100%; ++  ++  .x-carousel-indicator-item { ++    cursor: pointer; ++    width: 6px; ++    height: 6px; ++    border-radius: 3px; ++    margin-right: 8px; ++    background: #d3d5d9; ++  ++    &.active { ++      width: 24px; ++      background: #5e7ce0; ++      transition: all .3s cubic-bezier(.645, .045, .355, 1); // 切换内容时指示器小圆点上的动效 ++    } ++  } ++} 

效果如下：

至此，一个功能完整的 Carousel 组件就完成了，但这个组件是一个封装好的组件，开发者不能灵活进行扩展和定制。

7、增加灵活性：子组件+插槽

为了增加组件的灵活性，让用户可以自定义一些内容，我们需要做两件事：

• 将子组件抽取出来，并暴露给开发者
• 设置对应的插槽，让开发者可以放置自己的内容，当然也可以放置我们暴露出去的子组件

我们以页码指示器这个子组件为例，其他子组件同理。

先定义一个 CarouselIndicator 子组件。

carousel/src/components/carousel-indicator.tsx

import { defineComponent, toRefs, watch } from 'vue' import usePage from '../composables/use-page' import './carousel-indicator.scss' export default defineComponent({   name: 'XCarouselIndicator',   props: {     modelValue: {       type: Number,     },     count: {       type: Number,     }   },   emits: ['update:modelValue'],   setup(props, { emit, slots }) {     const { modelValue } = toRefs(props)     const { pageIndex, setPageIndex } = usePage(modelValue.value)     const indicatorArr = Array.from(new Array(props.count).keys())     watch(modelValue, (newVal: number) => {       pageIndex.value = newVal     })     watch(pageIndex, (newVal: number) => {       emit('update:modelValue', newVal)     })          return () => {       return <div class="x-carousel-indicator">         {           slots.default           ? slots.default({             pageIndex: pageIndex.value,             setPageIndex           })           : indicatorArr.map((item, index) => {             return <div class={`x-carousel-indicator-item${pageIndex.value === index+1 ? ' active' : ''}`} onClick={() => setPageIndex(index + 1)}></div>           })         }       </div>     }   } }) 

carousel-indicator.scss

.x-carousel-indicator {   display: flex;   position: absolute;   bottom: 12px;   justify-content: center;   width: 100%;     .x-carousel-indicator-item {     cursor: pointer;     width: 6px;     height: 6px;     border-radius: 3px;     margin-right: 8px;     background: #d3d5d9;       &.active {       width: 24px;       background: #5e7ce0;       transition: all .3s cubic-bezier(.645, .045, .355, 1); // 切换内容时指示器小圆点上的动效     }   } } 

然后把写死的页码指示器用 CarouselIndicator 子组件替换，并增加 indicator 插槽。

carousel.tsx

import { defineComponent, renderSlot, useSlots } from 'vue' ++import XCarouselIndicator from './components/carousel-indicator' import usePage from './composables/use-page' import './carousel.scss'   export default defineComponent({   name: 'XCarousel', ++  components: { ++    XCarouselIndicator, ++  }, --  setup(props, context) { ++  setup(props, { slots }) {     // 跳转特定页码时，需要使用到 setPageIndex 方法     const { pageIndex, prevPage, nextPage, setPageIndex } = usePage(1)     // 获取插槽内容中的元素数量     const count = useSlots().default().length   --    // 生成指示器数组 --    const indicatorArr = Array.from(new Array(count).keys())     return () => {       return <div class="x-carousel">         <div class="x-carousel-item-container" style={{           width: count * 100 + '%', // 根据内容元素的数量计算容器宽度           left: - (pageIndex.value - 1) * 100 + '%', // 根据当前页码计算容器偏移的位置，从而显示特定的元素内容         }}>{renderSlot(useSlots(), 'default')}</div>         ... --        <div class="x-carousel-indicator"> --          { --            indicatorArr.map((item, index) => { --              return <div class={`x-carousel-indicator-item${pageIndex.value === index+1 ? ' active' : ''}`} onClick={() => setPageIndex(index + 1)}></div> --            }) --          } --        </div> ++        {slots.indicator ? ( ++          slots.indicator({ ++            count, ++            pageIndex: pageIndex.value, ++            setPageIndex ++          }) ++        ) : ( ++          <XCarouselIndicator ++            count={count} ++            v-model={pageIndex.value} ++          ></XCarouselIndicator> ++        )}       </div>     }   } }) 

移除页码指示器对应的样式代码 carousel.scss

... --.x-carousel-indicator { --  display: flex; --  position: absolute; --  bottom: 12px; --  justify-content: center; --  width: 100%; --  --  .x-carousel-indicator-item { --    cursor: pointer; --    width: 6px; --    height: 6px; --    border-radius: 3px; --    margin-right: 8px; --    background: #d3d5d9; --  --    &.active { --      width: 24px; --      background: #5e7ce0; --      transition: all .3s cubic-bezier(.645, .045, .355, 1); // 切换内容时指示器小圆点上的动效 --    } --  } --} 

在入口文件 index.ts 中暴露 CarouselIndicator 子组件出去。

import type { App } from 'vue' import XCarousel from './src/carousel' ++import XCarouselIndicator from './src/components/carousel-indicator' --export { XCarousel } ++export { XCarousel, XCarouselIndicator } export default {   install(app: App) {     app.component(XCarousel.name, XCarousel) ++    app.component(XCarouselIndicator.name, XCarouselIndicator)   } } 

重构之后，默认使用方式依然不变，展示的效果也没有任何差别。

App.vue

<XCarousel>   <div class="carousel-item">page 1</div>   <div class="carousel-item">page 2</div>   <div class="carousel-item">page 3</div> </XCarousel> 

但这个组件灵活性却增加了，我们可以通过 indicator 插槽和 CarouselIndicator 子组件，实现更多的走马灯效果，满足更多的业务场景。

比如：我们可以调整页码指示器的位置

<XCarousel>   <div class="carousel-item">page 1</div>   <div class="carousel-item">page 2</div>   <div class="carousel-item">page 3</div>   <template #indicator="page">     <XCarouselIndicator :count="page.count" v-model="page.pageIndex" @update:modelValue="page.setPageIndex"       style="justify-content: flex-start; padding-left: 20px;">     </XCarouselIndicator>   </template> </XCarousel> 

效果如下：

比如：我们可以自定义自己的指示器

<script setup lang="ts"> const indicatorArr = Array.from(new Array(3).keys()) </script> <template>   <XCarousel>     <div class="carousel-item-dark">page 1</div>     <div class="carousel-item-dark">page 2</div>     <div class="carousel-item-dark">page 3</div>     <template #indicator="page">       <XCarouselIndicator :count="page.count" v-model="page.pageIndex" style="justify-content: flex-start; padding-left: 20px;">         <div           :class="['carousel-indicator-item', page.pageIndex === item+1 ? 'active' : '']"           v-for="item of indicatorArr"           :key="item"           @click="page.setPageIndex(item+1)"         ></div>       </XCarouselIndicator>     </template>   </XCarousel> </template> <style scoped> .carousel-item-dark {   text-align: center;   line-height: 200px;   background: rgb(135, 164, 186);   color: #fff; } .carousel-indicator-item {   position: relative;   display: inline-block;   width: 8px;   height: 8px;   margin: 4px;   border-radius: 50%;   background-color: var(--xui-icon-fill, #d3d5d9);   overflow: hidden;   cursor: pointer; } .carousel-indicator-item.active {   width: 14px;   height: 14px;   margin: 1px;   border-radius: 50%;   background-color: #fff; } </style> 

效果如下： 

我们甚至可以单独使用 CarouselIndicator 组件，实现一个很漂亮的手风琴式折叠卡片效果。

<template>   <XCarouselIndicator>     <template #default="page">     <div class="box">       <div :class="['panel', page.pageIndex === 1 ? 'active' : '']" @click="page.setPageIndex(1)">         <h3>Explore The World</h3>       </div>       <div :class="['panel', page.pageIndex === 2 ? 'active' : '']" @click="page.setPageIndex(2)">         <h3>Wild Forest</h3>       </div>       <div :class="['panel', page.pageIndex === 3 ? 'active' : '']" @click="page.setPageIndex(3)">         <h3>Sunny Beach</h3>       </div>       <div :class="['panel', page.pageIndex === 4 ? 'active' : '']" @click="page.setPageIndex(4)">         <h3>City on Winter</h3>       </div>       <div :class="['panel', page.pageIndex === 5 ? 'active' : '']" @click="page.setPageIndex(5)">         <h3>Mountains - Clouds</h3>       </div>     </div>     </template>   </XCarouselIndicator> </template> <style scoped> .box {   display: flex;   width: 90vw; } .panel {   background-size: cover;   background-position: center;   background-repeat: no-repeat;   height: 40vh;   border-radius: 50px;   color: #fff;   cursor: pointer;   flex: 0.5;   margin: 10px;   position: relative;   -webkit-transition: all 700ms ease-in;   transition: all 700ms ease-in; } .panel:nth-child(1){   background-image: url("https://picsum.photos/1350/900?random=1"); } .panel:nth-child(2){   background-image: url("https://picsum.photos/1350/900?random=2"); } .panel:nth-child(3){   background-image: url("https://picsum.photos/1350/900?random=3"); } .panel:nth-child(4){   background-image: url("https://picsum.photos/1350/900?random=4"); } .panel:nth-child(5){   background-image: url("https://picsum.photos/1350/900?random=5"); } .panel h3 {   font-size: 24px;   position: absolute;   bottom: 20px;   left: 20px;   margin: 0;   opacity: 0; } .panel.active {   flex: 5; } .panel.active h3 {   opacity: 1;   transition: opacity 0.3s ease-in 0.4s; } </style> 

效果如下：

VueCarousel 通过子组件+插槽的设计方式，仅使用 171 行代码就实现了 Carousel 基础功能、调整指示器位置、自定义指示器、手风琴式折叠卡片等效果。

其实组件的很多其他部分也可以外溢出去，包括子组件、内部方法、TypeScript类型等，将这些能力外溢，把自主权交给开发者，可以有效地增加组件的灵活性，让我们设计的组件既是“易用的”，又是“灵活的”，在易用性和灵活性之间取得一定的平衡。

• VueCarousel 组件示例：https://kagol.github.io/vue-carousel/

关于OpenTiny

OpenTiny 是一套企业级 Web 前端开发解决方案，提供跨端、跨框架、跨版本的 TinyVue 组件库，包含基于 Angular+TypeScript 的 TinyNG 组件库，拥有灵活扩展的低代码引擎 TinyEngine，具备主题配置系统TinyTheme / 中后台模板 TinyPro/ TinyCLI 命令行等丰富的效率提升工具，可帮助开发者高效开发 Web 应用。

---

欢迎加入 OpenTiny 开源社区。添加微信小助手：opentiny-official 一起参与交流前端技术～

OpenTiny 官网：https://opentiny.design/
OpenTiny 代码仓库：https://github.com/opentiny/
TinyVue 源码：https://github.com/opentiny/tiny-vue
TinyEngine 源码： https://github.com/opentiny/tiny-engine

欢迎进入代码仓库 Star🌟TinyEngine、TinyVue、TinyNG、TinyCLI~
如果你也想要共建，可以进入代码仓库，找到 good first issue标签，一起参与开源贡献~