Carousel

在有限区域轮播内容。中文惯用名：轮播。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.carousel`
名称	Carousel
二级分类	数据展示（`data-display`）
用途	在有限区域轮播内容
描述	中文惯用名：轮播。

预览

静态结构：Carousel 基于 vendored embla（data-slot="carousel"）：根容器内为 data-slot="carousel-viewport" 视口，逐项 data-slot="carousel-item"；items 元素为图片对象 { src, alt } 时渲染 w-full object-cover 圆角 <img>，为 DSL 节点时经 renderChildren 渲染。左右两侧为 data-slot="carousel-previous" / "carousel-next" 圆形导航按钮。loop 映射 embla loop；autoplay 以定时器驱动 scrollNext（true 用间隔 3000ms，数字为间隔毫秒数），抵达末尾时 loop 开启则回绕、否则停在末页。

DSL 结构

DslNode

{
  "type": "Carousel",
  "props": {
    "loop": true,
    "autoplay": 3000,
    "items": [
      {
        "src": "https://example.com/banner-ops.png",
        "alt": "运营看板"
      },
      {
        "src": "https://example.com/banner-growth.png",
        "alt": "增长分析"
      },
      {
        "src": "https://example.com/banner-insight.png",
        "alt": "客户洞察"
      }
    ]
  }
}

何时用

何时使用

同一位置轮播多张内容：运营 Banner、活动位、图片展示区。
每屏一个焦点内容、用户顺序浏览即可，不需要并排比较。
图片素材或 DSL 子树需要按序轮播（items 两种形态可混排）。

何时不用

需要并排比较、全部可见：使用 Gallery 或 Grid 平铺，轮播会隐藏大部分内容。
单张图片展示：直接使用 Image；放大与切换查看：使用 ImageViewer。
内容需要被检索 / 深链定位：轮播项默认不可直达，应改用列表 + 详情页。

变体

变体	视觉形态	适用场景
默认（手动切换）	单屏一项 + 左右圆形导航按钮	用户自主浏览的图片 / 内容轮播
loop 循环	末项之后回到首项	数量不多、希望连续浏览的轮播
autoplay 自动播放	按间隔自动切换到下一项（true 为 3000ms）	展示型 Banner，无需用户操作
DSL 子树项	轮播项由 DSL 节点渲染（非图片）	轮播内需要卡片、图文组合等复杂内容

API 属性

属性	类型	默认值	说明
`items`	`CarouselItemData[]`	[]	轮播项：图片 { src, alt? } 对象或 DSL 子树（经 renderChildren 渲染），可混排
`loop`	`boolean`	false	循环滚动；同时作用于手动切换与 autoplay 的回绕行为
`autoplay`	`boolean	number`	—
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式

使用规范

轮播项数量控制在 3-5 个：隐藏内容越多，用户越可能完全错过；必要时提供指示或缩略导航。
autoplay 间隔不宜过快（建议 ≥3000ms），且必须让用户能暂停或手动切换；正文信息不要只放在自动轮播中。
图片项务必提供 alt（缺省为空字符串），既是无障碍替代文本也是加载失败时的上下文。
切换是瞬时的，无过渡时长配置；不要用轮播承载必须被完整阅读的内容。
items 混排图片与 DSL 子树时保证每项高度一致，否则容器高度会随项跳动。

正例

✓ 首页 Banner：3 张运营图 + loop + autoplay={5000}，用户可点箭头手动切换。
✓ 图文推荐位：items 传 DSL 子树（Image + Text + Button 组合），与页面同一渲染路径。
✓ 内容区展示：loop 开启但关闭 autoplay，由用户自主浏览。

反例

✕ 用轮播承载需要被检索 / 深链定位的内容（应改用列表 + 详情页）。
✕ autoplay 间隔设为 1000ms 且不可暂停，用户来不及阅读。
✕ 轮播项高度不一致又不给约束，切换时容器高度反复跳动。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。