# Carousel 轮播用于在同一可视区域循环展示多屏内容，支持手动切换与自动播放。 ## 基础用法

第一屏

第二屏

第三屏

点击底部圆点可切换屏幕，默认不自动播放。触屏适配：箭头 / 暂停钮在触控（coarse pointer）下命中区扩到 44px（钮体放大、图标不变）；指示圆点视觉保持 12px，以透明热区扩到 44px，圆点间距同步放大防相邻热区重叠误触。 ## 指定起始索引

第一屏

第二屏

第三屏

通过 `index` 指定当前屏（从 0 开始）。 ## 自动播放

自动 1

自动 2

自动 3

设置 `autoplay` 开启自动播放，`interval` 控制间隔（毫秒）。 ## 箭头形态左右箭头支持三种显示形态，通过 `arrows` 属性控制：`always`（始终显示）/ `hover`（悬停显示，默认）/ `never`（不显示）。箭头点击切换上一屏 / 下一屏，首尾循环。

第一屏

第二屏

第三屏

第一屏

第二屏

第三屏

第一屏

第二屏

第三屏

默认（未指定 `arrows`）即悬停显示形态：箭头默认隐藏，鼠标悬停或键盘聚焦轮播区域时平滑淡入。不指定 `arrows` 时等价于 `arrows="hover"`。 ## 图片轮播轮播项不局限于色块——放 `` 或 SVG 即成图片 banner。

## 事件

第一屏

第二屏

第三屏

当前屏：1

## 指示器指示器支持隐藏、外挂与线性形态三种定制，通过 `indicators` / `indicator-position` / `indicator-type` 控制。圆点颜色走组件级 CSS 变量 `--oas-carousel-dot-bg` / `--oas-carousel-dot-active-bg`（默认白色系，适配深色轮播项；浅色轮播项可在宿主覆盖）。

第一屏

第二屏

第三屏

第一屏

第二屏

第三屏

第一屏

第二屏

第三屏

## 淡出淡入设置 `effect="fade"` 切换为全屏叠层淡入淡出（默认 `slide` 位移切换）。`prefers-reduced-motion` 下自动退化为即时切换。

淡入淡出 1

淡入淡出 2

淡入淡出 3

## 切换方法组件暴露 `next()` / `prev()` / `goTo(index)` 命令式方法，配合 `oas-change` 事件（`detail` 含 `index` 与 `prevIndex`）可实现缩略图控制主轮播等自定义交互。

第一屏

第二屏

第三屏

上一屏

下一屏

跳到第 3 屏

## 循环开关默认首尾循环；设置 `loop="false"` 后到头即停（首屏禁用上一箭头、末屏禁用下一箭头），适用于分步引导、末尾带操作区的场景。

第一步

第二步

第三步（最后）

## 自动播放暂停自动播放时，悬停或键盘聚焦轮播区域即暂停，移开恢复；页面切到后台自动停播，回到前台继续（满足 WCAG 2.2.2 暂停要求）。可用 `pause-on-hover="false"` 关闭悬停暂停。

悬停我试试 1

悬停我试试 2

悬停我试试 3

鼠标悬停（或 Tab 聚焦）上方轮播区域，自动播放会暂停在当前屏；移开后从下一拍继续。

悬停也不停 1

悬停也不停 2

悬停也不停 3

## 垂直轮播设置 `direction="vertical"` 沿纵向切换。垂直模式视口默认高度 200px，可用 CSS 变量 `--oas-carousel-height` 覆盖；指示器自动移到右侧，箭头旋转 90°。

第一屏

第二屏

第三屏

## 一屏多项 `slides-per-view` 设置每屏展示的轮播项数，`gap` 设置项间距（px）；指示器与步进按「页」语义（一组一项）。最后一页不足一组时对齐轨道末尾，不露出空白。

图 1

图 2

图 3

图 4

## 拖拽切换在轮播区域按下并左右（垂直模式下上下）拖动即跟手滑动，超过阈值（视口 25%，或快速轻扫）松手切换，未达阈值回弹。触摸与鼠标统一走 Pointer Events；水平拖拽放行页面纵向滚动（`touch-action: pan-y`），不与页面滚动手势冲突。拖拽中暂停过渡动画，松手恢复；拖拽结束后自动播放计时会重置。拖拽默认**按设备开启**：触摸设备（`pointer: coarse`）默认可拖拽，PC 默认关闭。加 `draggable` 属性可在 PC 显式开启；`draggable="false"` 可在触摸设备显式关闭。

拖我到左边 1

拖我到左边 2

拖我到左边 3

当前屏：1（拖动跟手，松手切屏或回弹）

## 卡片模式设置 `type="card"` 切换为卡片式轮播：当前卡居中为主体（默认占宽 60%），左右邻卡两侧部分露出并缩小降透明；点击任一邻卡直接切到该卡，焦点在轮播项内时也可用方向键切换。非循环模式（`loop="false"`）下首尾屏贴边展示——首屏贴左露出右邻卡、末屏贴右露出左邻卡，边界不悬空。卡宽、卡间距、邻卡缩放分别走 CSS 变量 `--oas-carousel-card-width` / `--oas-carousel-card-gap` / `--oas-carousel-card-scale`。卡片模式仅水平方向生效，与 `slides-per-view` / `effect` / `direction` 互斥（同时设置时卡片模式优先），arrows / indicators / autoplay / 拖拽 / loop 均可组合使用。

卡片 1

卡片 2

卡片 3

卡片 4

卡片 5

## 显式暂停按钮自动播放除悬停/聚焦自动暂停外，还可通过 `pause-button` 显示一个显式暂停/播放按钮（固定在右上角）。显式暂停优先级最高——暂停后即使移开鼠标也不会自动继续；未开启 `autoplay` 时点击「播放」会自动开启自动播放。按钮的 `aria-pressed` 与文案随暂停态同步。

点右上角按钮暂停 1

点右上角按钮暂停 2

点右上角按钮暂停 3

## 指示器触发方式 `trigger` 控制指示器切换时机：`click`（默认，点击切页）/ `hover`（悬停即切页，click 仍可用）；非法值回落 `click`。适合图片轮播快速浏览场景。

第 1 屏（悬停指示器试试）

第 2 屏

第 3 屏

## 缩略图指示器（thumbs） `thumbs` 用缩略图条替代圆点：每个缩略图取子项内 `` 的 `src`、子项 `data-thumb` 属性，或 `thumbs` 属性给出的 JSON 数组 URL（优先级：数组 > `data-thumb` > ``）；均无时渲染序号占位。当前项以主色描边高亮，点击缩略图切页，键盘导航与 `trigger` 触发方式与圆点一致。

第一屏

第二屏

第三屏

## API ### oas-carousel #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `arrows` | 箭头显示形态：`always`（始终显示）/ `hover`（悬停显示）/ `never`（不显示） | `string` | `hover` | | `autoplay` | 是否自动播放 | `boolean` | — | | `direction` | 轮播方向：`horizontal`（默认）/ `vertical`（垂直模式视口定高，走 `--oas-carousel-height`） | `string` | `horizontal` | | `draggable` | 指针拖拽/触摸滑动切换：视口 25% 或速度阈值翻页否则回弹；触摸设备默认开、PC 默认关，`"false"` 显式关闭 | `string` | — | | `effect` | 切换效果：`slide`（默认滑动）/ `fade`（叠层淡入淡出，reduced-motion 退化为直切） | `string` | `slide` | | `gap` | 多图一屏时屏间间距（px，配合 `slides-per-view`） | `string` | `0` | | `index` | 当前屏索引（从 0 起） | `string` | `0` | | `indicator-position` | 指示器位置：`inside`（默认，叠在内容上）/ `outside`（流内占位撑高容器） | `string` | `inside` | | `indicator-type` | 指示器形态：`dot`（默认圆点）/ `line`（线条，激活加宽） | `string` | `dot` | | `indicators` | 指示器开关（默认 true；`"false"` 隐藏） | `string` | `true` | | `interval` | 自动播放间隔（ms） | `string` | `3000` | | `loop` | 循环切换（默认开；`"false"` 时到边界停驻并禁用对应箭头） | `string` | — | | `pause-button` | 显示显式暂停/播放按钮（默认关；点击切换自动播放暂停/继续，优先级高于悬停暂停；未开启 autoplay 时点击播放即开启） | `boolean` | — | | `pause-on-hover` | 自动播放时悬停/聚焦暂停（默认 true；`"false"` 关闭；页面切后台恒停播） | `string` | `true` | | `slides-per-view` | 每屏展示屏数（默认 1；索引语义为页，末页对齐轨道末尾不露空白） | `string` | `1` | | `thumbs` | 缩略图指示器替代圆点（JSON 数组/data-thumb/子项 img 取源；当前项主色描边） | `string` | — | | `trigger` | 指示器切换时机：`click`（默认）/ `hover`（悬停即切，click 仍可用） | `string` | `click` | | `type` | 轮播形态：`"card"` 为卡片模式——当前卡居中为主体、左右邻卡露出缩小降透明，点击邻卡直接切换；与 `slides-per-view`/`effect`/`direction` 互斥（卡片模式优先），卡宽/卡间距/邻卡缩放走 `--oas-carousel-card-width` / `--oas-carousel-card-gap` / `--oas-carousel-card-scale` | `string` | — | #### 事件 | 事件 | 说明 | | --- | --- | | `oas-change` | 当前屏切换，`detail: { index }` | #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 轮播项 | #### CSS 变量 | CSS 变量 | 默认值 | | --- | --- | | `--oas-carousel-card-gap` | `var(--oas-space-3)` | | `--oas-carousel-card-scale` | `0.85` | | `--oas-carousel-card-width` | `60%` | | `--oas-carousel-dot-active-bg` | `#ffffff` | | `--oas-carousel-dot-bg` | `rgba(255, 255, 255, 0.5)` | | `--oas-carousel-height` | `200px` | ### 部件（::part()） | 部件 | 说明 | | --------------------------- | ------------------------------------------------------------ | | `viewport` / `track` | 视口与滑动轨道 | | `dots` / `dot` | 底部指示器容器与单个圆点 | | `arrow-prev` / `arrow-next` | 左右切换箭头按钮，绝对定位于轮播两侧垂直居中，可单独定制样式 | | `pause-button` | 自动播放暂停/继续按钮 | | `thumb` | thumbs 缩略图导航项 |