走马灯 carousel

数据展示组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

张数由 slideCount 声明而不是从 DOM 数，页数与指示点数量都由它算出来

第一张

第二张

第三张

<script setup lang="ts">
import {
  XhCarouselIndicator,
  XhCarouselIndicatorGroup,
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["第一张", "第二张", "第三张"];
</script>

<template>
  <XhCarouselRoot
    v-slot="{ totalPages }"
    :slide-count="slides.length"
    style="inline-size: 100%"
  >
    <XhCarouselPrevTrigger>‹</XhCarouselPrevTrigger>
    <!-- 视口只负责裁切，高度由页面给：不给高度就没有可裁的窗口 -->
    <XhCarouselViewport style="block-size: 140px">
      <XhCarouselItemGroup>
        <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
          <div style="display: grid; place-items: center; block-size: 100%">
            {{ text }}
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselNextTrigger>›</XhCarouselNextTrigger>
    <XhCarouselIndicatorGroup>
      <!-- 指示点一页一个，作者照着 totalPages 渲染 -->
      <XhCarouselIndicator v-for="p in totalPages" :key="p" :index="p - 1" />
    </XhCarouselIndicatorGroup>
  </XhCarouselRoot>
</template>

受控

传了 page 就由宿主说了算，组件只发 page-change 不自己改页码；v-model:page 是它的语法糖

登录

选套餐

付款

当前第 2 张

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["登录", "选套餐", "付款"];
const page = ref(1);
</script>

<template>
  <div style="inline-size: 100%; display: grid; gap: 12px">
    <XhCarouselRoot v-model:page="page" :slide-count="slides.length">
      <XhCarouselPrevTrigger>‹</XhCarouselPrevTrigger>
      <XhCarouselViewport style="block-size: 120px">
        <XhCarouselItemGroup>
          <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
            <div style="display: grid; place-items: center; block-size: 100%">
              {{ text }}
            </div>
          </XhCarouselItem>
        </XhCarouselItemGroup>
      </XhCarouselViewport>
      <XhCarouselNextTrigger>›</XhCarouselNextTrigger>
    </XhCarouselRoot>

    <!-- 页码握在宿主手里，外部按钮直接改它 -->
    <div style="display: flex; align-items: center; gap: 8px">
      <button
        v-for="(text, i) in slides"
        :key="text"
        type="button"
        @click="page = i"
      >
        跳到「{{ text }}」
      </button>
      <span>当前第 {{ page + 1 }} 张</span>
    </div>
  </div>
</template>

一屏多张

slidesPerPage 决定一屏露几张，一次翻几张缺省跟着它走，所以仍是整屏翻

第 一 张

第 二 张

第 三 张

第 四 张

第 五 张

第 六 张

<script setup lang="ts">
import {
  XhCarouselIndicator,
  XhCarouselIndicatorGroup,
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["一", "二", "三", "四", "五", "六"];
</script>

<template>
  <XhCarouselRoot
    v-slot="{ totalPages }"
    :slide-count="slides.length"
    :slides-per-page="2"
    spacing="12px"
    style="inline-size: 100%"
  >
    <!-- 不回绕：首页的上一张与末页的下一张转成原生 disabled -->
    <XhCarouselPrevTrigger>‹</XhCarouselPrevTrigger>
    <XhCarouselViewport style="block-size: 120px">
      <XhCarouselItemGroup>
        <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
          <div style="display: grid; place-items: center; block-size: 100%">
            第 {{ text }} 张
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselNextTrigger>›</XhCarouselNextTrigger>
    <XhCarouselIndicatorGroup>
      <XhCarouselIndicator v-for="p in totalPages" :key="p" :index="p - 1" />
    </XhCarouselIndicatorGroup>
  </XhCarouselRoot>
</template>

自动播放与回绕

autoplay 给毫秒即间隔，鼠标停上去或焦点走进来都会把计时按住

公告一

公告二

公告三

第 1 / 3 页 · 自动播放中

<script setup lang="ts">
import {
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["公告一", "公告二", "公告三"];
</script>

<template>
  <XhCarouselRoot
    v-slot="{ page, totalPages, autoplaying, paused }"
    :slide-count="slides.length"
    :autoplay="2500"
    loop
    style="inline-size: 100%"
  >
    <XhCarouselPrevTrigger>‹</XhCarouselPrevTrigger>
    <XhCarouselViewport style="block-size: 120px">
      <XhCarouselItemGroup>
        <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
          <div style="display: grid; place-items: center; block-size: 100%">
            {{ text }}
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselNextTrigger>›</XhCarouselNextTrigger>
    <!-- root 自己就是会换行的横排 flex，回显想独占一行得自己占满 -->
    <span style="flex-basis: 100%">
      第 {{ page + 1 }} / {{ totalPages }} 页 ·
      {{ autoplaying ? "自动播放中" : paused ? "被按住" : "已停" }}
    </span>
  </XhCarouselRoot>
</template>

纵向轨道

orientation 换成 vertical 后轨道竖着位移，两端按钮落到上下两头，翻页认的是上下方向键

09:00 晨会

11:00 客户沟通

15:00 联调

第 1 / 3 条

<script setup lang="ts">
import {
  XhCarouselIndicator,
  XhCarouselIndicatorGroup,
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["09:00 晨会", "11:00 客户沟通", "15:00 联调"];
</script>

<template>
  <XhCarouselRoot
    v-slot="{ page, totalPages }"
    orientation="vertical"
    :slide-count="slides.length"
    style="inline-size: 240px"
  >
    <XhCarouselPrevTrigger>∧</XhCarouselPrevTrigger>
    <!-- 纵轨的裁切窗口靠高度定，宽度交给根节点 -->
    <XhCarouselViewport style="block-size: 96px; inline-size: 100%">
      <XhCarouselItemGroup>
        <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
          <div style="display: grid; place-items: center; block-size: 100%">
            {{ text }}
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselNextTrigger>∨</XhCarouselNextTrigger>
    <XhCarouselIndicatorGroup>
      <XhCarouselIndicator v-for="p in totalPages" :key="p" :index="p - 1" />
    </XhCarouselIndicatorGroup>
    <span>第 {{ page + 1 }} / {{ totalPages }} 条</span>
  </XhCarouselRoot>
</template>

指针拖拽

allowPointerDrag 打开后按住轨道就能拖着走，松手落回整页；关掉则只有触摸的原生滚动

拖我

再拖

还能拖

最后一张

第 1 / 4 页 · 松手状态

<script setup lang="ts">
import {
  XhCarouselIndicator,
  XhCarouselIndicatorGroup,
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["拖我", "再拖", "还能拖", "最后一张"];
</script>

<template>
  <XhCarouselRoot
    v-slot="{ page, totalPages, dragging }"
    :slide-count="slides.length"
    allow-pointer-drag
    loop
    style="inline-size: 100%"
  >
    <XhCarouselPrevTrigger>‹</XhCarouselPrevTrigger>
    <XhCarouselViewport style="block-size: 130px">
      <XhCarouselItemGroup>
        <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
          <div style="display: grid; place-items: center; block-size: 100%">
            {{ text }}
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselNextTrigger>›</XhCarouselNextTrigger>
    <XhCarouselIndicatorGroup>
      <XhCarouselIndicator v-for="p in totalPages" :key="p" :index="p - 1" />
    </XhCarouselIndicatorGroup>
    <span style="flex-basis: 100%">
      第 {{ page + 1 }} / {{ totalPages }} 页 ·
      {{ dragging ? "正在拖" : "松手状态" }}
    </span>
  </XhCarouselRoot>
</template>

指示点悬停切页

页码由插槽交出的 setPage 说了算，指示点上补一个原生 mouseenter 就是悬停切页，点击照常翻页

城市夜景

海岸线

雪山

沙漠

鼠标扫过下面的圆点即可换页，当前第 1 / 4 页

<script setup lang="ts">
import {
  XhCarouselIndicator,
  XhCarouselIndicatorGroup,
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["城市夜景", "海岸线", "雪山", "沙漠"];
</script>

<template>
  <XhCarouselRoot
    v-slot="{ page, totalPages, setPage }"
    :slide-count="slides.length"
    style="inline-size: 100%"
  >
    <XhCarouselViewport style="block-size: 130px">
      <XhCarouselItemGroup>
        <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
          <div style="display: grid; place-items: center; block-size: 100%">
            {{ text }}
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselIndicatorGroup>
      <!-- mouseenter 是落到指示点按钮上的原生事件，组件自带的点击不受影响 -->
      <XhCarouselIndicator
        v-for="p in totalPages"
        :key="p"
        :index="p - 1"
        @mouseenter="setPage(p - 1)"
      />
    </XhCarouselIndicatorGroup>
    <span style="flex-basis: 100%">
      鼠标扫过下面的圆点即可换页，当前第 {{ page + 1 }} / {{ totalPages }} 页
    </span>
  </XhCarouselRoot>
</template>

一次挪一张

slidesPerMove 与 slidesPerPage 分开给：一屏露三张、一次只挪一张，页数按剩下的张数重新算

A

B

C

D

E

F

第 1 / 4 页 · 眼下露的是第 1 到 3 张

<script setup lang="ts">
import {
  XhCarouselIndicator,
  XhCarouselIndicatorGroup,
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

const slides = ["A", "B", "C", "D", "E", "F"];
</script>

<template>
  <XhCarouselRoot
    v-slot="{ page, totalPages, slideRange }"
    :slide-count="slides.length"
    :slides-per-page="3"
    :slides-per-move="1"
    spacing="10px"
    style="inline-size: 100%"
  >
    <XhCarouselPrevTrigger>‹</XhCarouselPrevTrigger>
    <XhCarouselViewport style="block-size: 110px">
      <XhCarouselItemGroup>
        <XhCarouselItem v-for="(text, i) in slides" :key="text" :index="i">
          <div style="display: grid; place-items: center; block-size: 100%">
            {{ text }}
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselNextTrigger>›</XhCarouselNextTrigger>
    <XhCarouselIndicatorGroup>
      <XhCarouselIndicator v-for="p in totalPages" :key="p" :index="p - 1" />
    </XhCarouselIndicatorGroup>
    <span style="flex-basis: 100%">
      第 {{ page + 1 }} / {{ totalPages }} 页 · 眼下露的是第
      {{ slideRange.start + 1 }} 到 {{ slideRange.end + 1 }} 张
    </span>
  </XhCarouselRoot>
</template>

换过渡效果

条目的内联样式只有尺寸与间距，位移之外的表现全归作者：把条目摞起来再按当前页调透明度与缩放，翻页、键盘与指示点一概照旧

城市夜景

海岸线

雪山

沙漠

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhCarouselIndicator,
  XhCarouselIndicatorGroup,
  XhCarouselItem,
  XhCarouselItemGroup,
  XhCarouselNextTrigger,
  XhCarouselPrevTrigger,
  XhCarouselRoot,
  XhCarouselViewport,
} from "@xihan-ui/vue";

type Effect = "slide" | "fade" | "zoom";

const slides = ["城市夜景", "海岸线", "雪山", "沙漠"];

const options: { key: Effect; label: string }[] = [
  { key: "slide", label: "平移" },
  { key: "fade", label: "淡入" },
  { key: "zoom", label: "缩放淡入" },
];

const effect = ref<Effect>("fade");

// 后两档把条目摞在一起，轨道那条整页位移随之作废
const groupStyle = computed(() =>
  effect.value === "slide" ? undefined : { position: "relative", transform: "none" }
);

function itemStyle(index: number, page: number): Record<string, string> | undefined {
  if (effect.value === "slide") return undefined;
  const current = index === page;
  return {
    position: "absolute",
    inset: "0",
    opacity: current ? "1" : "0",
    scale: effect.value === "zoom" && !current ? "0.9" : "1",
    transition: "opacity 320ms ease, scale 320ms ease",
  };
}
</script>

<template>
  <XhCarouselRoot
    v-slot="{ page, totalPages }"
    :slide-count="slides.length"
    style="inline-size: 100%"
  >
    <XhCarouselPrevTrigger>‹</XhCarouselPrevTrigger>
    <XhCarouselViewport style="block-size: 140px">
      <XhCarouselItemGroup :style="groupStyle">
        <XhCarouselItem
          v-for="(text, i) in slides"
          :key="text"
          :index="i"
          :style="itemStyle(i, page)"
        >
          <div style="display: grid; place-items: center; block-size: 100%">
            {{ text }}
          </div>
        </XhCarouselItem>
      </XhCarouselItemGroup>
    </XhCarouselViewport>
    <XhCarouselNextTrigger>›</XhCarouselNextTrigger>
    <XhCarouselIndicatorGroup>
      <XhCarouselIndicator v-for="p in totalPages" :key="p" :index="p - 1" />
    </XhCarouselIndicatorGroup>
    <div style="flex-basis: 100%; display: flex; justify-content: center; gap: 8px">
      <button
        v-for="opt in options"
        :key="opt.key"
        type="button"
        :aria-pressed="effect === opt.key"
        @click="effect = opt.key"
      >
        {{ opt.label }}
      </button>
    </div>
  </XhCarouselRoot>
</template>

产物

层	值
自定义元素	<xh-carousel>
Vue 组件	XhCarouselIndicator XhCarouselIndicatorGroup XhCarouselItem XhCarouselItemGroup XhCarouselNextTrigger XhCarouselPrevTrigger XhCarouselRoot XhCarouselViewport
组合式函数	useCarousel
状态机	carouselMachine
皮肤	@xihan-ui/styles/carousel.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="carousel"：root · viewport · item-group · item · prev-trigger · next-trigger · indicator-group · indicator

Props

属性	类型	必填	说明
page	number		当前页，0 基。给定即受控：内部不再自改，只发 onPageChange。 页不是张：一页可能同时露出好几张（见 slidesPerPage）。
defaultPage	number		非受控初始页，默认 0。
slideCount	number		条目总数，由作者声明，不从 DOM 数。
slidesPerPage	number		一屏放几张，默认 1。
slidesPerMove	number		一次翻几张，默认跟随 slidesPerPage（整屏翻页）。
orientation	Orientation		轨道方向，默认 horizontal；方向键的轴跟着它走。
dir	Direction		文字方向。水平轴上同时作用于排版与位移方向：rtl 下"下一张"在左手边， 轨道也要往正方向位移。纵向轨道不受它影响。
loop	boolean		走到尽头是否回绕，默认 false。
autoplay	boolean | number		自动播放。true 用默认间隔，数值即毫秒间隔；缺省 / false / 非正数一律不自动播放。 指针悬停或轮播内任一节点获得焦点时按住计时，离开后从头计满一整个间隔再翻。
allowPointerDrag	boolean		允许指针拖拽切页，默认 false。鼠标、触摸、触控笔一并门控。 打开后沿轨道那一轴的原生滚动会让位给拖拽，关掉则完全没有拖拽、触摸走原生滚动。
spacing	string		张与张之间的间距，任意 CSS 长度（如 '12px'）。落成条目自身的内边距，不影响位移算术。
translations	Partial<CarouselTranslations>
onPageChange	(details: CarouselPageChangeDetails) => void		页码变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。

状态机

状态：idle · playing · playing.running · playing.paused

事件：PAGE.SET · PAGE.PREV · PAGE.NEXT · AUTOPLAY.START · AUTOPLAY.STOP · AUTOPLAY.PAUSE · AUTOPLAY.RESUME · after.autoplay · DRAG.START · DRAG.MOVE · DRAG.END

判据：isLastPauseSource · canAdvance · hasAutoplay

connect API

useCarousel 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
page	number	当前页，0 基；恒在 [0, max(totalPages-1, 0)] 内，slideCount 变小后也读得到一个可用的值。
totalPages	number
slideCount	number	归一后的条目总数（负数/小数/缺省都已收成非负整数）。
slidesPerPage	number
slidesPerMove	number
orientation	Orientation
slideRange	{ start: number, end: number }	当前页露出的条目下标区间，0 基闭区间；一张都没有时 end < start。
pageSnapPoints	number[]	每一页的首张下标序列，长度即总页数。
canScrollPrev	boolean
canScrollNext	boolean
autoplaying	boolean	自动播放的计时正在走。
paused	boolean	自动播放开着但被按住（悬停 / 焦点 / 调用方）。
dragging	boolean
isInView	(index: number) => boolean
setPage	(page: number) => void	页码会被收进合法区间（loop 时回绕），越界入参不会写出越界的页。
goToPrev	() => void
goToNext	() => void
play	() => void	开始自动播放；autoplay prop 没给出正的间隔时无事发生。
pause	() => void	按住计时（来源记为 api），与悬停 / 焦点叠加计数。
resume	() => void
getRootProps	() => T['element']
getViewportProps	() => T['element']
getItemGroupProps	() => T['element']
getItemProps	(props: CarouselItemProps) => T['element']
getPrevTriggerProps	() => T['button']
getNextTriggerProps	() => T['button']
getIndicatorGroupProps	() => T['element']
getIndicatorProps	(props: CarouselIndicatorProps) => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowRight	orientation=horizontal，焦点在轮播内	翻到下一页；rtl 下反向（走上一页）
ArrowLeft	orientation=horizontal，焦点在轮播内	翻到上一页；rtl 下反向（走下一页）
ArrowDown	orientation=vertical，焦点在轮播内	翻到下一页；横轨下不接管，放行给页面滚动
ArrowUp	orientation=vertical，焦点在轮播内	翻到上一页；横轨下不接管，放行给页面滚动
Home	焦点在轮播内	跳到第一页
End	焦点在轮播内	跳到最后一页
Enter / Space	焦点在上一张 / 下一张按钮上	翻一页；由原生按钮的激活行为负责
Enter / Space	焦点在指示点上	跳到该指示点对应的页；由原生按钮的激活行为负责
Tab / Shift+Tab	任意时刻	在两端按钮与各指示点之间逐个停靠；到端点后禁用的按钮自动脱序
方向键	焦点在幻灯片内的输入控件上	不接管：交还给控件自己做光标移动