Carousel 轮播图 - Docs - Artefact

Carousel 轮播图

Data Display

自动交互

简介

Carousel 组件是一个高性能、基于原生滚动的幻灯片组件，用于在多张幻灯片之间翻页。它专为 CMS 页面构建而生，默认即零 JS 静态渲染，依赖现代 CSS scroll-snap 原语，而非厚重的 JS transform 逻辑。

因此，触摸滑动、触控板滚动以及键盘方向键导航，即便在客户端水合之前也能即时生效。JavaScript 仅在用户点击指示器、上/下一张按钮以及自动播放触发器时，才被优雅地按需叠加。

用法

你可以配置并排序幻灯片、设置展示布局，并控制自动播放属性。

基础幻灯片

标准的图片横幅，采用全宽幻灯片并叠加标题文字与导航链接。非常适合作为首屏头部或主页展示区。

{
  "blockType": "carousel",
  "slides": [
    {
      "image": "https://images.unsplash.com/photo-1551288049-bebda4e38f71?w=800&q=80",
      "caption": "Real-Time Analytics — Pulse delivers live data and dashboards with sub-second streaming latency.",
      "href": "/features/analytics"
    },
    {
      "image": "https://images.unsplash.com/photo-1518186285589-2f7649de83e0?w=800&q=80",
      "caption": "AI-Powered Detection — Smart anomaly detection notifies your team before production breaks.",
      "href": "/features/ai-detection"
    },
    {
      "image": "https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=800&q=80",
      "caption": "Unified Team Workspaces — Share annotated charts and build custom workspaces with ease.",
      "href": "/features/workspaces"
    }
  ]
}

Real-Time Analytics — Pulse delivers live data and dashboards with sub-second streaming latency.

带悬停控制的自动播放横幅

将轮播配置为以设定速度自动前进。为了兼顾界面的无障碍性与低侵入性，可启用 pauseOnHover，让用户只需将指针悬停在幻灯片上即可暂停播放。

{
  "blockType": "carousel",
  "loop": true,
  "pauseOnHover": true,
  "autoplayDelay": 3500,
  "slides": [
    {
      "image": "https://images.unsplash.com/photo-1504384308090-c894fdcc538d?w=800&q=80",
      "caption": "Developer Tools — Integrate your APIs in minutes with our native SDK wrappers.",
      "href": "/developers"
    },
    {
      "image": "https://images.unsplash.com/photo-1526374965328-7f61d4dc18c5?w=800&q=80",
      "caption": "Ironclad Security — SOC2-compliant data storage and end-to-end encryption by default.",
      "href": "/security"
    }
  ]
}

Developer Tools — Integrate your APIs in minutes with our native SDK wrappers.

多张幻灯片布局

同时并排展示多张幻灯片。非常适合产品列表、团队成员目录以及作品集画廊。设置 slidesPerPage 属性，并为各条目指定自定义 spacing 间距。

{
  "blockType": "carousel",
  "slidesPerPage": 2,
  "spacing": "16px",
  "slides": [
    {
      "image": "https://images.unsplash.com/photo-1542744094-3a31f103e35f?w=400&q=80",
      "caption": "Marketing Solutions",
      "href": "/solutions/marketing"
    },
    {
      "image": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=400&q=80",
      "caption": "Financial Growth",
      "href": "/solutions/financial"
    },
    {
      "image": "https://images.unsplash.com/photo-1551836022-d5d88e9218df?w=400&q=80",
      "caption": "HR Management",
      "href": "/solutions/hr"
    },
    {
      "image": "https://images.unsplash.com/photo-1507679799987-c73779587ccf?w=400&q=80",
      "caption": "Executive Advisory",
      "href": "/solutions/consulting"
    }
  ]
}

Card A

Card B

垂直画廊信息流

以垂直方向而非水平方向滚动浏览幻灯片内容。非常适合移动优先的内容卡片、媒体短片流或侧边导航面板。

{
  "blockType": "carousel",
  "orientation": "vertical",
  "slides": [
    {
      "image": "https://images.unsplash.com/photo-1517841905240-472988babdf9?w=800&q=80",
      "caption": "Curated Feed — Category Spotlight"
    },
    {
      "image": "https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=800&q=80",
      "caption": "Trending Creator Profile"
    },
    {
      "image": "https://images.unsplash.com/photo-1506794778202-cad84cf45f1d?w=800&q=80",
      "caption": "Featured Technical Portfolio"
    }
  ]
}

Vertical Item 1

叠加（内联）控件的强调主题

通过 inline 属性让上/下一张触发器与指示点直接浮于图片之上（而非置于其下方），并使用强调色的 colorPalette token 为激活状态的视觉提示着色。

{
  "blockType": "carousel",
  "inline": true,
  "colorPalette": "purple",
  "slides": [
    {
      "image": "https://images.unsplash.com/photo-1507238691740-187a5b1d37b8?w=800&q=80",
      "caption": "Overlay Design Layout"
    },
    {
      "image": "https://images.unsplash.com/photo-1531403009284-440f080d1e12?w=800&q=80",
      "caption": "High Fidelity Previews"
    }
  ]
}

Themed Slide 1

属性

参数	类型	默认值	说明
`slides`	`List`	-	一组有序的单个幻灯片集合（见下方 schema）。
`slidesPerPage`	`Number`	`1`	视口中同时可见的幻灯片数量。
`spacing`	`String`	-	可见幻灯片之间兼容 CSS 的间隙/间距（例如 `"16px"`、`"1rem"`）。
`loop`	`Boolean`	`false`	轮播到达末尾时是否回绕到第一张幻灯片。
`autoplayDelay`	`Number`	-	自动前进的计时器（毫秒）。留空或省略则完全禁用自动播放。
`pauseOnHover`	`Boolean`	`true`	当指针悬停在幻灯片上方时暂停自动播放。
`orientation`	`Select`	`horizontal`	滚动布局方向。可选：`horizontal`、`vertical`。
`inline`	`Boolean`	`false`	将导航控制器与指示点叠加在幻灯片媒体之上，而非放置在下方容器中。
`colorPalette`	`Select`	-	按钮与指示器的视觉强调色。可选：`blue`、`green`、`red`、`purple`、`orange`、`amber`、`cyan`、`slate`。

幻灯片条目 Schema

slides 参数中的每一项均接受以下属性：

属性	类型	必填	说明
`image`	`Image`	是	背景幻灯片图片的路径或 URL。
`caption`	`String`	否	动态渲染在幻灯片下部的叠加描述文字。
`href`	`String`	否	整张幻灯片在点击时触发的导航 URL 或本地化页面路由。

架构说明

SSR 期间零布局偏移： 为消除服务端渲染时的布局跳动，吸附点标记与视口宽度使用与 slideCount 和 slidesPerPage 设置相匹配的可预测结构公式预先计算。
稳健的事件委托： 所有针对指示器、圆点分页与暂停触发器的点击处理器，都通过从根容器委托出来的单一统一事件监听器进行管理。这避免了在水合后的页面模板中，为静态组件重复绑定事件监听器。
CSS Scroll Snap： 纯 CSS scroll-snap 原生处理布局对齐。在移动端触摸屏与现代触控板上，滑动滚动的过渡依然顺滑，即便在 JavaScript 被禁用或延迟时也能正常工作。

Card 卡片

Icon 图标

外观

外观

外观

外观