Sakana Element

简体中文

English

简体中文

English

主题

Carousel 走马灯 ​

用于循环展示内容幻灯片的走马灯组件，具有像素风格。

?
名称分类说明类型默认值
direction? 风格轮播方向'horizontal' | 'vertical''horizontal'
show-arrow? 风格箭头显示策略'always' | 'hover' | 'never''hover'
show-indicators? 风格是否显示指示器booleantrue
height? 风格容器高度string—
color? 颜色颜色主题，支持预设名称（primary / success / warning / danger / info）或自定义十六进制颜色string—
indicator-trigger? 行为指示器触发方式'click' | 'hover''click'
model-value / v-model? 内容当前激活的幻灯片索引number0
change? 事件幻灯片切换时触发(current: number, prev: number) => void—
default? 插槽轮播内容，应包含 CarouselItem 组件—
CarouselItemdefault? 插槽幻灯片内容—
next? 暴露切换到下一张幻灯片() => void—
prev? 暴露切换到上一张幻灯片() => void—
goTo? 暴露跳转到指定幻灯片(index: number) => void—

基础用法 ​

一个包含多张幻灯片的简单走马灯。使用方向键或点击导航箭头和指示器切换幻灯片。

<template>
  <px-carousel height="200px">
    <px-carousel-item v-for="i in 4" :key="i">
      <div
        :style="{
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '24px',
          fontWeight: 'bold',
          background: `var(--px-color-primary-light-${i + 5})`,
          color: 'var(--px-text-color-primary)',
        }"
      >
        Slide {{ i }}
      </div>
    </px-carousel-item>
  </px-carousel>
</template>

垂直方向 ​

设置 direction="vertical" 实现垂直滚动的走马灯。需要固定的 height。

<template>
  <px-carousel height="200px" direction="vertical">
    <px-carousel-item v-for="i in 4" :key="i">
      <div
        :style="{
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '24px',
          fontWeight: 'bold',
          background: `var(--px-color-warning-light-${i + 5})`,
          color: 'var(--px-text-color-primary)',
        }"
      >
        Slide {{ i }}
      </div>
    </px-carousel-item>
  </px-carousel>
</template>

指示器触发方式 ​

使用 indicator-trigger 控制指示器响应 click（默认）还是 hover。

<script setup>
import { ref } from 'vue';

const trigger = ref('click');
</script>

<template>
  <div style="margin-bottom: 12px">
    <label>
      <input type="radio" value="click" v-model="trigger" /> Click
    </label>
    <label style="margin-left: 12px">
      <input type="radio" value="hover" v-model="trigger" /> Hover
    </label>
  </div>
  <px-carousel height="200px" :indicator-trigger="trigger">
    <px-carousel-item v-for="i in 4" :key="i">
      <div
        :style="{
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '24px',
          fontWeight: 'bold',
          background: `var(--px-color-info-light-${i + 5})`,
          color: 'var(--px-text-color-primary)',
        }"
      >
        Slide {{ i }}
      </div>
    </px-carousel-item>
  </px-carousel>
</template>

箭头显示 ​

通过 show-arrow 控制导航箭头的显示时机：always、hover（默认）或 never。

<script setup>
import { ref } from 'vue';

const showArrow = ref('hover');
</script>

<template>
  <div style="margin-bottom: 12px">
    <label>
      <input type="radio" value="always" v-model="showArrow" /> Always
    </label>
    <label style="margin-left: 12px">
      <input type="radio" value="hover" v-model="showArrow" /> Hover
    </label>
    <label style="margin-left: 12px">
      <input type="radio" value="never" v-model="showArrow" /> Never
    </label>
  </div>
  <px-carousel height="200px" :show-arrow="showArrow">
    <px-carousel-item v-for="i in 3" :key="i">
      <div
        :style="{
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '24px',
          fontWeight: 'bold',
          background: `var(--px-color-danger-light-${i + 5})`,
          color: 'var(--px-text-color-primary)',
        }"
      >
        Slide {{ i }}
      </div>
    </px-carousel-item>
  </px-carousel>
</template>

颜色变体 ​

使用 color 属性搭配预设名称或自定义十六进制颜色来设置走马灯的边框、阴影、箭头和指示器样式。

<script setup>
import { ref } from 'vue';

const color = ref('primary');
const colors = ['primary', 'success', 'warning', 'danger', 'info'];
</script>

<template>
  <div style="margin-bottom: 12px; display: flex; gap: 8px">
    <px-button
      v-for="c in colors"
      :key="c"
      :type="c"
      :plain="color !== c"
      size="small"
      @click="color = c"
    >
      {{ c }}
    </px-button>
  </div>
  <px-carousel height="200px" :color="color">
    <px-carousel-item v-for="i in 4" :key="i">
      <div
        :style="{
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '24px',
          fontWeight: 'bold',
          background: `var(--px-fill-color-light)`,
          color: 'var(--px-text-color-primary)',
        }"
      >
        Slide {{ i }}
      </div>
    </px-carousel-item>
  </px-carousel>
</template>

编程式导航 ​

通过模板引用访问 next()、prev() 和 goTo(index) 方法进行编程式控制。

<script setup>
import { ref } from 'vue';

const carouselRef = ref();
const current = ref(0);
</script>

<template>
  <div style="margin-bottom: 12px; display: flex; gap: 8px">
    <px-button @click="carouselRef?.prev()">Prev</px-button>
    <px-button @click="carouselRef?.next()">Next</px-button>
    <px-button @click="carouselRef?.goTo(0)">Go to 1</px-button>
    <px-button @click="carouselRef?.goTo(2)">Go to 3</px-button>
    <span style="line-height: 32px; margin-left: 8px">Current: {{ current }}</span>
  </div>
  <px-carousel ref="carouselRef" v-model="current" height="200px" show-arrow="always">
    <px-carousel-item v-for="i in 4" :key="i">
      <div
        :style="{
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '24px',
          fontWeight: 'bold',
          background: `var(--px-color-info-light-${i + 5})`,
          color: 'var(--px-text-color-primary)',
        }"
      >
        Slide {{ i }}
      </div>
    </px-carousel-item>
  </px-carousel>
</template>