FxCarousel 走马灯

在有限空间内循环展示一系列图片或文字。不依赖任何 UI 框架。

FxCarousel 属于 @fx/components。

基础用法

FxCarousel 与 FxCarouselItem 组合即可得到一个走马灯。每一屏的内容完全自定义，只需放在 FxCarouselItem 标签内。默认情况下，鼠标 hover 到指示器时切换；将 trigger 设为 click，则仅在点击指示器时切换。

<template>
  <div class="demo-carousel">
    <p class="demo-label">指示器 hover 触发（默认）</p>
    <FxCarousel height="150px">
      <FxCarouselItem v-for="item in 4" :key="item">
        <h3 class="demo-item">{{ item }}</h3>
      </FxCarouselItem>
    </FxCarousel>
    <p class="demo-label">指示器 click 触发</p>
    <FxCarousel height="150px" trigger="click">
      <FxCarouselItem v-for="item in 4" :key="item">
        <h3 class="demo-item">{{ item }}</h3>
      </FxCarouselItem>
    </FxCarousel>
  </div>
</template>

<script setup lang="ts">
import { FxCarousel, FxCarouselItem } from "@fx/components"
</script>

<style scoped>
.demo-carousel {
  text-align: center;
}
.demo-label {
  margin: 12px 0 8px;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
}
.demo-item {
  margin: 0;
  color: #475669;
  opacity: 0.75;
  line-height: 150px;
  text-align: center;
  font-size: 20px;
}
.demo-carousel :deep(.fx-carousel__item:nth-child(2n)) {
  background-color: #99a9bf;
}
.demo-carousel :deep(.fx-carousel__item:nth-child(2n + 1)) {
  background-color: #d3dce6;
}
</style>

动态模糊

为走马灯加入动态模糊，使其更具动感与流畅度。

<template>
  <div class="demo-carousel">
    <p class="demo-label">水平方向动态模糊</p>
    <FxCarousel height="200px" motion-blur>
      <FxCarouselItem v-for="item in 4" :key="item">
        <h3 class="demo-item">{{ item }}</h3>
      </FxCarouselItem>
    </FxCarousel>
    <p class="demo-label">垂直方向动态模糊</p>
    <FxCarousel
      height="200px"
      direction="vertical"
      motion-blur
      :autoplay="false"
    >
      <FxCarouselItem v-for="item in 4" :key="item">
        <h3 class="demo-item">{{ item }}</h3>
      </FxCarouselItem>
    </FxCarousel>
  </div>
</template>

<script setup lang="ts">
import { FxCarousel, FxCarouselItem } from "@fx/components"
</script>

<style scoped>
.demo-carousel {
  text-align: center;
}
.demo-label {
  margin: 12px 0 8px;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
}
.demo-item {
  margin: 0;
  color: #475669;
  opacity: 0.75;
  line-height: 200px;
  text-align: center;
  font-size: 20px;
}
:deep(.fx-carousel__item:nth-child(2n)) {
  background-color: #99a9bf;
}
:deep(.fx-carousel__item:nth-child(2n + 1)) {
  background-color: #d3dce6;
}
</style>

开启动态模糊可增强走马灯的动感与流畅度。motion-blur 默认为 false，开启后会在切换瞬间叠加高斯模糊滤镜，提供更具视觉吸引力的体验（水平与垂直方向均支持）。

指示器

指示器可以显示在走马灯外部。

indicator-position 属性决定指示器的位置：默认在走马灯内部，设为 outside 移到外部，设为 none 隐藏指示器。

<template>
  <FxCarousel indicator-position="outside">
    <FxCarouselItem v-for="item in 4" :key="item">
      <h3 class="demo-item">{{ item }}</h3>
    </FxCarouselItem>
  </FxCarousel>
</template>

<script setup lang="ts">
import { FxCarousel, FxCarouselItem } from "@fx/components"
</script>

<style scoped>
.demo-item {
  margin: 0;
  display: flex;
  color: #475669;
  opacity: 0.75;
  line-height: 300px;
  align-items: center;
  justify-content: center;
  font-size: 20px;
}
:deep(.fx-carousel__item:nth-child(2n)) {
  background-color: #99a9bf;
}
:deep(.fx-carousel__item:nth-child(2n + 1)) {
  background-color: #d3dce6;
}
</style>

箭头

可以定义箭头何时显示。

arrow 属性决定箭头的显示时机：默认在鼠标 hover 到走马灯上时出现，设为 always 始终显示，设为 never 永久隐藏。

<template>
  <FxCarousel :interval="5000" arrow="always">
    <FxCarouselItem v-for="item in 4" :key="item">
      <h3 class="demo-item">{{ item }}</h3>
    </FxCarouselItem>
  </FxCarousel>
</template>

<script setup lang="ts">
import { FxCarousel, FxCarouselItem } from "@fx/components"
</script>

<style scoped>
.demo-item {
  margin: 0;
  color: #475669;
  opacity: 0.75;
  line-height: 300px;
  text-align: center;
  font-size: 20px;
}
:deep(.fx-carousel__item:nth-child(2n)) {
  background-color: #99a9bf;
}
:deep(.fx-carousel__item:nth-child(2n + 1)) {
  background-color: #d3dce6;
}
</style>

自适应高度

当 height 设为 auto 时，走马灯高度会根据当前 FxCarouselItem 的高度自动决定。

<template>
  <div class="demo-carousel">
    <p class="demo-label">每个子项高度不同，容器自适应</p>
    <FxCarousel height="auto" autoplay>
      <FxCarouselItem style="height: 100px">
        <h3 class="demo-item">height 100px</h3>
      </FxCarouselItem>
      <FxCarouselItem style="height: 200px">
        <h3 class="demo-item">height 200px</h3>
      </FxCarouselItem>
      <FxCarouselItem style="height: 300px">
        <h3 class="demo-item">height 300px</h3>
      </FxCarouselItem>
    </FxCarousel>
  </div>
</template>

<script setup lang="ts">
import { FxCarousel, FxCarouselItem } from "@fx/components"
</script>

<style scoped>
.demo-carousel {
  text-align: center;
  height: 300px
}
.demo-label {
  margin: 0 0 8px;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
}
.demo-item {
  margin: 0;
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100%;
  color: #475669;
  opacity: 0.75;
  text-align: center;
  font-size: 20px;
}
:deep(.fx-carousel__item:nth-child(2n)) {
  background-color: #99a9bf;
}
:deep(.fx-carousel__item:nth-child(2n + 1)) {
  background-color: #d3dce6;
}
</style>

卡片化

当页面宽度足够但高度有限时，可以为走马灯开启卡片化模式。

将 type 设为 card 即可开启卡片模式。除了外观差异，卡片模式与普通模式最大的不同是：在卡片模式下，直接点击两侧的幻灯片即可切换走马灯。card-scale 控制两侧卡片的缩放比例（默认 0.83）。

<template>
  <FxCarousel :interval="4000" type="card" height="200px">
    <FxCarouselItem v-for="item in 6" :key="item">
      <h3 class="demo-item">{{ item }}</h3>
    </FxCarouselItem>
  </FxCarousel>
</template>

<script setup lang="ts">
import { FxCarousel, FxCarouselItem } from "@fx/components"
</script>

<style scoped>
.demo-item {
  margin: 0;
  color: #475669;
  opacity: 0.75;
  line-height: 200px;
  text-align: center;
  font-size: 20px;
}
:deep(.fx-carousel__item:nth-child(2n)) {
  background-color: #99a9bf;
}
:deep(.fx-carousel__item:nth-child(2n + 1)) {
  background-color: #d3dce6;
}
</style>

垂直方向

默认 direction 为 horizontal。将 direction 设为 vertical 可让走马灯沿垂直方向展示（卡片化同样支持垂直方向）。

<template>
  <div class="demo-carousel">
    <p class="demo-label">普通垂直布局</p>
    <FxCarousel height="200px" direction="vertical" :autoplay="false">
      <FxCarouselItem v-for="item in 4" :key="item">
        <h3 class="demo-item">{{ item }}</h3>
      </FxCarouselItem>
    </FxCarousel>
    <p class="demo-label">卡片化垂直布局</p>
    <FxCarousel
      height="400px"
      direction="vertical"
      type="card"
      :autoplay="false"
    >
      <FxCarouselItem v-for="item in 4" :key="item">
        <h3 class="demo-item">{{ item }}</h3>
      </FxCarouselItem>
    </FxCarousel>
  </div>
</template>

<script setup lang="ts">
import { FxCarousel, FxCarouselItem } from "@fx/components"
</script>

<style scoped>
.demo-carousel {
  text-align: center;
}
.demo-label {
  margin: 12px 0 8px;
  color: var(--fx-text-color-secondary);
  font-size: 14px;
}
.demo-item {
  margin: 0;
  color: #475669;
  opacity: 0.75;
  line-height: 200px;
  text-align: center;
  font-size: 20px;
}
:deep(.fx-carousel__item:nth-child(2n)) {
  background-color: #99a9bf;
}
:deep(.fx-carousel__item:nth-child(2n + 1)) {
  background-color: #d3dce6;
}
</style>

局部引入

import { FxCarousel, FxCarouselItem } from "@fx/components"

FxCarousel API

Attributes

属性	说明	类型	默认值
height	走马灯高度（传 'auto' 自适应）	string	''
initial-index	初始激活项索引（从 0 开始）	number	0
trigger	指示器触发方式	'hover' | 'click'	hover
autoplay	是否自动循环切换	boolean	true
interval	自动切换间隔（ms）	number	3000
indicator-position	指示器位置	'' | 'none' | 'outside'	''
arrow	箭头显示时机	'always' | 'hover' | 'never'	hover
type	走马灯类型	'' | 'card'	''
card-scale	卡片化时两侧卡片缩放比例	number	0.83
loop	是否循环展示	boolean	true
direction	展示方向	'horizontal' | 'vertical'	horizontal
pause-on-hover	hover 时是否暂停自动切换	boolean	true
motion-blur	是否为切换注入动态模糊	boolean	false

Events

名称	说明	类型
change	激活项切换时触发，参数依次为新激活项索引、原激活项索引	(current: number, prev: number) => void

Slots

插槽名	说明	子标签
default	自定义默认内容	FxCarouselItem

Exposes

名称	说明	类型
active-index	当前激活项索引	number
set-active-item	手动切换到指定项，参数为从 0 开始的索引，或对应 FxCarouselItem 的 name	(index: number | string) => void
prev	切换到上一张	() => void
next	切换到下一张	() => void

FxCarouselItem API

Attributes

属性	说明	类型	默认值
name	item 名称，可用于 setActiveItem 定位	string	''
label	对应指示器的文本内容	string | number	''

Slots

插槽名	说明
default	自定义默认内容

实现说明

• 子项通过 useOrderedChildren + provide/inject 自注册，父容器按 DOM 顺序收集
• 箭头使用 FxIcon（@fx-core/icon），图标名 ep:arrow-left / ep:arrow-right
• motion-blur 通过内嵌隐藏 <svg><defs><filter> 的高斯模糊滤镜 + transitionstart/end 加减 .fx-transitioning class 实现
• 样式走 @fx/styles token（过渡 --duration-*、圆角 --radius-full），carousel 专属视觉值（箭头尺寸、指示器尺寸）作为局部 CSS 变量定义在 .fx-carousel 上，可在业务层覆盖
• 2 项 + loop 时自动克隆渲染，避免切换穿透